# Deploying knotless-serve

One Docker host, a reverse proxy in front of it for TLS, and a domain.

| | |
| --- | --- |
| `../Dockerfile` | one image, `knotless:current`: knotless-serve, git, and the built pages |
| `docker-compose.yml` | `/etc/knotless/docker-compose.yml`: `serve` (knotless-serve, on :2590) and `pages` (the SvelteKit app, on :2591) |
| `deploy.sh` | builds the image on the host over SSH, writes the compose file and its `.env`, and restarts what changed |
| `*.tf` | the domain's DNS records at Cloudflare, pointing at the host |

```sh
just deploy root@host git.example.com   # build on the host and restart; or put both in deploy/local.env
cd deploy && terraform apply            # DNS, once (terraform.tfvars from the .example)
```

The proxy joins the `knotless` docker network (`KNOTLESS_PROXY_NETWORK`)
and sends the domain to `knotless-serve:2590`, passing `X-Forwarded-Proto`.
With Caddy:

```caddy
git.example.com {
	reverse_proxy knotless-serve:2590
}
```

knotless-serve is the appview (`dev.knotless.listRepos`, `getForge`,
`getFeed`, indexed from Jetstream), the gateway, as `did:web:<domain>`, and
the moderation service. Its state is in `KNOTLESS_DATA`
(`/var/lib/knotless`):

- `index.db`, the index: a cache, rebuildable with `--backfill`.
- `cache/`, mirrors and identities: a cache.
- `config/`, the gateway's OAuth client key and the sessions owners
  delegated to it. Losing it breaks every delegation, which owners then
  have to make again: back it up.

`/etc/knotless/secrets.env` holds `KNOTLESS_ADMIN_PASSWORD`, made on the
first deploy, for `knotless admin`.

Keep the records DNS-only: PDSes fetch the gateway's DID document and OAuth
client metadata from the origin, and the proxy holds the certificate.