Docker Deployment

Run ModulaCMS in Docker containers with your choice of database backend and MinIO for S3-compatible media storage.

Available Stacks

Full Stack

Starts the CMS with all three database engines (SQLite, MySQL, PostgreSQL) and MinIO:

just dc full up

Single Database Stacks

Run the CMS with a specific database backend:

# SQLite
just dc sqlite up

# MySQL
just dc mysql up

# PostgreSQL
just dc postgres up

Infrastructure Only

Start only the supporting services (PostgreSQL, MySQL, MinIO) without the CMS binary. Useful when you want to run the CMS locally against containerized databases:

just docker-infra

Managing Stacks

All Docker commands use just as the task runner. The just dc command accepts a backend and an action:

just dc <backend> <action>

Backend	Compose File
`full`	`deploy/docker/docker-compose.full.yml`
`sqlite`	`deploy/docker/docker-compose.sqlite.yml`
`mysql`	`deploy/docker/docker-compose.mysql.yml`
`postgres`	`deploy/docker/docker-compose.postgres.yml`

Action	Description
`up`	Build images and start all containers
`down`	Stop containers, keep volumes
`reset`	Stop containers and delete volumes (destroys data)
`dev`	Rebuild and restart only the CMS container
`fresh`	Delete volumes, rebuild, and start everything from scratch
`logs`	Follow CMS container logs
`destroy`	Stop containers, delete volumes, and remove all images (`full` backend only)
`minio-reset`	Reset the MinIO container (`postgres` backend only)

Examples

Rebuild the CMS container after code changes without touching the database:

just dc sqlite dev

Wipe all data and start fresh:

just dc mysql fresh

View CMS logs:

just dc postgres logs

Destroy everything including images (full backend only):

just dc full destroy

Volume Management

Docker volumes persist data between container restarts. Understanding when data is preserved and when it is destroyed matters:

Command	Containers	Volumes	Images
`just dc <backend> down`	Stopped	Preserved	Preserved
`just dc <backend> reset`	Stopped	Deleted	Preserved
`just dc <backend> fresh`	Restarted	Deleted	Rebuilt
`just dc full destroy`	Stopped	Deleted	Deleted

Use down during normal development. Use reset or fresh when you want to start with an empty database. Use destroy (full backend only) when you need to clear cached Docker layers.

Good to know: The CMS binary is built inside the Docker image using a multi-stage build with CGO enabled for SQLite support. Configuration inside Docker containers uses the same modula.config.json format as bare-metal deployments.

Building the CMS Image

Build a standalone CMS image without starting any services:

just docker-build

This produces a modula image tagged as latest, suitable for CI pipelines or custom deployments.

Releasing Container Images

Tag and push the CMS image to a registry:

just docker-release

This tags the image with both latest and the current version from justfile, then pushes both tags to the configured registry.

MinIO for Local S3

All Docker stacks include MinIO for S3-compatible media storage. When running in Docker, the CMS connects to MinIO using the container hostname (minio:9000), but browsers need the externally reachable address.

Set bucket_public_url in your modula.config.json to the address accessible from outside Docker:

{
  "bucket_endpoint": "minio:9000",
  "bucket_public_url": "http://localhost:9000"
}

To start MinIO independently for running integration tests:

just test-minio       # Start MinIO
just test-integration # Run S3 integration tests
just test-minio-down  # Stop MinIO