6.5 KiB
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. 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.
Initial setup
Open /setup, create the first administrator, 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.
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 volume during an update.
Volumes and persistent data
| Host setting | Container path | Contents |
|---|---|---|
DOGAMA_DATA_PATH |
/var/lib/dogama |
SQLite database, imports 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 is an internal named volume. It contains the shared authentication token and the authenticated agent registry that prevents operations against unknown containers. It is not a user configuration surface, but it must be backed up with the other DoGaMa state.
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 |
latest |
Image version; pin a release in production |
DOGAMA_HTTP_PORT |
8080 |
Published web port |
TZ |
UTC |
Container timezone |
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; 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, 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-serversand/srv/game-backupsinside 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
- 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.