DoGaMa-serv/docs/operations/deployment-and-release.md

Deployment and release

Production prerequisites

DoGaMa V1 targets one Linux Docker host with the Compose plugin. Put the public application behind a trusted TLS reverse proxy; never publish the agent port. Create the server and backup roots on the host and restrict them to the administrator responsible for DoGaMa. Back up data/dogama.db, the server roots, and the backup roots using host-level tooling.

Create secrets before the first start. Both files must be readable only by the deployment administrator; the master key is exactly 32 bytes and the agent token is at least 32 bytes.

install -d -m 0700 secrets
install -d -m 0750 -o 65532 -g 65532 data
umask 077
head -c 32 /dev/urandom > secrets/master_key
head -c 32 /dev/urandom > secrets/agent_token
docker compose config --quiet
DOGAMA_VERSION=v1.0.0 docker compose up -d

Pin DOGAMA_VERSION to an immutable released version in production. The main application runs as a non-root user with a read-only root filesystem, no Linux capabilities and no Docker socket. The root-running restricted agent is isolated on the private control network, has a read-only root filesystem and no added capabilities; only it receives the Docker socket. The game and backup bind roots remain writable because lifecycle and recovery workflows require them.

TLS termination must retain DoGaMa's CSP, HSTS, frame, MIME and referrer headers. Do not make forwarded client addresses authoritative for login rate limiting. After startup, verify that only the configured application port is published and that normal use redirects to /setup until the first administrator is created.

The application image uses numeric UID/GID 65532:65532. Grant that identity write access to the configured server and backup roots (with ACLs or matching ownership) while keeping access unavailable to unrelated host users.

Release procedure

From a clean, signed-off release commit, run the complete validation gate in AGENTS.md, then create deterministic Linux archives:

make release VERSION=v1.0.0
(cd dist/dogama-v1.0.0 && sha256sum -c SHA256SUMS)

The release command refuses to overwrite an existing release directory. It produces static amd64 and arm64 archives, embedded Go build information, an SPDX 2.3 module SBOM and SHA-256 checksums. SOURCE_DATE_EPOCH defaults to the release commit timestamp and may be supplied explicitly for reproduction.

Build the two OCI images from the same commit and version:

make images VERSION=v1.0.0

The Dockerfile has distinct dogama and dogama-agent targets. Publish both images under the same immutable version and record their registry digests in the release notes. A release is complete only after a fresh-host Compose smoke test, bootstrap, Palworld draft/install against a disposable Docker daemon, backup/restore, failed-update rollback, and the security-denial checks described in the contributor testing guide.

Upgrade and rollback

Stop the application, take a filesystem-consistent copy of the SQLite database, then change only DOGAMA_VERSION and start Compose. Startup applies append-only migrations before serving requests. Preserve the pre-upgrade database copy and all player/backup roots. If startup or validation fails, stop the new containers, restore the database copy, select the prior image version and start again. Never roll back only the database while a newer application is writing to it.