Docker Deployment

Overview

The repository ships a multi-stage Dockerfile that compiles the standalone mirobody binary and produces a slim runtime image:

builder — Ubuntu 24.04 with the full build toolchain and dev headers; compiles the mirobody executable from the system package set (vcpkg is Windows-only; Linux uses CMake find_package).
runtime — Ubuntu 24.04 with only the shared libraries the binary actually links (extracted via ldd), plus CA certificates for outbound TLS.

The image bakes config.example.yml as the lowest-precedence defaults layer. Real settings come from environment variables or a config.yml you mount at /app/config.yml.

Mirobody ships as a single image you run against your own database (and, optionally, Redis) — there’s no bundled docker compose stack to stand up.

Build and run

Clone

git clone https://github.com/thetahealth/mirobody.git
cd mirobody

Build the image

docker build -t mirobody:latest .

The image links the PostgreSQL backend by default. Choose a different SQL backend with a build arg:

docker build --build-arg MIROBODY_DATABASE_BACKEND=POSTGRESQL_LEGACY -t mirobody:legacy .

Prepare config.yml

cp config.example.yml config.yml

Edit config.yml and set at least one LLM key plus your database connection (see Database backend):

config.yml

GOOGLE_API_KEY: 'AIza...'      # or OPENAI_API_KEY

PG_HOST: 'host.docker.internal'   # a Postgres reachable from the container
PG_PORT: 5432
PG_USER: 'postgres'
PG_DBNAME: 'mirobody'
PG_PASSWORD: '...'
PG_ENCRYPTION_KEY: '...'

Run

The image sets HTTP_PORT=80 internally and runs as an unprivileged user. Mount your config over the baked template:

docker run -p 80:80 \
  -v $PWD/config.yml:/app/config.yml \
  mirobody:latest

The container listens on port 80; the example maps host port 80 to it. Open http://localhost.

Verify

curl http://localhost/api/health   # -> ok

Precedence inside the container is: environment variables → mounted config.yml → remote config → baked config.example.yml. You can therefore configure entirely via -e env vars instead of a file, e.g. -e GOOGLE_API_KEY=... -e PG_HOST=....

Database backend

The SQL backend is compiled into the binary, so it is fixed at image-build time.

Backend	When to use	How
PostgreSQL	Server / multi-user (the desktop default)	Default image; point `PG_*` at your database
SQLite	Self-contained, single-file, no external DB	Build with `--build-arg MIROBODY_DATABASE_BACKEND=SQLITE`
PostgreSQL (legacy schema)	Existing `res/sql/pg_legacy` deployments	`--build-arg MIROBODY_DATABASE_BACKEND=POSTGRESQL_LEGACY`

The shipped Dockerfile installs libpq-dev for the PostgreSQL backends. To build MySQL / DuckDB images, add the matching -dev package to the apt-get install line in the Dockerfile first.

Cache (optional)

The server uses an in-process in-memory cache by default — no Redis needed for a single instance. To share cache state across replicas, run a Redis and set REDIS_HOST (and REDIS_PORT / REDIS_PASSWORD) in your config or via env vars.

Configuration via environment variables

Any config key can be overridden by an env var of the same name (highest precedence). Handy for secrets:

docker run -p 80:80 \
  -e GOOGLE_API_KEY="AIza..." \
  -e PG_HOST="db.internal" \
  -e PG_PASSWORD="..." \
  -e PG_ENCRYPTION_KEY="..." \
  -e CONFIG_ENCRYPTION_KEY="..." \
  mirobody:latest

Management

# Logs (the binary logs to stdout)
docker logs -f <container>

# Stop (SIGTERM triggers a graceful shutdown)
docker stop <container>

# Shell into a running container
docker exec -it <container> /bin/sh

Notes on the runtime image

Static assets and SQL live under /app

The binary resolves res/htdoc (HTTP_ROOT) and res/sql relative to its working directory, so res/ and config.yml sit next to the binary under /app. The web client is served at the container’s port.

No Docker HEALTHCHECK

The runtime image is libraries-only (no curl/wget), so there’s no built-in HEALTHCHECK. Under Kubernetes, use an httpGet liveness/readiness probe against /api/health.

Optional document formats are off

The server image keeps PDF/OCR/.xls off to stay lean (.xlsx via xlnt is built in). To enable PDF/OCR, add the deps and CMake flags to the Dockerfile — see the comments in it and File Processing.

Troubleshooting

Port conflict

Remap the host side: docker run -p 8080:80 …, or change the internal port with -e HTTP_PORT=8080 and map to that.

Container exits immediately

Check docker logs <container> — the most common cause is a database it can’t reach (PG_HOST) or a missing/invalid PG_ENCRYPTION_KEY. Bad connection settings fail startup by design.

Can't reach a database on the host

From the container, the host is host.docker.internal (Docker Desktop) — set PG_HOST to that rather than localhost.

For production hardening, see Production Deployment.

​Overview

​Build and run

​Database backend

​Cache (optional)

​Configuration via environment variables

​Management

​Notes on the runtime image

​Troubleshooting

Overview

Build and run

Database backend

Cache (optional)

Configuration via environment variables

Management

Notes on the runtime image

Troubleshooting