Unreal Horde Source Build Documentation with ARM64 Support by cwwalb · Pull Request #813 · aws-games/cloud-game-development-toolkit

cwwalb · 2025-12-13T01:02:51Z

Issue number:
closes #743

Summary

Changes

Please provide a summary of what's being changed

User experience

Please share what the user experience looks like before and after this change

Checklist

If your change doesn't seem to apply, please leave them unchecked.

I have performed a self-review of this change
Changes have been tested
Changes are documented

Is this a breaking change?

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created might not be successful.

hwkiem

Great PR. A few minor changes and a couple discussions for the team.

hwkiem · 2025-12-17T17:11:01Z

modules/unreal/horde/ecs.tf

+      }, var.github_credentials_secret_arn != null && !var.is_source_build ? {
+      repositoryCredentials = {
+        "credentialsParameter" : var.github_credentials_secret_arn
+      }
+      } : {}, {


Could move some of this logic to a local

hwkiem · 2025-12-17T17:11:32Z

modules/unreal/horde/ecs.tf

    {
      name                     = "unreal-horde-docdb-cert",
-      image                    = "public.ecr.aws/docker/library/bash:5.3",
+      image                    = "public.ecr.aws/docker/library/bash:latest",


It is probably safer to pin to a specific version of bash. :latest opens us up to upstream issues

I know we do this elsewhere... probably should open an issue and fix those too.

hwkiem · 2025-12-17T17:12:22Z

modules/unreal/horde/ecs.tf

    local.need_p4_trust ? [{
      name      = "unreal-horde-p4-trust",
-      image     = "ubuntu:noble"
+      image     = "public.ecr.aws/ubuntu/ubuntu:noble"


nice fix. I wonder if we should also pin this release to a particular version for the same reason as above.

hwkiem · 2025-12-17T17:12:54Z

modules/unreal/horde/source-build/README.md

Do you think we should put this in a nested directory like this? Or just update the Horde README with these instructions?

hwkiem · 2025-12-17T17:16:00Z

modules/unreal/horde/source-build/README.md

+### For devices using ARM64 architecture
+1. In an IDE, open the Horde Server Dockerfile located at `/Engine/Source/Programs/Horde/HordeServer/Dockerfile`.
+2. Replace the code between `COPY --from=redis /usr/local/bin/redis-server /usr/local/bin/redis-server` and `COPY Source/Programs/Shared/EpicGames.Core/*.csproj ./Source/Programs/Shared/EpicGames.Core/` with the following:
+
+    ```dockerfile
+    # Since the .deb does not install in this image, just download it and extract the static binary
+    RUN ARCH=$(dpkg --print-architecture) && \
+        if [ "$ARCH" = "arm64" ]; then \
+            wget https://repo.mongodb.org/apt/ubuntu/dists/jammy/mongodb-org/7.0/multiverse/binary-arm64/mongodb-org-server_7.0.4_arm64.deb && \
+            dpkg -x mongodb-org-server_7.0.4_arm64.deb /tmp/mongodb; \
+        else \
+            wget https://repo.mongodb.org/apt/debian/dists/bookworm/mongodb-org/7.0/main/binary-amd64/mongodb-org-server_7.0.4_amd64.deb && \
+            dpkg -x mongodb-org-server_7.0.4_amd64.deb /tmp/mongodb; \
+        fi && \
+        cp /tmp/mongodb/usr/bin/mongod /usr/local/bin/mongod
+    ```
+3. Locate the code block with the comment `# Remove native libs not used on Linux x86_64`. We need to modify this so that the build has the libraries associated with the operating system and CPU architecture we are using. To do this, replace that block with the following:
+```dockerfile
+# Remove native libs not used for current architecture
+RUN ARCH=$(dpkg --print-architecture) && \
+    if [ "$ARCH" = "amd64" ]; then \
+        rm -rf /app/out/runtimes/osx* && \
+        rm -rf /app/out/runtimes/win-x86 && \
+        rm -rf /app/out/runtimes/win-arm* && \
+        rm -rf /app/out/runtimes/linux-arm* && \
+        rm -rf /app/out/runtimes/linux-x86 && \
+        rm -rf /app/out/runtimes/linux/native/libgrpc_csharp_ext.x86.so; \
+    elif [ "$ARCH" = "arm64" ]; then \
+        rm -rf /app/out/runtimes/osx-x64 && \
+        rm -rf /app/out/runtimes/win-x64 && \
+        rm -rf /app/out/runtimes/win-x86 && \
+        rm -rf /app/out/runtimes/linux-x64* && \
+        rm -rf /app/out/runtimes/linux-x86 && \
+        rm -rf /app/out/runtimes/linux/native/libgrpc_csharp_ext.x64.so && \
+        rm -rf /app/out/runtimes/linux/native/libgrpc_csharp_ext.x86.so; \
+    fi
+```


What in the WORLD is going on here? Why are we removing the redis dependencies? I am confusion.

This was the original code from the UE repository

# Remove native libs not used on Linux x86_64 RUN rm -rf /app/out/runtimes/osx* && \ rm -rf /app/out/runtimes/win* && \ rm -rf /app/out/runtimes/linux-arm* && \ rm -rf /app/out/runtimes/linux/native/libgrpc_csharp_ext.x86.so

It seems to be removing libs that are not used for the Linux x86_64 because that is the architecture this is built for by default. I think this is to remove unnecessary libraries to remove bloat from the docker image. In order to follow this same principle we make this compatible with all compute architectures and OS by identifying the architecture and OS the build is for, then removing the other libraries.

Got it - thanks for clarifying.

A few thoughts:

You should raise a PR against the engine directly suggesting changes to the Horde dockerfile that make it truly multi-arch. Suggesting changes that customers need to make to their version of the engine is a little messier.

That being said, I think the work you've done to show how one can build Horde for ARM is valuable. It informs the PR, and you can and should include it in the documentation changes so that customers can take advantage of this before UE merges the changes upstream. Plus, you can link your PR/issue in the UE repo in the docs so people can upvote / endorse your changes.

The default of the toolkit should be support for x86 until the ARM support is first-party.

What do you think?

hwkiem · 2025-12-17T17:20:25Z

modules/unreal/horde/source-build/README.md

+        <Docker-Build BaseDir="Engine/Source/Programs/Horde/HordeServer" Files="Dockerfile*" UseBuildKit="true" Tag="horde-server" DockerFile="Engine/Source/Programs/Horde/HordeServer/Dockerfile.dashboard" />
+
+        <!-- Publish the docker image to Amazon ECR -->
+        <Docker-Push Repository="<account-id>.dkr.ecr.<region>.amazonaws.com" Image="horde-server" TargetImage="horde/horde-server:$(Version)" AwsEcr="True" />


I do like this... Just wondering if we want to recommend the creation of a new graph. I wonder if you could raise a PR against the the engine itself with modifications / improvements to the Horde buildgraph.

I agree also would make sense to do the same with the Horde Server Dockerfile since at the moment it only is designed to support AMD64 and I have the fixes to make it more adaptive to the different architectures which you see in the README

Exactly. Let's make default docs use default approach in the engine. Then create a change upstream to support multi-arch better, and link those changes in docs.

Want help with this? I'm happy to assist on the UE changes. Docs for now should default to X86 and then we include an optional section below that outlines all those QOL changes.

hwkiem · 2025-12-17T17:21:59Z

modules/unreal/horde/source-build/README.md

+1. In your IDE, open the main.tf located at `modules/unreal/horde/examples/complete/main.tf`.
+2. Under the module declaration `"unreal_engine_horde"` add the following line with the value of the image URI you noted earlier. Be sure to also set the value of `is_source_build` to `true` and set the value of `horde_server_architecture` to `ARM64` or `X_86` by passing the value with the `var.horde_server_architecture` variable as shown below:
+    ```python
+    module "unreal_engine_horde" {
+        ...
+        image = "<image-uri>"
+        is_source_build = true
+        horde_server_architecture = "<horde-server-architecture>"
+        ...
+    }
+    ```


We should manage this through variables on the example.

hwkiem · 2025-12-17T17:23:50Z

modules/unreal/horde/variables.tf

+variable "horde_server_architecture" {
+  type        = string
+  description = "The CPU architecture for Horde server container. Valid values: x86 or arm64"
+  default     = "X86_64"
+  validation {
+    condition     = contains(["X86_64", "ARM64"], var.horde_server_architecture)
+    error_message = "horde_server_architecture must be either 'X_86' or 'ARM64'"
+  }
+}


Can we determine architecture via data block and a lookup against the image?

hwkiem · 2025-12-17T17:24:15Z

modules/unreal/horde/variables.tf

+variable "is_source_build" {
+  type        = bool
+  description = "Set this flag to true if you are using a custom built Horde Server image from source."
+  default     = false
+}


Why do we need to know if its a source build?

I added that because in ecs.tf we have the current steps to use github credentials as part of the container definition to pull the public horde docker image. I didn't want to break the functionality so created the variable so the user can still use the pre-built docker image if they choose or go for the source build

I think if they provide an image as a variable that accomplishes the same thing right?

Customer specifies "image" and we use it. Credentials are not required.

Customer does not specify image or arch. We use the latest version of horde published and require GHCR credentials?

hwkiem · 2025-12-17T17:28:49Z

modules/unreal/horde/variables.tf

+variable "operating_system" {
+  type        = string
+  description = "The operating system for the Horde server container. Valid values: linux or windows"
+  default     = "WINDOWS_SERVER_2019_CORE"
+  validation {
+    condition     = contains(["LINUX", "WINDOWS_SERVER_2025_FULL", "WINDOWS_SERVER_2025_CORE", "WINDOWS_SERVER_2022_FULL", "WINDOWS_SERVER_2022_CORE", "WINDOWS_SERVER_2019_FULL", "WINDOWS_SERVER_2019_CORE"], var.operating_system)
+    error_message = "Operating_system must be either LINUX, WINDOWS_SERVER_2025_FULL, WINDOWS_SERVER_2025_CORE, WINDOWS_SERVER_2022_FULL, WINDOWS_SERVER_2022_CORE, WINDOWS_SERVER_2019_FULL, and WINDOWS_SERVER_2019_CORE."
+  }
+}


Also this. I am not sure why we want to support a windows OS for Horde unless a customer explicitly asks for it. Open to your thoughts on this!

That was something I wanted to ask. What are the most commonly used OS for Horde?

We should really only support Linux distributions. I don't think this is required for containerized deployments...

github-actions · 2025-12-19T21:39:19Z

📝 Markdown Linting Failed

The markdown linter has found issues in the changed documentation files.

Action Required

Please review the inline annotations in the Files changed tab and the workflow logs to fix the linting errors.

Common Issues

Missing blank lines around headings, lists, or code blocks
Inconsistent list styles
Code blocks without language specifiers
Emphasis used instead of proper headings

Auto-fix Available

Many issues can be automatically fixed by running:

npx markdownlint-cli2 --fix "**/*.md"

Last checked: dea95d5
This comment will update automatically when you push new commits

github-actions · 2025-12-19T21:39:47Z

📚 Documentation Preview

✅ Preview deployed successfully!

🔗 Preview URL: https://aws-games.github.io/cloud-game-development-toolkit/preview-pr-813/

🔒 Maintainer Action Required

The preview requires approval before it's accessible. A maintainer must approve the GitHub Pages deployment in the Environments section.

Once approved, the preview will be accessible within 1-2 minutes.

Build Information

Status: ✅ Deployed (awaiting approval)
Commit: dea95d5869892d8fa0f2e9f3e538e180eed41cc6
Workflow Run: #66

This preview will be automatically deleted when the PR is merged or closed.

cwwalb self-assigned this Dec 13, 2025

cwwalb force-pushed the cwwalb/ue-horde-source-build branch 3 times, most recently from b78cc1d to 44ff5cb Compare December 15, 2025 16:28

cwwalb changed the title ~~Unreal Horde Source Build Documentation with ARM64 Support~~ Unreal Horde Source Build Documentation with ARM64 Support (#743) Dec 15, 2025

cwwalb changed the title ~~Unreal Horde Source Build Documentation with ARM64 Support (#743)~~ Unreal Horde Source Build Documentation with ARM64 Support Dec 15, 2025

hwkiem requested changes Dec 17, 2025

View reviewed changes

cwwalb force-pushed the cwwalb/ue-horde-source-build branch from 44ff5cb to f1986bd Compare December 19, 2025 21:38

cwwalb force-pushed the cwwalb/ue-horde-source-build branch from f1986bd to dea95d5 Compare December 19, 2025 21:56

docs: Unreal Horde source build instructions

a4fd601

cwwalb force-pushed the cwwalb/ue-horde-source-build branch from dea95d5 to a4fd601 Compare December 19, 2025 21:59

Comments

Conversation

cwwalb commented Dec 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

User experience

Checklist

Acknowledgment

Uh oh!

hwkiem left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cwwalb Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions bot commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📝 Markdown Linting Failed

Action Required

Common Issues

Auto-fix Available

Uh oh!

github-actions bot commented Dec 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📚 Documentation Preview

🔒 Maintainer Action Required

Build Information

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

cwwalb commented Dec 13, 2025 •

edited

Loading

cwwalb Dec 19, 2025 •

edited

Loading

github-actions bot commented Dec 19, 2025 •

edited

Loading

github-actions bot commented Dec 19, 2025 •

edited

Loading