Filesystem Layout

dockmesh treats the filesystem as the source of truth. Knowing where things live helps with backups, migrations, and debugging.

Default paths per platform

dockmesh init (the installer) picks a platform-appropriate data root and writes all the individual path env vars against it. The defaults the installer lays down:

Platform	Data root
Linux (systemd)	`/var/lib/dockmesh`
macOS (launchd)	`/usr/local/var/dockmesh`
Docker image (official)	`/var/lib/dockmesh` inside the container
Bare `dockmesh serve` with no env vars	`./data` and `./stacks` relative to the working directory

Every path below is configurable via env vars — the installer just fills in sensible defaults.

Layout

Using the Linux systemd layout as an example:

/var/lib/dockmesh/
├── data/
│   ├── dockmesh.db              # SQLite: users, roles, deployments, audit, CA refs
│   ├── dockmesh.db-wal          # SQLite write-ahead log
│   ├── dockmesh.db-shm          # SQLite shared memory
│   ├── secrets.env              # JWT signing secret (mode 0600)
│   ├── secrets.age-key          # age key for encrypting stack .env files at rest
│   ├── audit-genesis.sha256     # First row of the audit hash chain
│   ├── agents-ca.crt            # Internal CA cert (10-year validity)
│   ├── agents-ca.key            # Internal CA private key (mode 0400)
│   ├── agents-server.crt        # Server cert for the :8443 mTLS listener
│   └── agents-server.key        # …and its key (mode 0400)
├── stacks/
│   ├── <stack-name>/
│   │   ├── compose.yaml         # Source of truth for the stack
│   │   ├── .env                 # Stack environment (encrypted at rest if enabled)
│   │   └── any-other-files      # Referenced as bind-mounts from compose.yaml
│   └── ...
└── dockmesh.env                 # EnvironmentFile read by the systemd unit

DOCKMESH_DB_PATH, DOCKMESH_STACKS_ROOT, DOCKMESH_SECRETS_PATH, DOCKMESH_SECRETS_KEY_PATH, DOCKMESH_AUDIT_GENESIS_PATH each point at one of the files above; override them independently if you want, for example, the database on a faster disk from the stacks tree.

Critical files for backup

Must back up:

data/dockmesh.db — users, roles, deployments, audit log, settings
data/agents-ca.crt + data/agents-ca.key — the CA. Without it, every agent has to re-enrol after restore
data/secrets.env — the JWT secret. Losing it invalidates every session after restore (users re-login; not catastrophic)
data/secrets.age-key — decrypts encrypted stack .env files. Do not lose this if you rely on at-rest encryption
data/audit-genesis.sha256 — anchors the audit hash chain
stacks/ — compose files + env files

The built-in system-backup job rolls all of the above into a single encrypted tarball on a schedule you set in the UI under Backups. To restore the resulting archive onto a fresh host, run dockmesh restore --from <archive.tar.gz> (see the CLI Reference for flags). For a one-off SQLite-only snapshot without the surrounding files, dockmesh db backup --out <path> does an atomic VACUUM INTO. Full walkthrough: Backup & Restore.

Stack directory

Each stack lives at stacks/<stack-name>/. The stack name is what you type when you create the stack in the UI — it matches com.docker.compose.project on the running containers.

File	Purpose	Managed by
`compose.yaml`	Compose definition	You (or Git-sync, or adopt)
`.env`	Environment vars for `${VAR}` interpolation	You (or the Environment page)
Any other file	Mounted configs, certs, static sites	You

Any file you drop in the directory can be referenced from compose.yaml as a bind-mount:

services:
  nginx:
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro

Docker daemon paths

dockmesh doesn’t own these but interacts with them via the Docker socket:

Path	Contents
`/var/lib/docker/volumes/`	Docker named volumes (your data)
`/var/lib/docker/containers/`	Container runtime state
`/var/lib/docker/overlay2/`	Image layers
`/var/run/docker.sock`	Docker daemon socket (what dockmesh talks to)

Don’t manually modify /var/lib/docker/. Use dockmesh’s UI or the docker CLI.

Log locations

What	Where
dockmesh server logs	systemd journal — `journalctl -u dockmesh`
Agent logs	systemd journal on each agent host — `journalctl -u dockmesh-agent`
Container logs	`/var/lib/docker/containers/<id>/<id>-json.log`, or live via the UI
Audit log	inside `dockmesh.db`; view or export from the Audit page

Permissions

Recommended for a production Linux install (the installer writes these):

Path	Owner	Mode
`/var/lib/dockmesh`	`dockmesh:docker`	0750
`/var/lib/dockmesh/data`	`dockmesh:docker`	0700
`/var/lib/dockmesh/data/*.key`	`dockmesh:docker`	0400
`/var/lib/dockmesh/data/*.db`	`dockmesh:docker`	0600
`/var/lib/dockmesh/stacks`	`dockmesh:docker`	0750

Customising paths

Override any path by setting the corresponding env var before starting the service. For a split filesystem layout (DB on SSD, stacks on a bigger spinning disk):

DOCKMESH_DB_PATH=/mnt/ssd/dockmesh/dockmesh.db
DOCKMESH_STACKS_ROOT=/mnt/hdd/dockmesh-stacks

All path env vars are independent; change as many as you need.

Inside Docker (when running dockmesh itself in a container)

Persist data with a named volume or a bind-mount. The official image uses /var/lib/dockmesh inside the container:

services:
  dockmesh:
    image: ghcr.io/blinkmsp/dockmesh:latest
    ports:
      - "8080:8080"
      - "8443:8443"
    volumes:
      - dockmesh-data:/var/lib/dockmesh
      - /var/run/docker.sock:/var/run/docker.sock
volumes:
  dockmesh-data:

Bind-mount stacks/ separately if you want to edit compose files from the host without going through the dockmesh UI.