Skip to content

Commit

Permalink
Merge pull request #576 from sonroyaalmerol/box64-binaries
Browse files Browse the repository at this point in the history 
Add specific Box64 builds for common ARM64 hosts
  • Loading branch information
@thijsvanloef
thijsvanloef authored Jul 8, 2024
2 parents 1826e29 + 7a2ae17 commit 579150d
Show file tree
Hide file tree
Showing 8 changed files with 103 additions and 36 deletions.
9 changes: 9 additions & 0 deletions .env.example
View file
Original file line number Diff line number Diff line change
Expand Up @@ -93,3 +93,12 @@ ALLOW_CONNECT_PLATFORM=Steam
USE_BACKUP_SAVE_DATA=True
USE_DEPOT_DOWNLOADER=False
INSTALL_BETA_INSIDER=False

# Box64 Configs (Only relevant for ARM64 hosts)
# These can be adjusted if the server keeps on crashing.
BOX64_DYNAREC_STRONGMEM=1 # This can be set to 2 or 3 with 3 being the most stable but worst performance.
BOX64_DYNAREC_BIGBLOCK=1 # This can be set to 0 for better stability but worse performance.
BOX64_DYNAREC_SAFEFLAGS=1 # This can be set to 2 for better stability but worse performance.
BOX64_DYNAREC_FASTROUND=1 # This can be set to 0 for better stability but worse performance.
BOX64_DYNAREC_FASTNAN=1 # This can be set to 0 for better stability but worse performance.
BOX64_DYNAREC_X87DOUBLE=0 # This can be set to 1 for better stability but worse performance.
13 changes: 11 additions & 2 deletions Dockerfile
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ RUN wget -q https://github.com/gorcon/rcon-cli/archive/refs/tags/v${RCON_VERSION
FROM cm2network/steamcmd:root as base-amd64
# Ignoring --platform=arm64 as this is required for the multi-arch build to continue to work on amd64 hosts
# hadolint ignore=DL3029
FROM --platform=arm64 sonroyaalmerol/steamcmd-arm64:root-2024-06-23 as base-arm64
FROM --platform=arm64 sonroyaalmerol/steamcmd-arm64:root-2024-07-08 as base-arm64

ARG TARGETARCH
# Ignoring the lack of a tag here because the tag is defined in the above FROM lines
Expand Down Expand Up @@ -158,12 +158,21 @@ ENV HOME=/home/steam \
DISCORD_ERR_BACKUP_DELETE_MESSAGE_ENABLED=true \
ENABLE_PLAYER_LOGGING=true \
PLAYER_LOGGING_POLL_PERIOD=5 \
ARM_COMPATIBILITY_MODE=false \
ARM64_DEVICE=generic \
DISABLE_GENERATE_ENGINE=true \
ALLOW_CONNECT_PLATFORM=Steam \
USE_DEPOT_DOWNLOADER=false \
INSTALL_BETA_INSIDER=false

# Sane Box64 config defaults
# hadolint ignore=DL3044
ENV BOX64_DYNAREC_STRONGMEM=1 \
BOX64_DYNAREC_BIGBLOCK=1 \
BOX64_DYNAREC_SAFEFLAGS=1 \
BOX64_DYNAREC_FASTROUND=1 \
BOX64_DYNAREC_FASTNAN=1 \
BOX64_DYNAREC_X87DOUBLE=0

# Passed from Github Actions
ARG GIT_VERSION_TAG=unspecified

Expand Down
24 changes: 23 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -285,7 +285,6 @@ It is highly recommended you set the following environment values before startin
| DISABLE_GENERATE_ENGINE | Whether to automatically generate the Engine.ini | true | true/false | 0.30.0 |
| ENABLE_PLAYER_LOGGING | Enables Logging and announcing when players join and leave | true | true/false | 0.31.0 |
| PLAYER_LOGGING_POLL_PERIOD | Polling period (in seconds) to check for players who have joined or left | 5 | !0 | 0.31.0 |
| ARM_COMPATIBILITY_MODE | Switches the compatibility layer from Box86 to QEMU when executing steamcmd for server updates. This setting is only applicable for ARM64 hosts. | false | true/false | 0.30.0 |
| USE_DEPOT_DOWNLOADER | Uses DepotDownloader to download game server files instead of steamcmd. This will help hosts incompatible with steamcmd (e.g. M-series Mac) | false | true/false | 0.39.0 |

