Environment Variables Reference

You don’t normally need this page. The one-liner installer writes a sensible dockmesh.env for you, and the first-boot Setup Wizard lets you configure base URL, admin user, and the core options through the browser. Anything you’d want to change later — proxy on/off, scanner on/off, base URL, agent public URL, session policy, SSO providers — lives in Settings in the UI and is stored in the SQLite settings table, not in environment variables.

Env vars exist for the edge cases where the UI can’t reach you yet:

Docker-image deployment — passing -e DOCKMESH_BASE_URL=… instead of running the wizard
Path customisation — DB on SSD, stacks tree on a bigger spinning disk
Unattended CI rebuilds — scripted boots that must run before any browser is involved
Debugging — DOCKMESH_LOG_LEVEL=debug for one restart

The installer’s dockmesh.env and the systemd EnvironmentFile= line are managed by dockmesh init; hand-editing them survives upgrades but is rarely necessary. Where a value can also be set in the UI, the env var only acts as the initial default on first boot — runtime changes via Settings win and persist in the DB.

Server — paths

Variable	Default	Description
`DOCKMESH_DB_PATH`	`./data/dockmesh.db`	Path to the SQLite database file
`DOCKMESH_STACKS_ROOT`	`./stacks`	Root directory for stack compose files
`DOCKMESH_SECRETS_PATH`	`./data/secrets.env`	Path to the secrets env file (JWT secret, etc.)
`DOCKMESH_SECRETS_KEY_PATH`	`./data/secrets.age-key`	Path to the age key used to encrypt stack `.env` files at rest
`DOCKMESH_AUDIT_GENESIS_PATH`	`./data/audit-genesis.sha256`	Path to the audit-log genesis hash file

Defaults are relative to the service’s working directory. The dockmesh init installer lays out /var/lib/dockmesh/ on Linux and /usr/local/var/dockmesh/ on macOS and writes absolute values into the systemd / launchd env file.

Server — network

Variable	Default	Description
`DOCKMESH_HTTP_ADDR`	`:8080`	HTTP listen address for the UI and API
`DOCKMESH_AGENT_LISTEN`	`:8443`	mTLS listen address for agent connections
`DOCKMESH_BASE_URL`	`http://localhost:8080`	Public URL for the dockmesh server — used in OIDC callbacks and the UI
`DOCKMESH_AGENT_PUBLIC_URL`	(empty)	Public `wss://` URL agents use to connect back. Derived from `DOCKMESH_BASE_URL` if empty, but setting explicitly is recommended in production.
`DOCKMESH_AGENT_SANS`	(empty)	Comma-separated extra hostnames/IPs added to the server cert that agents connect to

Server — embedded features

Variable	Default	Description
`DOCKMESH_PROXY_ENABLED`	`false`	Enable the embedded Caddy reverse proxy (can be toggled at runtime in the Proxy page)
`DOCKMESH_SCANNER_ENABLED`	`true`	Enable the embedded Grype vulnerability scanner
`DOCKMESH_SCANNER_BINARY`	`grype`	Path / name of the Grype binary to invoke
`DOCKMESH_SECRETS_ENCRYPT_ENV`	`true`	Encrypt stack `.env` files at rest with age. Set to `false` only if you’re managing encryption elsewhere.
`DOCKMESH_METRICS_AUTH`	`true`	Require the `metrics.read` permission on `/metrics`. Set to `false` on a trusted-network Prometheus with host-only firewalling.

Server — logging and tracing

Variable	Default	Description
`DOCKMESH_LOG_FORMAT`	`json`	`json` or `text`
`DOCKMESH_LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error`
`DOCKMESH_OTEL_ENDPOINT`	(empty)	OTLP/gRPC trace exporter endpoint. Empty disables tracing.
`DOCKMESH_OTEL_INSECURE`	`false`	Skip TLS verification on the OTLP exporter

Server — install + RBAC

Variable	Default	Description
`DOCKMESH_SETUP_FORCE`	`false`	Force the Setup Wizard to take over admin creation. Used by the installer when the wizard is driving setup. Default off keeps `dockmesh init --yes` (legacy auto-admin) working unchanged.
`DOCKMESH_RBAC_V2_ENFORCE`	`true`	Enforce role-scope (per-host + per-stack) on typed-resource handlers. Default on — flipping to `false` falls back to permission-only checks (no scope enforcement). Only useful for migrating an older deployment forward in stages.

Server — secrets (auto-managed)

Variable	Default	Description
`DOCKMESH_JWT_SECRET`	(auto-generated)	Stored inside the file pointed to by `DOCKMESH_SECRETS_PATH`. Generated on first boot; do not set manually unless you’re restoring from backup.

Agent binary

The remote-host agent (dockmesh-agent) reads a different, smaller set. These are set by the install command the UI generates — you rarely need to touch them by hand.

Variable	Default	Description
`DOCKMESH_DATA_DIR`	`/var/lib/dockmesh`	Where the agent stores its cert, key, CA bundle, and state
`DOCKMESH_ENROLL_URL`	(required on first run)	`https://<server>/api/v1/agents/enroll` — used with `DOCKMESH_TOKEN` during enrolment
`DOCKMESH_TOKEN`	(required on first run)	The one-time enrolment token from the server
`DOCKMESH_AGENT_URL`	(derived from enrolment response)	`wss://<server>:8443/connect` — used for the persistent connection after enrolment

After the first successful enrolment, the agent persists the URL and cert/key into DOCKMESH_DATA_DIR and can be restarted without DOCKMESH_ENROLL_URL or DOCKMESH_TOKEN.

Examples

Systemd service (server)

The installer writes the real paths for you. A hand-written unit looks roughly like:

[Service]
EnvironmentFile=/var/lib/dockmesh/dockmesh.env
ExecStart=/usr/local/bin/dockmesh serve

And /var/lib/dockmesh/dockmesh.env:

DOCKMESH_HTTP_ADDR=:8080
DOCKMESH_DB_PATH=/var/lib/dockmesh/data/dockmesh.db
DOCKMESH_STACKS_ROOT=/var/lib/dockmesh/stacks
DOCKMESH_SECRETS_PATH=/var/lib/dockmesh/data/secrets.env
DOCKMESH_SECRETS_KEY_PATH=/var/lib/dockmesh/data/secrets.age-key
DOCKMESH_AUDIT_GENESIS_PATH=/var/lib/dockmesh/data/audit-genesis.sha256
DOCKMESH_BASE_URL=https://dockmesh.example.com
DOCKMESH_AGENT_PUBLIC_URL=wss://dockmesh.example.com:8443
DOCKMESH_LOG_FORMAT=json

Docker (server)

docker run -d \
  -p 8080:8080 -p 8443:8443 \
  -e DOCKMESH_BASE_URL=https://dockmesh.example.com \
  -e DOCKMESH_AGENT_PUBLIC_URL=wss://dockmesh.example.com:8443 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v dockmesh-data:/var/lib/dockmesh \
  ghcr.io/blinkmsp/dockmesh:latest