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). gitandopenssl.- 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_URLis 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_URLandEMAIL_FROMcome from your email provider. See the email guide. SetSMTP_URLbefore going live: the Compose file falls back to themailpittest server, which only runs with thedevprofile, so withoutSMTP_URLevery email fails.- Add any other optional variables from the app page (Scheduler or Invoicing), such as
GOOGLE_CLIENT_IDorSTRIPE_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 runningdocker compose:AUTH_SECRETis missing from.env(or you’re not in the app’s folder).- Emails fail with an error about the host
mailpit:SMTP_URLisn’t set, so the Compose default (the Mailpit test server) is used. SetSMTP_URLin.envand rundocker compose up -d. - A change to
.envhas no effect: rundocker compose up -d, notdocker compose restart. Onlyuprecreates 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 caddyshows the reason. !resetis rejected: update Docker Compose to 2.24.4 or later.- Sign-in fails:
APP_URLin.envmust match the address in your browser exactly.