Configuration
dockmesh is configured primarily through the web UI — the one-line installer drops sensible defaults, the first-boot Setup Wizard collects the few things that need a human answer, and from then on everything lives in pages you can click. There is no required hand-edited config file.
Runtime settings (web UI)
Section titled “Runtime settings (web UI)”Stored in the SQLite settings table. Changes take effect immediately without restarting the server.
| Page | What you configure |
|---|---|
| Settings → Instance | Display name, base URL, agent public URL, default-system-backup toggle |
| Settings → Updates | Update channel (stable / testing), self-update behaviour |
| Settings → Configuration | Reverse proxy on/off, vulnerability scanner on/off, metrics auth, secrets-encryption flag |
| Settings → Encryption key | Export / import the age key that protects stack .env files at rest |
| Authentication → Password policy | Min length, complexity, rotation, lockout |
| Authentication → Sessions | Idle timeout, absolute lifetime, remember-me window, max concurrent sessions per user |
| Authentication → Sign-in flow | Allow local password, require 2FA for admin, auto-create accounts on SSO, allow self-registration |
| Authentication → SSO providers | OIDC, OAuth2, SAML, LDAP — one or many, with optional group → role mapping |
| Users → Roles | Custom roles + permission selection (RBAC v2 with per-host / per-stack scope) |
| Alerts → Channels | Email, Slack/Discord/Generic webhook, ntfy, Telegram |
| Alerts → Rules | Thresholds, container/host scope, severity, channel routing |
| Backups | Targets (local / S3 / SFTP / WebDAV / SMB), jobs (schedule, retention, encryption) |
| Environment | Global env vars injected into every stack deploy. Stack-level .env values override globals. |
Environment variables (boot-only)
Section titled “Environment variables (boot-only)”A small set of values must be set before the server can read its own settings table. The installer writes these into /var/lib/dockmesh/dockmesh.env; you rarely edit them by hand.
| Variable | Default | Description |
|---|---|---|
DOCKMESH_HTTP_ADDR | :8080 | HTTP listen address |
DOCKMESH_DB_PATH | ./data/dockmesh.db | SQLite database file path |
DOCKMESH_STACKS_ROOT | ./stacks | Root directory for compose files |
DOCKMESH_AGENT_LISTEN | :8443 | mTLS listen address for agents |
DOCKMESH_BASE_URL | http://localhost:8080 | Public URL — used as initial default for OIDC callbacks and agent links until you set it in the UI |
DOCKMESH_AGENT_SANS | (empty) | Extra SANs for the agent TLS cert |
See the full environment variables reference for log/tracing/path overrides and the agent-side variables.
Global env vars for stacks
Section titled “Global env vars for stacks”Set under Environment in the sidebar. These are merged into every stack’s environment at deploy time. When a stack’s own .env defines the same key, the stack value wins.
Typical entries: TZ, PUID, PGID, shared database credentials, SMTP credentials, common API tokens. Mark a value as Secret to encrypt it at rest and hide it in the UI by default.