Host Your Own Beyond All Reason Server | Complete Setup Guide

You are setting up a self-hosted "Beyond All Reason" (BAR) game server for me. BAR is an open-source RTS built on the Spring/Recoil engine. A working server is two cooperating pieces of software:

1. Teiserver — the lobby/matchmaking/account/chat/moderation server (github.com/beyond-all-reason/teiserver). It cannot launch a match by itself.
2. SPADS — an autohost bot that logs into Teiserver as a normal bot account, launches the actual headless game engine process, and keeps a synced copy of the game content. BAR's config layer on top of generic SPADS lives at github.com/beyond-all-reason/spads_config_bar.

Everything runs in Docker Compose. Do not install Elixir, Erlang, Postgres, or Node directly on the host — they all run inside the Teiserver container's own multi-stage Dockerfile, which is required (a bare "mix release" skips the asset-compile step and produces a broken UI with missing CSS/JS).

FIRST, confirm the target environment with me before doing anything:
- Where is this running: my current machine, a rented VPS I'll SSH you into (DigitalOcean/Hetzner/Vultr/etc. — a $5-10/month box with 2GB+ RAM is enough), a second Linux machine on my network, or Windows via WSL2 (this path is untested — if you hit something WSL-specific, tell me rather than guessing)?
- Is this Ubuntu/Debian-based? Adjust package manager commands if not.
- Will this box also be my everyday desktop, or dedicated to the server? (Affects whether to set up boot-time auto-start.)
- LAN-only for now, or do you want it reachable from the public internet? Default to LAN-only unless I say otherwise — public exposure needs a firewall, TLS, and reverse-proxy work that should be a deliberate later step, not baked in blindly.
- What IP or domain should the server advertise to clients? (LAN IP like 192.168.1.x, or a public IP/domain if this is a VPS.)

Then do the following, explaining what you're doing at each step and pausing for my input at the marked decision points. Ask me before running anything destructive or before it needs sudo I don't have configured for you already.

## 1. Install Docker

Install Docker Engine + Compose plugin from Docker's OFFICIAL apt repository — not snap, not the distro's bundled docker.io package (both have known networking/permission quirks with this stack):

    sudo install -m 0755 -d /etc/apt/keyrings
    curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /tmp/docker.gpg
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg /tmp/docker.gpg
    sudo chmod a+r /etc/apt/keyrings/docker.gpg
    echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
    sudo apt-get update
    sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
    sudo usermod -aG docker "$USER"

The new docker group membership won't apply to your current shell session. Either start a fresh login shell, or prefix docker commands with `sg docker -c "..."` until I've logged out and back in.

## 2. Lay out the project and clone the repos

    mkdir -p ~/bar-server/{docker,data/postgres,repos}
    cd ~/bar-server/repos
    git clone --depth 1 https://github.com/beyond-all-reason/teiserver.git
    git clone --depth 1 https://github.com/beyond-all-reason/spads_config_bar.git

Clone the default branch with no tag pinned — that matches how BAR's own production actually runs (no release tag has been cut in years; main is what's live).

## 3. Generate secrets and write docker/.env

Generate real random secrets with openssl — never hand-type placeholder passwords into the real file:

    cd ~/bar-server/docker
    cat > .env <<EOF
    TEI_DB_HOSTNAME=127.0.0.1
    TEI_DB_NAME=teiserver_prod
    TEI_DB_USERNAME=teiserver_prod
    TEI_DB_PASSWORD=$(openssl rand -hex 16)
    TEI_HTTP_SECRET_KEY_BASE=$(openssl rand -base64 48)
    TEI_SETUP_ROOT_KEY=$(openssl rand -hex 24)
    TEI_DOMAIN_NAME=<the IP or domain I gave you>
    TEI_OAUTH_ISSUER=http://<the IP or domain I gave you>:4000
    TEI_NODE_NAME=barserver

    SPADS_LOBBY_LOGIN=BAR_SPADS_01
    SPADS_LOBBY_PASSWORD=$(openssl rand -hex 12)
    SPADS_OWNER_LOBBY_LOGIN=root
    SPADS_REGISTRATION_EMAIL=spads@example.com
    EOF

Two validation rules that are easy to trip on: the SPADS bot login must use an underscore, not a hyphen (a hyphen causes a login error), and its registration email must contain a dot in the domain part (a bare "@localhost"-style domain is rejected).

Add this file to .gitignore if this directory is ever put under git.

## 4. Write docker/docker-compose.yml

