DoGaMa

DoGaMa is a lightweight, self-hosted manager for private Docker game servers. It provides a web interface for families and small groups while keeping direct Docker access isolated in a restricted private agent.

DoGaMa V1 is feature-complete. Linux is the production target; advanced instance, catalog and backup workflows remain partly API-first.

Features

• Local administrator bootstrap, accounts, sessions, roles and per-instance permissions.
• Validated game catalog and deployment previews, with Palworld as the reference integration.
• Controlled create, inspect, start, stop, restart, update and container-only deletion workflows.
• Persistent player data, scheduled and manual backups, safe import, export and restore.
• Digest-aware updates with optional safety backups, readiness checks and rollback.
• Sandboxed WebAssembly game adapters; no native plugins or host scripts.
• Encrypted notification channels, bounded delivery retries and security-focused audit events.
• Responsive server-rendered web interface with no external runtime asset dependency.

Screenshots

The repository currently includes the official banner above but no maintained product screenshots. Screenshots will be added only when they can be kept aligned with released UI behavior.

Installation

Install Docker Engine with the Compose plugin on a Linux host. Create a directory and save the repository's canonical compose.yaml there; optionally copy .env.example to .env and set durable host paths. A complete start is then:

mkdir dogama
cd dogama
docker compose pull
docker compose up -d

The default web address is http://HOST:8080. DoGaMa generates its internal agent token and encryption key automatically on first start; do not create or add them to .env. The repository compose.yaml is the single source of truth for service, volume, network and hardening settings. No separate initialization command, host user, internal UID/GID or secret preparation is required.

For production installation, reverse-proxy and recovery procedures, see deployment and release. For local HTTPS development and browser testing, use the separate development Compose guide; production Compose does not include or require Caddy.

Initial setup

Open /setup, create the first administrator with a valid email address and preferred language, then sign in. Configure global labels and notification channels from Settings. Create game instances only after checking the host paths, ports and backup policy shown by the deployment preview.

During this development phase, SQLite schema changes can require starting again with an empty application database. Versioned migrations will be introduced before production stabilization.

Updating

Pin DOGAMA_VERSION to a released version such as 0.1.0, back up the DoGaMa data directory, then pull and recreate:

docker compose pull
docker compose up -d

Never delete data, the server/backup directories or the internal agent_state and agent_auth volumes during an update.

Volumes and persistent data

Host setting	Container path	Contents
DOGAMA_DATA_PATH	/var/lib/dogama	SQLite database, imports, templates and the application-only master key
DOGAMA_SERVERS_PATH	/srv/game-servers	Game-server configuration and player data
DOGAMA_BACKUPS_PATH	/srv/game-backups	DoGaMa-managed game backups

agent_state and agent_auth are internal named volumes. The first contains the authenticated agent registry that prevents operations against unknown containers; the second contains only the shared authentication token and is the only agent storage mounted read-only by the application. They are not user configuration surfaces, but both must be backed up with the other DoGaMa state.

Local game templates

Templates are stored under ${DOGAMA_DATA_PATH:-./data}/templates on the Docker host, mounted in DoGaMa as /var/lib/dogama/templates. On the first start, DoGaMa copies its official templates there; Palworld is therefore immediately available. Existing local files are never overwritten on a restart or image update.

Create one directory per game and place its template.yaml (plus any local assets it references) in that directory. Open Catalog as an administrator and select Scan to apply additions, edits and removals without restarting the application. Invalid templates are ignored while valid ones remain available; the Scan result identifies each invalid directory without exposing host paths or secrets. See the template guide for the complete format.

Administrators can also record future sources in Administration → Template repositories. These name/HTTP(S)-URL definitions are stored locally only. They do not download, clone, fetch, authenticate to, or synchronize templates; Catalog → Scan continues to read only /var/lib/dogama/templates.

Ports

Port	Exposure	Purpose
8080/tcp	Host, configurable	DoGaMa web interface and API
8081/tcp	Private Compose network only	Authenticated application-to-agent API

Managed game ports are selected per instance from validated templates.

Environment variables

Variable	Default	Purpose
DOGAMA_VERSION	0.2.1	Image version; pin a published release in production
DOGAMA_HTTP_PORT	8080	Published web port
TZ	UTC	IANA container timezone (also used for Audit display, e.g. Europe/Paris)
DOGAMA_DATA_PATH	./data	Host path for DoGaMa data
DOGAMA_SERVERS_PATH	./servers	Host path for game-server data
DOGAMA_BACKUPS_PATH	./backups	Host path for backups
DOGAMA_NETWORK	dogama	Docker network used to reach the web application, including from a reverse proxy
DOGAMA_GAMES_NETWORK	dogama-games	Approved Docker network attached to every created or recreated game container

Internal container paths, allowed roots and service authentication are intentionally not configurable through the public Compose interface. DOGAMA_GAMES_NETWORK is passed to the restricted agent as its fixed allowed network; the agent creates it if absent and lifecycle API requests cannot select another Docker network.

Security

• The main application never mounts the Docker socket.
• Only the private, non-published agent can access Docker, through typed and deny-by-default operations.
• Both images use a root identity inside their container namespaces so fresh bind mounts work without a host-specific image UID. Their root filesystems remain read-only, all Linux capabilities are dropped, Linux file creation uses a private 0077 umask, and no recursive ownership change is performed on application, server or backup data.
• Internal secrets are generated from the operating system cryptographic random source, stored with restrictive permissions and never logged or exposed in the UI.
• The master key is mounted only through the application data path; the agent has no access to it.
• Agent path checks remain fixed to /srv/game-servers and /srv/game-backups inside the containers.

Use a trusted TLS reverse proxy and restrict access to all host data directories. The Docker agent still has host-equivalent power through the socket and must never be published.

Supported platforms

Release images and archives target Linux amd64 and arm64. The full validation suite is designed for Linux; native Windows execution is not supported.

Documentation

• Deployment and release
• Local templates
• Current project state
• Architecture
• Restricted Docker agent
• Security and threat model
• Contributor development guide
• Contributor testing guide

Support and issues

Report reproducible problems in the Gitea issue tracker. Include the DoGaMa version, host architecture and sanitized logs; never attach secrets, databases or player data.

License

No repository-wide license file is currently present, so no general redistribution license is asserted here. The Palworld reference module has its own license. A project-wide license must be added by the owner before public distribution.

Web access and languages

HTTP at HOST:8080 is usable by default, including setup, login, sessions and CSRF protection. HTTPS is recommended for production. In Settings / Web access, an administrator may enable Require HTTPS and optionally set a canonical base URL; configure and verify a trusted HTTPS reverse proxy first. When HTTPS locking is enabled, expose the application backend only to that proxy or another trusted network: X-Forwarded-Proto is useful behind a proxy but is not trustworthy on a directly exposed backend. The initial interface languages are English and French; browser language is used until a user chooses a saved preference.