Skip to content
Esc

Environment variables

Every environment variable read by the Dockmesh server, the agent, dmctl and the install scripts, with defaults.

Dockmesh has no configuration file format of its own. The server reads DOCKMESH_* environment variables at startup; everything else lives in the database and is changed in the UI. configs/dockmesh.example.yaml in the repository is not parsed by anything.

On a normal install the variables live in dockmesh.env in the data root (/var/lib/dockmesh/dockmesh.env by default). systemd loads it with EnvironmentFile=, launchd passes it as --env-file, and the dockmesh admin commands load it automatically (see dockmesh commands). Edit the file and restart the service to apply a change:

shell
sudo systemctl restart dockmesh
dockmesh config show   # check what the server will see

Boolean variables are case-sensitive: “on by default” variables are only switched off by the exact value false, “off by default” ones only switched on by true. An empty value counts as unset.

VariableDefaultMeaning
DOCKMESH_HTTP_ADDR:8080Listen address for the web UI, REST API, /metrics and /install/*. Plain HTTP
DOCKMESH_BASE_URLhttp://localhost:8080Public URL of the server. Wins over Base URL under Settings → General for SSO callback URLs, invite links and agent install commands
DOCKMESH_AGENT_LISTEN:8443Listen address of the agent listener. It always runs; an empty value falls back to the default
DOCKMESH_AGENT_PUBLIC_URLunsetwss:// URL agents enroll at and connect to. Wins over Agent public URL under Settings → General. With neither set: wss://<host of the base URL>:<port of DOCKMESH_AGENT_LISTEN>/connect
DOCKMESH_AGENT_SANSemptyComma-separated extra host names and IPs for the agent listener certificate. localhost, 127.0.0.1, ::1 and the agent URL’s host are always included
DOCKMESH_AGENT_ENROLL_TOKEN_TTL24hLifetime of host enrollment tokens, as a Go duration from 1m to 720h. Any other value stops the server at startup
DOCKMESH_TRUSTED_PROXIESunsetUsed when Trusted proxies under Settings → General is empty: comma-separated IPs or CIDRs whose forwarding headers are believed. With neither, only localhost

The web setup wizard stores the address you enter as the Base URL and Agent public URL settings, so agent install commands work without editing dockmesh.env. SSO callbacks and invite links don’t read those settings; when you use them, also set the public URL in dockmesh.env:

shell
DOCKMESH_BASE_URL=https://dockmesh.example.com

dockmesh init writes DOCKMESH_BASE_URL, DOCKMESH_AGENT_PUBLIC_URL and DOCKMESH_AGENT_SANS into the file it creates; on those installs the environment wins over the Settings fields.

VariableDefaultMeaning
DOCKMESH_DB_PATH./data/dockmesh.dbSQLite database. Its directory is the data directory: PKI files and git-cache/ go there too
DOCKMESH_STACKS_ROOT./stacksStacks directory, one subdirectory per stack
DOCKMESH_SECRETS_PATH./data/secrets.envFile holding DOCKMESH_JWT_SECRET; created on first start
DOCKMESH_SECRETS_KEY_PATH./data/secrets.age-keyage key that encrypts stack .env files and stored credentials
DOCKMESH_AUDIT_GENESIS_PATH./data/audit-genesis.sha256Genesis hash of the audit log chain
DOCKMESH_INSTALL_SCRIPT./scripts/install-agent.shTemplate served at /install/agent.sh
DOCKMESH_BINARY_DIR./binDirectory with the agent binaries (dockmesh-agent-linux-amd64, -arm64) served under /install/ and to agents for upgrades. dmctl binaries are served from it only if you copy them in

Relative defaults resolve against the server’s working directory. The installers write absolute paths. See Filesystem layout.

VariableDefaultMeaning
DOCKMESH_SECRETS_ENCRYPT_ENVtrueEncrypt stack .env files as .env.age. With false, .env is stored in plaintext and values meant for encrypted DB columns are stored in plaintext as well
DOCKMESH_SCANNER_ENABLEDtrueDefault for Scan images with Grype under Settings → General; a value saved there wins. Scanning also needs the binary to be present
DOCKMESH_SCANNER_BINARYgrypeName or path of the Grype binary, looked up in PATH
DOCKMESH_PROXY_ENABLEDfalsetrue turns the reverse proxy on while the proxy_enabled setting has never been saved. See the note below
DOCKMESH_PROXY_IMAGEcaddy:2.11.7 pinned by digestCaddy image for the dockmesh-proxy container. While it is set, the Caddy version can’t be switched from the UI or API
DOCKMESH_METRICS_AUTHtrueRequire a bearer token with metrics.view on /metrics. false makes it public
DOCKMESH_SETUP_FORCEfalseStart in setup mode and skip creating the bootstrap admin. install.sh sets it; the web wizard removes it from dockmesh.env when it finishes
DOCKMESH_UPDATE_ROLLBACK_KEEP3How many rollback tags per image container updates keep. Must be a positive number, or the server doesn’t start
DOCKMESH_SKIP_PREMIGRATE_BACKUPunset1 or true skips the database copy (<db>.pre-migrate-<time>.bak) taken before schema migrations, for example when the disk is too full for it

Note: Whether the reverse proxy starts follows the proxy_enabled setting, which the enable and disable buttons on the Reverse proxy page save. DOCKMESH_PROXY_ENABLED=true only counts while that setting has never been saved. Once you enable or stop the proxy on the page, the saved choice wins over the variable. See Reverse proxy.

VariableDefaultMeaning
DOCKMESH_LOG_FORMATjsonjson or text (to stdout)
DOCKMESH_LOG_LEVELinfodebug, info, warn or error
DOCKMESH_OTEL_ENDPOINTemptyOTLP/gRPC endpoint for traces; empty disables tracing
DOCKMESH_OTEL_INSECUREfalsePlaintext connection to the OTLP endpoint

Tracing does not start: initialisation fails with a resource schema conflict, which the server logs as a warning and continues without tracing.

Variables that are not read from the environment

Section titled “Variables that are not read from the environment”

DOCKMESH_JWT_SECRET is a line inside the secrets.env file, not an environment variable. Setting it in the environment does nothing. Losing the file signs everyone out.

The server connects to Docker with the standard Docker client variables (DOCKER_HOST, DOCKER_API_VERSION, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY). Without them it uses /var/run/docker.sock.

The server runs in the time zone of its process (TZ, otherwise the system zone). Backup schedules use it unless the backups.timezone setting names another zone; see Backups.

Written by install-agent.sh to /etc/dockmesh-agent/agent.env.

VariableDefaultMeaning
DOCKMESH_DATA_DIR/var/lib/dockmeshAgent state: certificate, key, CA, saved URL, staging and stack mirror. The installer writes /var/lib/dockmesh-agent
DOCKMESH_ENROLL_URLnoneEnrollment endpoint on the agent port (https://<host>:8443/enroll), required on first start
DOCKMESH_TOKENnoneOne-time enrollment token, required on first start. It stays in agent.env after enrollment
DOCKMESH_CA_FINGERPRINTnoneSHA-256 fingerprint of the server’s agent CA. Required for enrollment over https://; the CA the server returns must match it
DOCKMESH_ENROLL_CA_FILEnonePEM file with the agent CA, trusted for the enrollment request. Required for enrollment over https://; it must match DOCKMESH_CA_FINGERPRINT
DOCKMESH_AGENT_URLsaved at enrollmentwss:// URL of the server’s agent listener. Overrides the saved one
DOCKMESH_INSECURE_ENROLLunsettrue allows enrollment over plain http://, like the --insecure-enroll flag. For isolated labs only
VariableMeaning
DMCTL_SERVERServer URL, used when --server is not given
DMCTL_TOKENAPI token or access token, used when --token is not given

Set these in front of bash when piping the installer, for example curl -fsSL https://get.dockmesh.dev | sudo DOCKMESH_NO_SCANNER=1 bash.

VariableDefaultMeaning
DOCKMESH_VERSIONlatestRelease tag to install
DOCKMESH_CHANNELstablestable or testing
DOCKMESH_INSTALL_DIR/usr/local/binDirectory for dockmesh, dmctl and grype
DOCKMESH_ASSET_DIR<install-dir>/../share/dockmeshAgent installer and agent binaries
DOCKMESH_DATA_DIRthe directory of an earlier install’s dockmesh.env; otherwise /data if it exists and is writable (or the script runs as root), else /var/lib/dockmesh (Linux) or /usr/local/var/dockmesh (macOS)Data root. Setting it to a different directory than an earlier install’s stops the script
DOCKMESH_NO_SUDO01 runs without sudo
DOCKMESH_FORCE01 reinstalls even if the same version is installed
DOCKMESH_NO_SCANNER01 skips installing Grype
DOCKMESH_SKIP_CHECKSUM01 installs without checking the release tarball against checksums.txt; the binary runs as root, so only for a build you verified yourself
DOCKMESH_SKIP_DOWNLOAD01 uses the binary already in the install directory
DOCKMESH_NO_BOOTSTRAP01 skips creating the service user, env file and service; run dockmesh init yourself
NO_COLORunsetAny value disables colours

dockmesh init also honours DOCKMESH_ASSET_DIR when it writes DOCKMESH_INSTALL_SCRIPT and DOCKMESH_BINARY_DIR.

The server fills in the token, the URLs, the agent CA and the binary checksums when it serves the script. It accepts two flags, --as-root (run the agent as root instead of a dockmesh-agent user) and --skip-docker. The only variable it reads is AGENT_WAIT_SECS (default 60): how long it waits for the agent to connect. Pass it through sudo, for example | sudo AGENT_WAIT_SECS=120 bash.

VariableDefaultMeaning
DOCKMESH_INSTALL_DIR/usr/local/binWhere to remove dockmesh, dockmesh.bak and dmctl from
NO_COLORunsetDisables colours

It finds the data root and the asset directory by looking for dockmesh.env in /var/lib/dockmesh, /usr/local/var/dockmesh, /opt/dockmesh and /data. Flags: --yes, --purge (also deletes the data root), --dry-run. See Uninstall.

These keys live in the settings table and are edited in the UI or with PUT /api/v1/settings. Each has an environment variable that takes part as described.

KeyWhere in the UIEnvironment variable
base_urlSettings → General → Base URLDOCKMESH_BASE_URL wins
agent_public_urlSettings → General → Agent public URLDOCKMESH_AGENT_PUBLIC_URL wins
trusted_proxiesSettings → General → Trusted proxiesDOCKMESH_TRUSTED_PROXIES is used while the setting is empty
scanner_enabledSettings → General → Vulnerability scannerTurns image scanning on or off without a restart. DOCKMESH_SCANNER_ENABLED only sets the default
proxy_enabledReverse proxy page, enable and disableDOCKMESH_PROXY_ENABLED=true counts as true until the setting is saved

The release check against GitHub is set under Settings → Updates (update_check_enabled, update_check_interval_minutes); it has no environment variable.