Put BOTH teiserver and spads on network_mode: "host" from the very start. This is important: if teiserver stays on Docker's default bridge network while spads uses host networking, Docker NAT-hairpins the autohost's connection to the lobby server, and the lobby server (which deliberately trusts only the raw observed TCP peer address, as an anti-spoof measure) ends up advertising the Docker bridge gateway address to joining clients instead of a real one. Login and lobby browsing work fine in that broken state — only the actual match connection silently fails after a ~30 second timeout with no obvious error. Avoid the whole bug by starting both services on host networking:

    services:
      teiserver:
        build:
          context: ../repos/teiserver
          dockerfile: Dockerfile
        container_name: bar-teiserver
        restart: unless-stopped
        network_mode: "host"
        depends_on:
          database:
            condition: service_healthy
          mailserver:
            condition: service_started
        env_file: [.env]
        environment:
          - PHX_SERVER=true
          - TEI_ENABLE_EMAIL_INTEGRATION=true
          - TEI_SMTP_SERVER=127.0.0.1
          - TEI_SMTP_HOSTNAME=127.0.0.1
          - TEI_SMTP_PORT=1025
          - TEI_SMTP_USERNAME=teitestuser
          - TEI_SMTP_PASSWORD=teitestpassword
          - TEI_SMTP_TLS_VERIFY=false

      database:
        image: postgres:17-alpine
        container_name: bar-teiserver-db
        restart: unless-stopped
        environment:
          - POSTGRES_DB=teiserver_prod
          - POSTGRES_USER=teiserver_prod
          - POSTGRES_PASSWORD=${TEI_DB_PASSWORD}
        volumes: ["../data/postgres:/var/lib/postgresql/data"]
        ports: ["127.0.0.1:5432:5432"]
        healthcheck:
          test: ["CMD-SHELL", "pg_isready -U teiserver_prod -d teiserver_prod"]
          interval: 5s
          timeout: 5s
          retries: 10

      mailserver:
        image: axllent/mailpit
        container_name: bar-mailpit
        restart: unless-stopped
        command: ["--smtp-tls-cert", "sans:localhost", "--smtp-tls-key", "sans:localhost"]
        environment:
          - MP_SMTP_AUTH_FILE=/tmp/auth
          - MP_SMTP_AUTH_ALLOW_INSECURE=true
        volumes: ["./containers/mailpit-auth/auth:/tmp/auth"]
        ports:
          - "127.0.0.1:8025:8025"
          - "127.0.0.1:1025:1025"

      spads:
        build:
          context: ../repos/spads_config_bar
        container_name: bar-spads
        restart: unless-stopped
        network_mode: "host"
        depends_on: [teiserver]
        env_file: [.env]
        environment:
          - SPRING_DATADIR=/spring-data
          - SPRING_WRITEDIR=/spring-data
          - RECOIL_ENGINE_VERSION=2025.06.24
          - SPADS_ARGS=--tls-cert-trust
          - SPADS_LOBBY_HOST=<the IP or domain I gave you>
          - SPADS_BASEGAME_PORT=53200
          - SPADS_BASEAUTOHOST_PORT=53100
          - SPADS_BATTLENAME_PREFIX=Self-Host -
          - SPADS_LAN_IP=<the IP or domain I gave you>
          - SPADS_MAX_INSTANCES=1
          - SPADS_TARGET_SPARES=1
          - SPADS_PLUGINS=AutoRegister;ClusterManager;JsonStatus;InGameMute;BarManager
          - SPRING_HOSTIP=<the IP or domain I gave you>
        volumes:
          - spring_data:/spring-data
          - spads_cache:/opt/spads/var
          - spring_engines:/spring-engines

      games-updater:
        build:
          context: ../repos/spads_config_bar
          dockerfile: Dockerfile.services
        container_name: bar-spads-games-updater
        restart: "no"
        profiles: ["tools"]
        command: /usr/bin/sync-all.sh
        environment:
          - SPRING_DATADIR=/spring-data
          - SPRING_WRITEDIR=/spring-data
          - RECOIL_ENGINE_VERSION=2025.06.24
          - PRD_RAPID_REPO_MASTER=https://repos-cdn.beyondallreason.dev/repos.gz
          - PRD_RAPID_USE_STREAMER=false
        volumes:
          - spring_data:/spring-data
          - spring_engines:/spring-engines

    volumes:
      spring_data:
      spads_cache:
      spring_engines:

Also create the mail-catcher auth file (must match TEI_SMTP_USERNAME/PASSWORD above):

    mkdir -p ~/bar-server/docker/containers/mailpit-auth
    HASH=$(openssl passwd -apr1 teitestpassword)
    echo "teitestuser:$HASH" > ~/bar-server/docker/containers/mailpit-auth/auth

A few values above are easy to get wrong if you go looking at other reference material instead of this prompt — use these exact ones:
- The lobby server's real Spring TCP listener defaults to port 8200, not 8000/8001 (an older example compose file mislabels this).
- Game content must come from BAR's own CDN, https://repos-cdn.beyondallreason.dev/repos.gz, using the byar:test rapid tag — NOT the generic repos.springrts.com master or a bar:test tag, which are a stale, unrelated community mirror.
- PRD_RAPID_USE_STREAMER=false is required because that CDN serves plain static files and doesn't implement the legacy streaming download endpoint pr-downloader tries by default (it 404s otherwise).
- Mailpit needs the TLS cert flags and auth file above, or account registration fails with a misleading Jason.Encoder/HTTP 500 error — the real cause is that Teiserver's mailer hardcodes tls: :always and auth: :always regardless of env vars, and stock Mailpit doesn't satisfy either by default. If you hit a registration 500 anyway: check whether the account row was already created in Postgres before retrying with the same username — the DB insert happens before the email-send step.

