Docker Compose

Docker Compose is the recommended way to run Atrium in production. The official docker-compose.yml starts a PostgreSQL container alongside Atrium and wires them together automatically.

Generate a secret

Before you start, generate a value for BETTER_AUTH_SECRET:

openssl rand -base64 32

Keep this value — you’ll need it in the next step. It must be at least 32 characters and should be treated like a password.

Built-in database

The default configuration starts Atrium with a dedicated PostgreSQL 16 container.

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER:-atrium}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-atrium}
      POSTGRES_DB: ${POSTGRES_DB:-atrium}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-atrium}"]
      interval: 5s
      timeout: 5s
      retries: 5

  atrium:
    image: vibralabs/atrium:latest
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: "postgresql://${POSTGRES_USER:-atrium}:${POSTGRES_PASSWORD:-atrium}@postgres:5432/${POSTGRES_DB:-atrium}"
      BETTER_AUTH_SECRET: "${BETTER_AUTH_SECRET:-change-me-to-a-random-string-at-least-32-chars}"
    volumes:
      - uploads:/app/uploads
    depends_on:
      postgres:
        condition: service_healthy

volumes:
  pgdata:
  uploads:

Save this as docker-compose.yml, then start Atrium:

BETTER_AUTH_SECRET=$(openssl rand -base64 32) \
POSTGRES_PASSWORD=your-secure-password \
docker compose up -d

Open http://localhost:8080 and create your account.

You can also put BETTER_AUTH_SECRET and POSTGRES_PASSWORD in a .env file next to your docker-compose.yml so you don’t have to pass them on the command line every time.

External database

If you already have a PostgreSQL instance, skip the bundled postgres service and point Atrium at your existing database:

services:
  atrium:
    image: vibralabs/atrium:latest
    ports:
      - "8080:8080"
    environment:
      USE_BUILT_IN_DB: "false"
      DATABASE_URL: "postgresql://user:password@your-db-host:5432/atrium"
      BETTER_AUTH_SECRET: "${BETTER_AUTH_SECRET:-change-me-to-a-random-string-at-least-32-chars}"
    volumes:
      - uploads:/app/uploads
    restart: unless-stopped

volumes:
  uploads:

The database schema is applied automatically on startup. If your connection goes through a pooler like PgBouncer, set SKIP_DB_PUSH=true and add a DIRECT_URL pointing to a non-pooled connection. See Docker for details.

Volume mounts

Named volume	Container path	Purpose
`pgdata`	`/var/lib/postgresql/data`	PostgreSQL data for the bundled database
`uploads`	`/app/uploads`	Uploaded files when using local storage

Docker manages these as named volumes. The data lives on your host under Docker’s volume directory and persists across container restarts and image updates.

Starting and stopping

# Start in the background
docker compose up -d

# Stop without removing volumes
docker compose down

# Stop and remove all volumes (destroys data)
docker compose down -v

docker compose down -v deletes your named volumes, including the database and uploaded files. Only run this if you intend to wipe all data.

Adding more environment variables

For the full list of environment variables (storage, email, Stripe, rate limiting, and more), see Docker.

Deployment

Operations

Docker Compose

Generate a secret

Built-in database

External database

Volume mounts

Starting and stopping

Adding more environment variables

​Generate a secret

​Built-in database

​External database

​Volume mounts

​Starting and stopping

​Adding more environment variables

Generate a secret

Built-in database

External database

Volume mounts

Starting and stopping

Adding more environment variables