*highly recommended to set
Expand All @@ -294,6 +293,29 @@ It is highly recommended you set the following environment values before startin

*** Required for docker stop to save and gracefully close the server

### ARM64-exclusive environment variables

ARM64 hosts can use the following variables to tweak their server setup. This includes
known relevant Box64 configurations one can modify for better server stability/performance.

For the Box64 configurations, please see the their official documentation for more info.

> [!TIP]
> Set `ARM64_DEVICE` to the most appropriate setting for your device. `generic` is expected
> to work on all devices but better stability can be found with specifying your device.
> For more specific device compatibility, create an issue on the
> [base image repo](https://github.com/sonroyaalmerol/steamcmd-arm64).
| Variable | Info | Default Values | Allowed Values | Added in Version |
|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
| BOX64_DYNAREC_STRONGMEM | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_strongmem-)] Enable/Disable simulation of Strong Memory model | 1 | 0, 1, 2, 3 | 0.23.0 |
| BOX64_DYNAREC_BIGBLOCK | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_bigblock-)] Enables/Disables Box64's Dynarec building BigBlock. | 1 | 0, 1, 2, 3 | 0.23.0 |
| BOX64_DYNAREC_SAFEFLAGS | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_safeflags-)] Handling of flags on CALL/RET opcodes | 1 | 0, 1, 2 | 0.23.0 |
| BOX64_DYNAREC_FASTROUND | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_fastround-)] Enable/Disable generation of precise x86 rounding | 1 | 0, 1 | 0.23.0 |
| BOX64_DYNAREC_FASTNAN | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_fastnan-)] Enable/Disable generation of -NAN | 1 | 0, 1 | 0.23.0 |
| BOX64_DYNAREC_X87DOUBLE | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_x87double-)] Force the use of Double for x87 emulation | 0 | 0, 1 | 0.23.0 |
| ARM64_DEVICE | Specify Box64 build to be used based on host device. This setting is only applicable for ARM64 hosts. | generic | generic, m1, rpi5, adlink | 0.39.0 |

### Game Ports

| Port | Info |
Expand Down
25 changes: 24 additions & 1 deletion docusaurus/docs/getting-started/configuration/server-settings.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -101,7 +101,6 @@ It is highly recommended you set the following environment values before startin
| DISABLE_GENERATE_ENGINE | Whether to automatically generate the Engine.ini | true | true/false | 0.30.0 |
| ENABLE_PLAYER_LOGGING | Enables Logging and announcing when players join and leave | true | true/false | 0.31.0 |
| PLAYER_LOGGING_POLL_PERIOD | Polling period (in seconds) to check for players who have joined or left | 5 | !0 | 0.31.0 |
| ARM_COMPATIBILITY_MODE | Switches the compatibility layer from Box86 to QEMU when executing steamcmd for server updates. This setting is only applicable for ARM64 hosts. | false | true/false | 0.30.0 |
| USE_DEPOT_DOWNLOADER | Uses DepotDownloader to download game server files instead of steamcmd. This will help hosts incompatible with steamcmd (e.g. M-series Mac) | false | true/false | 0.39.0 |

*highly recommended to set
Expand All @@ -110,6 +109,30 @@ It is highly recommended you set the following environment values before startin

*** Required for docker stop to save and gracefully close the server

## ARM64-exclusive environment variables

ARM64 hosts can use the following variables to tweak their server setup. This includes
known relevant Box64 configurations one can modify for better server stability/performance.

For the Box64 configurations, please see the their official documentation for more info.

