AgrarianGameArchive/Docs/Ops/DedicatedServerBuildRunbook.md

Agrarian Dedicated Server Build Runbook

Agrarian's multiplayer server target is Linux. Windows-Builder remains the interactive Unreal build machine, but the server artifact should run on an Ubuntu cloud VM or other Linux host.

Public Endpoint Convention

Use this MVP gameplay endpoint unless a later deployment requires a different host name:

• DNS name: play.agrariangame.com
• Unreal gameplay traffic: 7777/udp
• SSH: admin IPs only

When the first Ubuntu gameplay VM is created, point the play A/AAAA record at that VM. Do not point this name at the tile server; tile delivery and gameplay should remain separate until a deliberate combined-host decision is made.

Build Machine

Use Windows-Builder for the first repeatable build lane:

• Unreal Engine 5.7
• VS 2022 Build Tools toolchain compatible with Unreal 5.7
• Epic Linux cross-compile toolchain for Unreal 5.7
• Project path: P:\AgrarianGameBulid when mapped from \\DevBox\projects

The server target is AgrarianGameServer, defined in Source/AgrarianGameServer.Target.cs.

Ubuntu Host Bootstrap

Prepare a new Ubuntu gameplay host with:

sudo Operations/cloud-game-server/bootstrap_ubuntu_game_server.sh play.agrariangame.com

The script installs baseline packages, creates an agrarian service user, creates /opt/agrarian/server, writes a systemd unit named agrarian-game-server, and opens 7777/udp with ufw when available.

For DigitalOcean or another cloud provider later, create an Ubuntu LTS droplet or VM, copy this repository or just the script onto the host, run the bootstrap script, then copy the Builds/LinuxServerDevelopment package contents into /opt/agrarian/server.

Build Command

From an elevated or normal Command Prompt on Windows-Builder:

cd /d P:\AgrarianGameBulid
Scripts\BuildLinuxDedicatedServer-Windows.bat

Expected output:

• Logs: Saved\BuildLogs\BuildLinuxDedicatedServer.log
• Archive: Builds\LinuxServerDevelopment

The script self-heals LINUX_MULTIARCH_ROOT when the known UE 5.7 toolchain is installed at C:\UnrealToolchains\v26_clang-20.1.8-rockylinux8.

If the script fails with:

Server targets are not currently supported from this engine distribution.

the installed Epic binary engine cannot build the true AgrarianGameServer target. Use the MVP fallback package until a source-built/server-capable engine is available:

cd /d P:\AgrarianGameBulid
Scripts\PackageLinuxGameServerFallback-Windows.bat

Fallback expected output:

• Logs: Saved\BuildLogs\PackageLinuxGameServerFallback.log
• Archive: Builds\LinuxGameDevelopment

Deploy the fallback package to /opt/agrarian/server and launch it through AgrarianGameServer.sh with -server -port=7777 -NullRHI -nosound.

Initial Runtime Shape

The first server package cooks the Ground Zero MVP map:

/Game/Agrarian/Maps/L_GroundZeroTerrain_Test

First cloud/server launch target:

./AgrarianGameServer L_GroundZeroTerrain_Test?listen -log -port=7777

In-game/admin MVP travel command:

AgrarianServerTravel GroundZero

This command is allowlisted to the Ground Zero MVP map and should remain the only server travel path until tile/session validation is stronger.

Systemd launch target created by the bootstrap script:

sudo systemctl restart agrarian-game-server
sudo journalctl -u agrarian-game-server -f

Open firewall ports only as needed:

• 7777/udp for Unreal gameplay traffic.
• SSH from trusted admin IPs only.

Do not expose editor, SMB, RDP, database, or admin ports on the public server.

Smoke Test

For the first MVP validation:

1. Build the Linux server package on Windows-Builder.
2. Copy the archived server package to an Ubuntu test VM.
3. Start the server with -log -port=7777.
4. Confirm the log reaches map load without fatal errors.
5. Connect from a packaged Windows Development client on the LAN or test VPN.
6. Record the commit, package date, map, client build, and server log path.

Current Limits

This runbook creates the repeatable build lane. It does not yet prove a full external multiplayer session. That remains a later roadmap item after the project has a clean server package and a stable deploy target.