Godot Encore

Appearance

Deployment (Ubuntu 24.04) ​

This guide deploys Encore Server as a systemd service on Ubuntu 24.04 with optional cgroup v2 limits.

Preflight checklist ​

  • Ubuntu 24.04 host (Linux x64)
  • build-essential and Rust toolchain installed
  • Unified cgroup v2 mounted at /sys/fs/cgroup
  • Server binaries and ports reachable by game clients

Install binary and config ​

bash
cargo build --release --manifest-path server/Cargo.toml
sudo install -D -m 0755 server/target/release/encore /usr/local/bin/encore

sudo install -d -m 0755 /etc/encore/templates
sudo install -d -m 0755 /var/lib/encore/uploads
sudo install -m 0644 server/config.example.toml /etc/encore/config.toml

Update bind, template_folder, and optional admin_token in /etc/encore/config.toml. The templates directory can be empty at startup — templates can be added later via the admin API or by dropping .toml files into the folder and calling POST /api/v1/serve/reload.

If you plan to use the binary upload API, set upload_folder in your config (defaults to <template_folder>/../uploads/). The directory is created automatically on startup if it doesn't exist.

Install systemd unit ​

bash
sudo install -D -m 0644 deploy/systemd/encore.service /etc/systemd/system/encore.service

If needed, edit User, Group, and ExecStart:

bash
sudo systemctl edit --full encore

Start service ​

bash
sudo systemctl daemon-reload
sudo systemctl enable --now encore
sudo systemctl status encore

cgroup v2 warnings and verification ​

If you use template cgroup limits, systemd delegation is mandatory for non-root deployments.

The provided unit includes:

  • Delegate=cpu memory pids
  • DelegateSubgroup=encore
  • accounting flags for CPU/memory/tasks

Verify delegation:

bash
CG=$(systemctl show -p ControlGroup --value encore)
echo "$CG"
sudo cat /sys/fs/cgroup$CG/cgroup.subtree_control

Expected controllers include cpu, memory, and pids.

Important operational note:

  • If cgroup setup fails for a template that requires it, instance spawn fails (fail-closed behavior).

Validate before go-live ​

bash
encore validate --config-file /etc/encore/config.toml

Then run smoke checks:

bash
curl http://127.0.0.1:8080/health
curl -X POST http://127.0.0.1:8080/api/v1/instances \
  -H "Content-Type: application/json" \
  -d '{"template_id":"game_QkMtDm7A2x","extra_options":{"max_players":"10"}}'

Operations ​

  • Follow logs: journalctl -u encore -f
  • Restart service: sudo systemctl restart encore
  • Reload templates at runtime (admin auth): POST /api/v1/serve/reload

Common pitfalls ​

  • admin_token not set: admin routes are unavailable by design.
  • public_host not set or incorrect in config.toml: clients receive unusable connection endpoints.
  • Port range too small: frequent no_ports_available.
  • cgroup delegation missing: isolated templates fail to spawn.