:::tip
Set `ARM64_DEVICE` to the most appropriate setting for your device. `generic` is expected
to work on all devices but better stability can be found with specifying your device.
For more specific device compatibility, create an issue on the
[base image repo](https://github.com/sonroyaalmerol/steamcmd-arm64).
:::

| Variable | Info | Default Values | Allowed Values | Added in Version |
|--------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|------------------|
| BOX64_DYNAREC_STRONGMEM | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_strongmem-)] Enable/Disable simulation of Strong Memory model | 1 | 0, 1, 2, 3 | 0.23.0 |
| BOX64_DYNAREC_BIGBLOCK | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_bigblock-)] Enables/Disables Box64's Dynarec building BigBlock. | 1 | 0, 1, 2, 3 | 0.23.0 |
| BOX64_DYNAREC_SAFEFLAGS | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_safeflags-)] Handling of flags on CALL/RET opcodes | 1 | 0, 1, 2 | 0.23.0 |
| BOX64_DYNAREC_FASTROUND | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_fastround-)] Enable/Disable generation of precise x86 rounding | 1 | 0, 1 | 0.23.0 |
| BOX64_DYNAREC_FASTNAN | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_fastnan-)] Enable/Disable generation of -NAN | 1 | 0, 1 | 0.23.0 |
| BOX64_DYNAREC_X87DOUBLE | [[Box64 config](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md#box64_dynarec_x87double-)] Force the use of Double for x87 emulation | 0 | 0, 1 | 0.23.0 |
| ARM64_DEVICE | Specify Box64 build to be used based on host device. This setting is only applicable for ARM64 hosts. | generic | generic, m1, rpi5, adlink | 0.39.0 |

### Game Ports

The server needs the following ports by default.
Expand Down
38 changes: 35 additions & 3 deletions docusaurus/docs/known-issues/known-issues.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,11 @@ it means that you'll need to look at the following:

## Only ARM64 hosts with 4k page size is supported

:::tip
This issue should not occur anymore after the addition of `USE_DEPOT_DOWNLOADER`. Instead, it should ask you to set the
said configuration to `true`.
:::

This error occurs when the container detects that the host kernel does not have a 4k page size,
which is required for the emulation used for ARM64 architecture. The container relies on this specific page
size for proper execution.
Expand All @@ -100,9 +105,36 @@ problematic machine to prevent steamcmd from executing.
This means that the Docker host is unable to run AArch32 binaries such as Box86 without an additional
compatibility layer which is the case for Apple Silicon.

Docker Desktop solves this by running its containers inside a VM (QEMU) with a compatible kernel.
However, if you're unable to use Docker Desktop, then try setting `ARM_COMPATIBILITY_MODE` to `true`.
This will switch the container from using Box86 to QEMU when running steamcmd.
Try setting `USE_DEPOT_DOWNLOADER` to `true`. This will switch the container from using steamcmd to
DepotDownloader instead. This should avoid the need for any AArch32 emulation.

## Server keeps on crashing randomly! (ARM64 hosts)

For ARM64 hosts, emulation of the server binaries and libraries is required. As such, huge updates can cause Box64
(the emulator we use) to crash due to many reasons. Box64 has a lot of configuration options to tweak the emulator
for specific binaries. We will try to set appropriate defaults for these configs as we receive more reports. In general,
setting the following environment variables will give you the best chance of stability in exchange for performance:

* `BOX64_DYNAREC_BIGBLOCK=0` (Default: 1)
* `BOX64_DYNAREC_SAFEFLAGS=2` (Default: 1)
* `BOX64_DYNAREC_STRONGMEM=3` (Default: 1)
* `BOX64_DYNAREC_FASTROUND=0` (Default: 1)
* `BOX64_DYNAREC_FASTNAN=0` (Default: 1)
* `BOX64_DYNAREC_X87DOUBLE=1` (Default: 0)

See [Box64 usage documentation](https://github.com/ptitSeb/box64/blob/main/docs/USAGE.md) for more info.

Also, the container should have multiple Box64 variants for different host devices. This can be set using the `ARM64_DEVICE`
environment variable.

:::tip
For best compatibility with **Apple Silicon**, set `ARM64_DEVICE` to `m1`.
For best compatibility with **Oracle ARM**, set `ARM64_DEVICE` to `adlink`.
For best compatibility with **Raspberry Pi 5**, set `ARM64_DEVICE` to `rpi5`.
:::

These builds are from the [ARM64 base image](https://github.com/sonroyaalmerol/steamcmd-arm64). If your device is not listed
above, consider creating an issue on the base image's repository.

## FAQ

Expand Down
Loading

0 comments on commit 579150d

Please sign in to comment.