Run several servers and update safely

01The fleet launcher

--fleet <manifest> starts one child server per enabled [[instances]] entry, each with its own config, port and log. Config paths are resolved beside the manifest. Before anything starts, every config is validated and duplicate names or game ports are rejected. Ctrl+C sends a clean shutdown to every child and only force-stops a child that exceeds shutdown_timeout_seconds (1–60, default 10).

[fleet]
shutdown_timeout_seconds = 10

[[instances]]
name = "Official TDM"
config = "configs/official-tdm.toml"
enabled = true

[[instances]]
name = "Official CTF"
config = "configs/official-ctf.toml"
enabled = true
# port = 27117   # optional: override this instance's [server] port

# Portable Windows release
.\BattleSpades.exe --fleet fleet.toml

# Source checkout
py -3.12 run_server.py --fleet fleet.toml

02The ten official profiles

The shipped fleet.toml launches these profiles from configs/. Each uses the recovered retail map rotation and clock, backfills at most six bots with the crash-isolated process worker, and has its own game port, Steam ports and log file. AoSPlay and Steam publishing are disabled in all of them.

To publish a fleet, give each profile its own public identity: enable [revival] per profile, register every game port, and run each with its own token (the fleet passes the parent's environment to every child, so separate launches or containers are simpler when each needs a different AOS_MASTER_WRITE_TOKEN). With Steam listing, forward each game and query port plus the Steam UDP ports 8766–8775 the profiles use.

03Write your own profile

A profile is an ordinary config file; anything missing uses the built-in default (not the values in the big sample config.toml), so set the keys you care about explicitly.

[server]
name = "My Zombie Server"
port = 27041
max_players = 24

[game]
default_mode = "zom"
default_map = "SpookyMansion"

[lobby]
match_length_minutes = 10
map_rotation = ["SpookyMansion", "MayanJungle", "CastleWars"]

[bots]
enabled = true
population_mode = "backfill"
fill_target = 8
max_bots = 8
worker = "process"

[admin]
password = "another-long-unique-secret"
bans_path = "bans-zombie.json"

[revival]
enabled = false

[logging]
file = "my-zombie.log"
console = false

You can also run instances as completely separate processes: BattleSpades --config configs/my-zombie.toml (and --port to override the port once).

04Keep it running as a service

The server stops cleanly on Ctrl+C, SIGINT and SIGTERM, so any service manager works. On Linux, systemd restarts it after a crash and starts it at boot.

[Unit]
Description=BattleSpades Ace of Spades server
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=battlespades
WorkingDirectory=/opt/battlespades
ExecStart=/opt/battlespades/BattleSpades --config /opt/battlespades/config.toml
Environment=AOS_MASTER_WRITE_TOKEN=aos_srv_...
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable --now battlespades
journalctl -u battlespades -f

On Windows, the simplest option is a Task Scheduler task that runs BattleSpades.exe “At startup” with “Run whether user is logged on or not”, the server folder as “Start in”, and “If the task fails, restart every 1 minute”. For a source checkout run python run_server.py from its folder instead. --control-stdin lets a launcher stop the server by writing shutdown to its standard input.

05Updating without losing data

Keep these across every upgrade — they are your data, not part of the program:

• config.toml (and any configs/*.toml / fleet.toml you changed)
• bans.json (or your bans_path)
• state/round-results.sqlite3 — AoSPlay round results that were not yet uploaded
• custom maps in maps/ (with their .txt/.json sidecars), prefabs, and your plugins
• logs/ if you need history

1. 01
   Test first

   Extract or build the new version in a separate folder and run it with --check, ideally on a spare port (--port 27099) for a quick join test.

2. 02
   Announce

   Warn players with /say; a restart disconnects everyone.

3. 03
   Stop

   Stop the old server (Ctrl+C or your service manager).

4. 04
   Carry data over

   Copy the files above into the new folder. Compare your config.toml with the new sample for new keys; missing keys simply use defaults.

5. 05
   Start

   Start the new version and watch the log for warnings.

# stop the server first (compiled modules are locked while it runs)
git pull
python -m pip install -r requirements.txt
python setup.py build_ext --inplace
python run_server.py --check

The release packager refuses to overwrite an existing release folder on purpose, so a new portable version always lands next to the old one. Containers update by switching the image tag; see Docker.