Skip to content

Docker Compose

Run an app on any server or computer with Docker Compose, with HTTPS through Caddy.

View as MarkdownCoding agents can read this page at /docs/docker.md

Each app ships a Docker Compose file (apps/<app>/compose.yaml) that starts the app and its own Postgres database, with volumes for the database and for uploaded files. It works on any Linux server (a VPS from any provider, a home server) and on your laptop for a trial.

There are no prebuilt images yet, so Compose builds the image from source. You need a clone of the repository on the machine that runs it.

The examples use the Scheduler. For another app, replace scheduler with the app’s folder name (for example invoicing).

What you need

  • A machine with Docker Engine and the Docker Compose plugin, version 2.24.4 or later (docker compose version).
  • git and openssl.
  • For a public deployment: a domain name you control, and ports 80 and 443 open on the server.

Building the image needs more memory than running it. If the build fails on a small server (1 GB of RAM), add swap space and try again.

Try it on your computer

git clone https://github.com/gtalarico/saas-clones.git
cd saas-clones/apps/scheduler
export AUTH_SECRET=$(openssl rand -base64 32)
docker compose --profile dev up -d --build

Open http://localhost:3000 and create the admin account. The dev profile also starts Mailpit, a fake mail server that catches every email: read them at http://localhost:8025.

The secret only lives in your shell here. For anything you’ll keep, write it to a .env file as described below.

Deploy on a server

1. Point your domain at the server

At your DNS provider, create an A record (and AAAA for IPv6) for the address you want, such as cal.example.com, pointing at the server’s public IP address.

2. Get the code

git clone https://github.com/gtalarico/saas-clones.git
cd saas-clones/apps/scheduler

3. Create the .env file

Compose reads apps/scheduler/.env automatically. It’s ignored by git, so your secrets stay out of the repository. Create it with your values:

cat > .env <<EOF
APP_URL=https://cal.example.com
AUTH_SECRET=$(openssl rand -base64 32)
SMTP_URL=smtp://resend:re_xxxxxxxx@smtp.resend.com:587
EMAIL_FROM=Scheduler <cal@example.com>
EOF
chmod 600 .env
  • APP_URL is the public HTTPS address, with no trailing slash.
  • If a value contains a $, wrap the whole value in single quotes in .env, otherwise Compose treats it as a variable.
  • SMTP_URL and EMAIL_FROM come from your email provider. See the email guide. Set SMTP_URL before going live: the Compose file falls back to the mailpit test server, which only runs with the dev profile, so without SMTP_URL every email fails.
  • Add any other optional variables from the app page (Scheduler or Invoicing), such as GOOGLE_CLIENT_ID or STRIPE_SECRET_KEY, to the same file.

The Compose file already sets these for you, and they take priority over .env:

Variable Value in compose.yaml
DATABASE_URL The bundled Postgres service
STORAGE_DRIVER local
STORAGE_LOCAL_DIR /app/data/uploads, on the appdata volume

To change them (for example to use S3), use an override file as shown in Use S3 storage.

4. Add HTTPS with Caddy

Caddy is a web server that gets and renews HTTPS certificates for you. Run it in the same Compose project, in front of the app.

Create Caddyfile in apps/scheduler:

cal.example.com {
	reverse_proxy app:3000
}

Create compose.override.yaml in the same folder. Compose merges it with compose.yaml automatically:

services:
  app:
    # Only Caddy talks to the app; don't publish port 3000 to the internet.
    ports: !reset []
  caddy:
    image: caddy:2
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    depends_on: [app]
    restart: unless-stopped
volumes:
  caddy_data:
  caddy_config:

If the server already runs a reverse proxy (Caddy, nginx, Traefik), skip this step and point that proxy at localhost:3000 instead.

5. Start it

docker compose up -d --build

Don’t add --profile dev on a public server: it would publish Mailpit’s inbox on port 8025.

6. Check it

docker compose ps                  # app, db and caddy should be running
docker compose logs -f app         # look for: [server] Scheduler listening on :3000 (role=all)
curl -fsS https://cal.example.com/api/health
# {"ok":true,"db":true,"version":"dev"}

Then open https://cal.example.com/setup and create the admin account. See first admin.

Use S3 storage

Uploads go to the appdata volume by default, which is fine for one server. To use a bucket instead, add the storage variables to compose.override.yaml (values from the storage guide):

services:
  app:
    environment:
      STORAGE_DRIVER: s3
      S3_ENDPOINT: https://<ACCOUNT_ID>.r2.cloudflarestorage.com
      S3_REGION: auto
      S3_BUCKET: scheduler-uploads
      S3_FORCE_PATH_STYLE: "true"

Keep the two keys (S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY) in .env, not in the override file. Then run docker compose up -d.

Run background jobs separately (optional)

By default one container runs the web server and the background jobs. To split them, run a second container from the same image with ROLE=worker, and set ROLE=web on the first. Most installs don’t need this.

Useful commands

docker compose logs -f app                    # follow the app logs
docker compose up -d                          # apply changes to .env (restart alone doesn't reload it)
docker compose exec db psql -U scheduler      # open a SQL shell
docker compose down                           # stop (data volumes are kept)

Never run docker compose down -v unless you mean to delete the database and uploads: -v removes the volumes.

Updating

cd saas-clones
git pull
cd apps/scheduler
docker compose up -d --build

Back up first. See updates and backups.

Troubleshooting

  • Set AUTH_SECRET (openssl rand -base64 32) when running docker compose: AUTH_SECRET is missing from .env (or you’re not in the app’s folder).
  • Emails fail with an error about the host mailpit: SMTP_URL isn’t set, so the Compose default (the Mailpit test server) is used. Set SMTP_URL in .env and run docker compose up -d.
  • A change to .env has no effect: run docker compose up -d, not docker compose restart. Only up recreates the container with the new values.
  • Caddy can’t get a certificate: check that the DNS record points at this server and that ports 80 and 443 are reachable from the internet. docker compose logs caddy shows the reason.
  • !reset is rejected: update Docker Compose to 2.24.4 or later.
  • Sign-in fails: APP_URL in .env must match the address in your browser exactly.