Warp/Docker/README.md

# Docker: one container per component

The homeserver (`warp`), the admin panel (`warp-admin`) and the web client
(`warp-web`) as separate images, built from `Dockerfile`,
`apps/admin/Dockerfile` and `apps/web/Dockerfile`.

| File | Database | Images |
| --- | --- | --- |
| `docker-compose.sqlite.yml` | SQLite, in the `warp-data` volume | built here |
| `docker-compose.pocketbase.yml` | PocketBase, embedded in the homeserver, in `warp-data` | built here |
| `docker-compose.postgresql.yml` | PostgreSQL 17, its own container | built here |
| `docker-compose.pocketbase.s3.yml` | PocketBase, media in an existing S3 bucket elsewhere | built here |
| `docker-compose.pocketbase.seaweedfs.yml` | PocketBase, media in SeaweedFS, one container | built here |
| `docker-compose.pocketbase.seaweedfs.split.yml` | PocketBase, media in SeaweedFS, one container per role, with its admin UI | built here |
| `docker-compose.*.prod.yml` | as above | pulled, never built |

```sh
cd Docker
cp .env.sqlite.example .env      # then edit it
docker compose -f docker-compose.sqlite.yml up -d --build
docker compose -f docker-compose.sqlite.yml exec warp warp create-account --username admin --admin
```

Homeserver on `:8008`, admin panel on `:8009`, web client on `:8080`
(`WARP_PORT`, `WARP_ADMIN_PORT`, `WARP_WEB_PORT` in `.env` move them). Put a
TLS-terminating reverse proxy in front before exposing them; see
[docs/deployment.md](../docs/deployment.md).

PocketBase is a database driver inside the homeserver, not a separate
server, so the PocketBase files have no PocketBase container.

## Media in S3

The three `pocketbase.s3` and `pocketbase.seaweedfs` setups keep the
PocketBase database in `/data/pb_data` and put media in an S3 bucket
(`WARP_PB_S3_BUCKET`, default `warp`). Media already stored on the
filesystem is not moved into the bucket when S3 is turned on, so start
these on a fresh `warp-data` or copy the files across first.

- **`docker-compose.pocketbase.s3.yml`**: a bucket that already exists
  elsewhere (AWS, MinIO, a SeaweedFS on another host). Set
  `WARP_PB_S3_ENDPOINT`, `WARP_PB_S3_ACCESS_KEY` and `WARP_PB_S3_SECRET`.
  Path style is on by default; set `WARP_PB_S3_FORCE_PATH_STYLE=false` for
  AWS S3. `http://host.docker.internal:8333` reaches a gateway on the
  Docker host. The homeserver waits up to 30 seconds for the endpoint to
  answer before it starts.
- **`docker-compose.pocketbase.seaweedfs.yml`**: SeaweedFS as one
  `weed server -s3` container, plus a one-shot `seaweedfs-init` that
  creates the bucket. The gateway's one identity is the homeserver's key
  pair, `WARP_PB_S3_ACCESS_KEY` and `WARP_PB_S3_SECRET`.
- **`docker-compose.pocketbase.seaweedfs.split.yml`**: master, volume,
  filer, S3 gateway and admin UI (port 23646) as separate containers.
  `seaweedfs-init` writes the homeserver's identity into the filer's IAM
  store on every start, the store the admin UI writes too, so keys added
  under *Object Store → Users* never displace it; the gateway does not
  start until that identity is there. Set `SEAWEED_ADMIN_PASSWORD` as well.

The S3 gateway and the admin UI are published on 127.0.0.1 only
(`SEAWEED_S3_BIND`, `SEAWEED_ADMIN_BIND`); master, volume and filer are not
published, since the volume server serves content by id with no
authentication. Both SeaweedFS files share a project and the
`seaweed-data` layout, so switching between them needs no migration.
`SEAWEED_IMAGE` pins the SeaweedFS release (4.45).

## Prod files

The `.prod.yml` files pull `$WARP_REGISTRY/warp`, `warp-admin` and
`warp-web` at tag `$WARP_VERSION` (defaults `ghcr.io/dariuszjaniak` and
`latest`). Push the images there first:

```sh
docker compose -f docker-compose.sqlite.yml build
for i in warp warp-admin warp-web; do
  docker tag $i:latest $WARP_REGISTRY/$i:$WARP_VERSION
  docker push $WARP_REGISTRY/$i:$WARP_VERSION
done
```

`docker-compose.postgresql.prod.yml` refuses to start without
`WARP_POSTGRES_PASSWORD`.

## Settings

Every compose file has its own settings file, named after it:
`docker-compose.<name>.yml` takes `.env.<name>.example`, so
`docker-compose.pocketbase.seaweedfs.prod.yml` takes
`.env.pocketbase.seaweedfs.prod.example`. Each lists only the settings
its compose file uses, with their defaults, and names the ones that are
required; an empty value means the default. Copy the one you need to
`.env`, which compose reads for the ports, the registry and the passwords,
and passes to the homeserver, the admin panel and the web client. `.env`
is not committed. The prod examples start from a public server name
rather than `localhost`.

The compose files set only what makes each one what it is: the database
driver and connection string, and the address the admin panel and web
client reach the homeserver on.