Foundry logo Foundry Docker guide
Deployment Guide

Running Foundry with Docker

Foundry ships two Docker Compose shapes: a local-development default and a stricter production-oriented setup. This page explains when to use each one and what each overlay expects.

Default Docker workflow

The default docker-compose.yml is meant for local development. It keeps the source tree bind-mounted into the container so code, themes, and content edits are reflected immediately. 

sh scripts/docker-init.sh
docker compose up -d --build

That setup:

  • bind-mounts the project root into /app
  • keeps data/ and public/ on named Docker volumes
  • uses content/config/site.docker.yaml as the config overlay
  • reads local Docker secrets from .env when present
  • can bootstrap a local .env with scripts/docker-init.sh

Local secret bootstrap

scripts/docker-init.sh creates a local .env file if one does not exist and fills in:

  • FOUNDRY_PUBLISH_ADDR
  • FOUNDRY_ADMIN_SESSION_SECRET
  • FOUNDRY_ADMIN_TOTP_SECRET_KEY

Those values are for local Docker convenience. They are not the production deployment path.

Production-oriented Docker workflow

The stricter setup lives in docker-compose.prod.yml. Use it when you want a safer immutable-style container shape instead of a source-mounted development container. 

export FOUNDRY_ADMIN_SESSION_SECRET="$(openssl rand -hex 32)"
export FOUNDRY_ADMIN_TOTP_SECRET_KEY="$(openssl rand -base64 32)"
docker compose -f docker-compose.prod.yml up -d --build

That setup:

  • requires explicit session and TOTP secrets
  • runs with a read-only root filesystem
  • uses tmpfs for /tmp
  • drops Linux capabilities
  • enables no-new-privileges
  • uses named volumes for content/, themes/, plugins/, data/, and public/
  • uses content/config/site.docker.prod.yaml as the config overlay

Important config overlays

  • content/config/site.docker.yaml: development-oriented Docker defaults like local base URL and live reload enabled.
  • content/config/site.docker.prod.yaml: production-shaped Docker defaults like disabled live reload, disabled debug surfaces, and explicit production environment labeling.

Before using the production overlay, set content/config/site.docker.prod.yaml base_url to the real HTTPS origin for the deployment.

Operational notes

  • Set strong values for FOUNDRY_ADMIN_SESSION_SECRET and FOUNDRY_ADMIN_TOTP_SECRET_KEY in production.
  • Keep the production admin behind HTTPS so secure cookies behave correctly.
  • The default Docker setup is convenient for development, but the production compose file is the right base for a real deployment.
  • The Dockerfile creates runtime directories inside the image; generated output belongs on the writable public/ volume, not in the image layer.

Related docs