Deployment

Docker

Garden CMS ships with a Containerfile and compose.yaml for container-based deployment.

Quick start with Docker Compose

docker compose up -d

This starts the application and a PostgreSQL database. The app is available at http://localhost:8000.

Production Compose

Create a .env file with your production settings:

DATABASE_URL=postgres://garden:secure-password@db:5432/garden
SECRET_KEY=your-random-secret-key
ADMIN_PASSWORD=your-admin-password

Then run:

docker compose --profile production up -d

Building the image

docker build -f Containerfile -t garden-cms .

Environment variables

See Configuration for the complete list.

Stateless mode

Set STATELESS=true for serverless or multi-instance deployments:

STATELESS=true

In stateless mode, content blocks and storage settings are reloaded from the database on every request instead of being cached in memory. This ensures consistency when multiple instances share a database or when instances are ephemeral (e.g. AWS Lambda, Cloud Run, Fly Machines).

When stateless mode is inactive (default), content is cached in memory at startup and refreshed only when saved through the admin. This is more performant for single-instance deployments.

Reverse proxy

Garden CMS runs as a standard ASGI application on port 8000. Place it behind a reverse proxy (Caddy, nginx, Traefik) for TLS termination:

# Caddyfile example
yoursite.com {
    reverse_proxy garden-cms:8000
}

Security headers

The application sets these headers on all responses:

• X-Frame-Options: DENY
• X-Content-Type-Options: nosniff
• X-XSS-Protection: 1; mode=block
• Referrer-Policy: strict-origin-when-cross-origin
• Vary: HX-Request

Database migrations

After upgrading, run Piccolo migrations:

uv run piccolo migrations forwards db

Or in Docker:

docker compose exec app uv run piccolo migrations forwards db

Hosting

Garden CMS runs as a standard Python ASGI application. It can be deployed to traditional servers, container platforms, or serverless environments. Your choice depends on traffic patterns, budget, and operational preferences.

Stateful hosting

In stateful mode (the default), Garden CMS caches content blocks and storage settings in memory at startup. This is the most performant option for single-instance deployments where the process stays running.

Requirements

• A long-running Python process (not ephemeral)
• PostgreSQL database
• Persistent disk for local media storage, or an S3-compatible bucket

Providers

Example: Fly.io

fly launch --dockerfile Containerfile
fly postgres create
fly postgres attach
fly secrets set SECRET_KEY=your-random-key ADMIN_PASSWORD=your-password
fly deploy

Example: Docker on a VPS

git clone https://github.com/itsnisuxyz/garden-cms.git
cd garden-cms
cp .env.example .env  # edit with your settings
docker compose up -d

Place behind a reverse proxy for TLS:

# Caddyfile
yoursite.com {
    reverse_proxy localhost:8000
}

Serverless hosting

Set STATELESS=true for serverless environments. In this mode, content blocks and storage settings are reloaded from the database on every request instead of being cached in memory. This ensures consistency when instances are ephemeral or when multiple instances run concurrently.

Requirements

• A serverless platform that supports ASGI or container-based functions
• An externally hosted PostgreSQL database (not co-located with the function)
• S3-compatible storage for media (local disk is not available in ephemeral environments)

Providers

Environment variables for serverless

STATELESS=true
DATABASE_URL=postgres://user:pass@your-managed-db:5432/garden
SECRET_KEY=your-random-key
ADMIN_PASSWORD=your-password
S3_BUCKET=your-bucket
S3_REGION=us-east-1
S3_ACCESS_KEY_ID=your-key
S3_SECRET_ACCESS_KEY=your-secret
S3_PUBLIC_URL=https://cdn.yoursite.com

Example: Phemeral

1. Create a project in the Phemeral dashboard
2. Link your repository
3. Push a commit

Phemeral auto-detects the ASGI application and deploys it. Set your environment variables (STATELESS=true, DATABASE_URL, SECRET_KEY, etc.) in the project settings.

Example: Google Cloud Run

# Build and push
gcloud builds submit --tag gcr.io/PROJECT/garden-cms

# Deploy
gcloud run deploy garden-cms \
  --image gcr.io/PROJECT/garden-cms \
  --set-env-vars STATELESS=true,DATABASE_URL=postgres://... \
  --allow-unauthenticated

Database hosting

Garden CMS requires PostgreSQL 14+. For managed options:

Choosing between stateful and serverless