Docker Compose

This guide covers running deco Studio with Docker Compose for testing and self-hosted evaluation.

Source (compose files): decocms/studio → deploy/docker-compose

Overview

Studio uses PostgreSQL as its database. The repo ships three compose files under deploy/docker-compose/ — pick by use case:

• docker-compose.postgres.yml — self-host, all-in-one: Studio (published image) plus a fully bundled stack (PostgreSQL + NATS + MinIO), all wired so the app provisions nothing itself. The recommended starting point. (selfhost/examples/docker-compose wraps this with a documented .env.example.)
• docker-compose.yml — self-host, bring-your-own DB: Studio only (published image), expecting a PostgreSQL you provide.
• docker-compose.dev.yml — development: only the dependencies (PostgreSQL + a 3-node NATS cluster, prod-like topology); you run the API and web apps from source with bun run dev:servers. No sandbox here — that needs Kubernetes (see the dev-hybrid loop).

The self-host files use a Docker volume for persistence and an automatic /health check.

Prerequisites

• Docker 20.10+
• Docker Compose 2.0+
• A PostgreSQL database — bundled (via docker-compose.postgres.yml) or your own

Quick Start (bundled PostgreSQL)

# 1. Clone the repo and enter the compose directory
git clone https://github.com/decocms/studio.git
cd studio/deploy/docker-compose
 
# 2. Create a .env with an auth secret, a vault key, and Postgres credentials
cat > .env << EOF
BETTER_AUTH_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -base64 32)
POSTGRES_USER=studio_user
POSTGRES_PASSWORD=$(openssl rand -base64 24)
POSTGRES_DB=studio_db
EOF
 
# 3. Start Studio + PostgreSQL
docker compose -f docker-compose.postgres.yml up -d
 
# 4. Access
open http://localhost:3000

The docker-compose.postgres.yml file wires DATABASE_URL automatically from the POSTGRES_* variables, using the postgres service as the host.

Environment variables

Set these in .env alongside the compose file:

The container runs as user 1001:1001 and persists data to the studio-data volume; the bundled Postgres persists to postgres-data.

Using your own PostgreSQL

To point Studio at an external database, use the base docker-compose.yml and set DATABASE_URL:

# .env
BETTER_AUTH_SECRET=your_generated_secret_here
DATABASE_URL=postgresql://user:password@host:5432/database_name

docker compose up -d

Authentication options

By default the bundled stack uses email/password auth. To enable social login, uncomment and set the provider variables in the compose environment block (or your .env):

AUTH_GOOGLE_CLIENT_ID=...
AUTH_GOOGLE_CLIENT_SECRET=...
AUTH_GITHUB_CLIENT_ID=...
AUTH_GITHUB_CLIENT_SECRET=...

For richer configuration (deployment-wide SSO, email providers, magic links), set the corresponding AUTH_* variables in the compose environment block — there's no config file to mount. See Authentication for the full reference.

Operations

Logs and status

# Follow logs for the app
docker compose logs -f studio
 
# Container status
docker compose ps
 
# Resource usage (container name is "decocms")
docker stats decocms

Update the image

docker compose pull
docker compose up -d

Pin a version by setting IMAGE_TAG in .env before pulling.

Backup and restore (PostgreSQL)

# Backup (bundled Postgres service)
docker compose exec postgres pg_dump -U studio_user studio_db > backup-$(date +%Y%m%d).sql
 
# Restore
docker compose exec -T postgres psql -U studio_user studio_db < backup-20240101.sql

Reset all data

docker compose down -v   # removes named volumes (studio-data, postgres-data)
docker compose -f docker-compose.postgres.yml up -d

Security

• Always generate strong BETTER_AUTH_SECRET and ENCRYPTION_KEY values (openssl rand -base64 32) and a real POSTGRES_PASSWORD.
• Don't commit .env (echo ".env" >> .gitignore; chmod 600 .env).
• Don't commit secrets (client secrets, API keys) into .env or the compose file.