# Docker Compose

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

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](https://docs.docker.com/engine/install/) 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

```sh
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

```sh
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:

```sh
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](./email.md). 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](./scheduler.md#environment-variables) or [Invoicing](./invoicing.md#environment-variables)), 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](#use-s3-storage).

### 4. Add HTTPS with Caddy

[Caddy](https://caddyserver.com/) 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`:

```text
cal.example.com {
	reverse_proxy app:3000
}
```

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

```yaml
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

```sh
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

```sh
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](./first-admin.md).

## 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](./storage.md)):

```yaml
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

```sh
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

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

Back up first. See [updates and backups](./updates-backups.md#back-up-the-database).

## 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.