## 5. Bring the stack up

    cd ~/bar-server/docker
    docker compose up -d
    docker compose run --rm games-updater

Database migrations run automatically at container boot — don't run a manual migrate command. games-updater is a one-shot job excluded from the default up (via its tools profile); run it once now, and again in future whenever you deliberately bump RECOIL_ENGINE_VERSION or the content tag, since nothing here updates them automatically.

You do NOT need to manually create a bot account for SPADS in the admin panel. Its Docker image fully automates the SPADS install, and an AutoRegister plugin makes the bot self-register with Teiserver the first time it connects, using the SPADS_LOBBY_LOGIN/SPADS_LOBBY_PASSWORD already in .env. Confirm it worked with `docker compose logs spads --tail 80`.

## 6. Create the admin account

With TEI_SETUP_ROOT_KEY set, find and visit the setup route that consumes it (check lib/teiserver_web/controllers/account/setup_controller.ex in the cloned repo for the exact current path — it has moved between versions) to bootstrap a root@localhost account, whose password becomes that key's value.

Log in as root, then IMMEDIATELY enroll TOTP at /teiserver/account/security/totp/edit, before trying any admin page. Every privileged role (Admin, Moderator, Server, Overwatch, Contributor) is hard-gated on having TOTP configured — a fresh account without it gets a bare, unhelpful "Unauthorized" on every privileged action with no explanation of why.

Register my real account through the normal /register page, then, from the root session, grant it the Admin role via the admin user page, and enroll TOTP for it too.

One non-obvious role fact: Server is a SUPERSET of Admin, not the other way around. Holding Admin alone will NOT unlock Server-gated pages like telemetry or several moderation reports — that's the opposite of what you'd naturally assume. There is no UI path to grant Server directly; do it via SQL:

    docker exec bar-teiserver-db psql -U teiserver_prod -d teiserver_prod -c \
      "UPDATE account_users SET roles = array_append(roles, 'Server') WHERE name = 'MYUSERNAME' AND NOT ('Server' = ANY(roles));"

Two gotchas with this: Teiserver caches user rows in memory (ETS), so a raw SQL edit can be silently clobbered the next time the app updates that same row on its own — prefer the app's own update functions when practical, and re-check the role stuck afterward. And if a role change doesn't seem to show up in the UI even after it's confirmed in the database, do a full page reload / re-login rather than assuming the grant failed — an already-open LiveView session only loads current_user once, at socket-mount time, and won't reflect a mid-session DB change until it's torn down and reopened.

Reach the containerized Postgres only via `docker exec bar-teiserver-db psql ...` — never via a host-level `psql -h localhost`, which is very likely to silently hit a completely unrelated Postgres instance already running on the machine instead of this one.

## 7. Verify with a real match

Confirm the autohost shows up as connected/registered (`docker compose logs spads`), then connect with the actual BAR game client from a SEPARATE machine — never install or run the game client on the server host itself, since a client and server sharing one machine's own network stack can mask exactly the kind of connectivity bug this stack is prone to. Play one full match end-to-end before calling this done.

## 8. Before exposing this beyond your LAN

Only do this section if I've told you I want public/internet access, not just LAN. Ask me to confirm before doing any of this:
- Enable and actually configure a firewall (ufw or equivalent) — a fresh Ubuntu install commonly has one present but DISABLED, which means nothing is filtering inbound traffic until it's turned on.
- Put a reverse proxy and TLS termination in front of the web/admin port (4000).
- Rotate every secret generated above, and any placeholder account password, before treating this as more than a private test.
- Double check you haven't left any local-debugging rate-limit relaxations in place — they should never carry into a public-facing deployment.
- Consider (all optional, and none configured by default because they need external services/API keys I may not have): an email domain blocklist for registration, a VPN/IP-reputation check via a third-party API, and requiring game-client hardware data before play (this makes the automatic MAC-hash smurf-ban system, which is already present in the code, actually effective).
- Think specifically about how the lobby server will observe the autohost's source IP in whatever hosting environment this is (cloud VPS NAT/load-balancer setups can reintroduce the exact same hairpinning-style bug described in step 4, even without Docker's bridge network being the cause) — verify a real match again after any networking change here, don't just assume it still works.

## 9. Ongoing maintenance

There is no automatic update mechanism for the game engine or content version — RECOIL_ENGINE_VERSION and the rapid tag in .env/compose are pinned values you (or I) update deliberately, then re-run `docker compose run --rm games-updater`. Docker's restart: unless-stopped brings containers back after a crash or Docker daemon restart, but starting the whole stack automatically at OS boot still requires Docker's own systemd service to be enabled — check `systemctl is-enabled docker` and set up a boot-start mechanism if I want that.

When you're done, report back to me: the URL to reach the web UI, the root setup-key login URL you used, confirmation that `docker compose ps` shows all containers healthy, and the exact IP/domain value you configured everywhere above, so I can note it down.