Skip to content
Esc

Architecture

The pieces that make up a Dockmesh installation, where each kind of state lives, and how a request or deploy travels through the system.

Dockmesh is one server binary, dockmesh. It serves the web UI and the REST API, talks to the Docker engine on its own machine, and accepts connections from agents on other machines. Two helpers are optional and run outside the binary: the Caddy reverse proxy (as a Docker container) and the Grype vulnerability scanner (as a subprocess).

Diagram: the browser and dmctl reach the dockmesh server over HTTP on port 8080; the server drives the local Docker engine, runs grype and configures the dockmesh-proxy container through the Caddy admin API; agents on other hosts dial out to the server over a mutual-TLS WebSocket on port 8443.

ComponentWhat it isNotes
dockmesh serverGo binary with the SvelteKit UI embeddedListens on DOCKMESH_HTTP_ADDR (default :8080) for the UI and API, and on DOCKMESH_AGENT_LISTEN (default :8443) for agents.
Web UISingle-page app served by the serverFetches everything from /api/v1. There is no separate frontend server.
SQLite databasemodernc.org/sqlite, file at DOCKMESH_DB_PATH (default ./data/dockmesh.db)The only supported database.
Local Docker engineReached through the Docker SDKConnection settings come from the standard Docker environment (DOCKER_HOST etc.), usually the local socket. Dockmesh never shells out to the docker CLI.
dockmesh-agentSmall binary on each remote hostDials out to the server over a mutual-TLS WebSocket and runs Docker operations locally on the server’s behalf. See Hosts and agents.
Reverse proxyDocker container dockmesh-proxy running a pinned, tested caddy image (or DOCKMESH_PROXY_IMAGE)Only exists when the proxy is enabled (DOCKMESH_PROXY_ENABLED=true or the proxy_enabled setting). Dockmesh configures it over Caddy’s admin API on a private Unix socket. See Reverse proxy.
Vulnerability scannerExternal grype binary, run as a subprocessscripts/install.sh installs it unless DOCKMESH_NO_SCANNER=1. The Dockerfile in the repository does not include it. Binary path: DOCKMESH_SCANNER_BINARY (default grype). See Vulnerability scanning.
dmctlCommand-line clientTalks to the same REST API with an API token or a username and password. See dmctl.

Caddy and Grype are not compiled into Dockmesh. If the proxy is off and Grype is not installed, the server runs fine without them; only those features are unavailable.

Dockmesh splits state between the filesystem and the database on purpose.

On the filesystem (source of truth for what runs):

  • Stack definitions: <stacks root>/<name>/compose.yaml, the stack’s .env or encrypted .env.age, optional compose.<env>.yaml override files and .dockmesh.meta.json. The stacks root is DOCKMESH_STACKS_ROOT (default ./stacks). See Stacks.
  • The data directory, which is the directory containing the database file. It holds the internal CA and server certificate for agents and the git-source cache (git-cache/). The JWT secret (secrets.env, DOCKMESH_SECRETS_PATH) and the age key used to encrypt stack secrets (secrets.age-key, DOCKMESH_SECRETS_KEY_PATH) are in ./data by default too, but their paths do not follow DOCKMESH_DB_PATH. A local backup target without a path writes to backups/ in the data directory (see Backups).

In SQLite (runtime and management state):

  • Users, sessions, roles, permissions, scopes, API tokens, invites, SSO provider configuration.
  • Which host each stack is deployed on, deploy history, stack dependencies, git-source bindings, templates, global environment variables.
  • Agents and host tags, backup jobs and runs, alert rules and history, notification channels, proxy routes, registry credentials, scan results, metrics history, the audit log and settings.

Compose files are never stored only in the database. If you lose the database you still have every stack on disk, but you lose users, deployment records and history. Back up both; the system backup covers the database, the stacks directory and the data directory. See Backups and Filesystem layout for the full tree.

  1. The browser or dmctl sends a request to /api/v1/... with a bearer token. Browser sessions use a 15-minute access token plus a refresh token; scripts use API tokens (dmt_...).
  2. The auth middleware checks the token and evaluates the user’s current assignments on every request, so access changes take effect immediately.
  3. Most routes are gated by one permission such as stacks.deploy. Handlers that act on a specific host or stack also check scope. See Permissions.
  4. The handler picks the target host from the ?host= query parameter. No parameter or local means the local host; an agent ID means that remote host. List endpoints also accept ?host=all and query every online host in parallel.
  5. For the local host the server calls the Docker SDK directly. For a remote host it sends a request frame over the agent’s WebSocket and waits for the reply.

Live logs, exec shells, container stats and the event feed run over WebSockets under /api/v1/ws/. The UI first gets a short-lived, single-use ticket for one permission from POST /api/v1/ws/ticket, then opens the socket with it.

  1. You click Deploy (or run dmctl stacks deploy). The server reads compose.yaml and the decrypted .env from the stack directory, and merges global environment variables. Stacks it depends on that aren’t running on the target host yet are deployed first, in dependency order. If an environment override is active, it is merged into compose.yaml first, interpolated with the same environment (global variables plus the stack’s .env).
  2. The server sends the compose text and environment to the target: the local host, or the agent on a remote host.
  3. On the target, Dockmesh writes both into a temporary staging directory, parses them with the Compose library, and reconciles with the Docker SDK: networks, then volumes, then image pulls, then each service in alphabetical order (remove the old container, create, start, wait for health).
  4. The server records which host the stack is on and adds a deploy-history entry. For remote hosts it also pushes a copy of the stack files to the agent.

The deploy runs inside the HTTP request. The details of what reconcile does, including which Compose fields are honoured, are in Stacks.

PortListenerWho connects
8080/tcpUI, REST API, WebSockets, /metrics, agent install script and binaries (/install/)Browsers, dmctl, hosts running the agent installer
8443/tcpAgent enrollment (/enroll), mTLS WebSocket (/connect) and agent upgrade downloadsAgents only
80/tcp, 443/tcpCaddy in dockmesh-proxy (host network)Your users, only when the proxy is enabled

The 8080 listener speaks plain HTTP. Put TLS in front of it with a reverse proxy, or use the managed proxy. See Ports and Security hardening.