Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add specific Box64 builds for common ARM64 hosts #576

Merged
merged 15 commits into from
Jul 8, 2024
Merged

Add specific Box64 builds for common ARM64 hosts #576

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
6573ddc
Rename ARM_COMPATIBILITY_MODE to ARM_QEMU_MODE and add ARM64_DEVICE o…
sonroyaalmerol Jul 3, 2024
2fd6b42
update arm64 base image
sonroyaalmerol Jul 3, 2024
801ac98
Update documentations + bump base image version
sonroyaalmerol Jul 4, 2024
b8bee60
set BOX64_DYNAREC_STRONGMEM to 1
sonroyaalmerol Jul 4, 2024
b558d3f
Merge branch 'main' into box64-binaries
sonroyaalmerol Jul 4, 2024
f86c047
Merge branch 'main' into box64-binaries
sonroyaalmerol Jul 7, 2024
729693f
remove qemu option and update to latest arm64 base image
sonroyaalmerol Jul 7, 2024
cb7701b
separate table for arm64-only env vars
sonroyaalmerol Jul 7, 2024
bc72cdc
fix markdown linting
sonroyaalmerol Jul 7, 2024
138184e
move USE_DEPOT_DOWNLOADER documentation back to general env vars
sonroyaalmerol Jul 7, 2024
892a362
change tip for better description
sonroyaalmerol Jul 7, 2024
151f79a
add space
sonroyaalmerol Jul 7, 2024
0e81848
add space again
sonroyaalmerol Jul 7, 2024
e080628
use specific urls for each box64 configs
sonroyaalmerol Jul 7, 2024
7a2ae17
revert ARM_COMPATIBILITY_MODE renames on translated docs
sonroyaalmerol Jul 7, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions .env.example
View file
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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
Open in desktop
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