feat(ci): seed previews from staging and read its event stream

Restores what #1455 built and #1557 dropped: a preview starts from a pg_dump of
staging's database and consumes staging's JetStream, so it is worth looking at
rather than an empty install.

The seed loader runs before the application server may boot. It cancels queued
work, disables every review trigger, and drops the instance identity, then
verifies that against the database and refuses to mark the preview seeded if the
policy did not take — a preview that cannot be silenced stays down. It holds the
Docker socket read-only because pg_dump and psql run inside the two database
containers; check-preview-stack.ts now refuses that mount on any other service,
and refuses it writable on this one.

The local broker is gone. The application server joins staging's shared-network
for its broker, with a durable named per deploy so previews never compete for one
consumer, and a 72h inactivity window because a preview is deleted rather than
shut down. staging-shared is external and named, which the sandbox check now
distinguishes from the project-scoped networks every preview would share.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017VKWqbmrPJFv8aKZBp36uD

Author: FelixTJDietrich

.changeset/previews-deploy-on-purpose.md

@@ -4,6 +4,6 @@
 
 Pull request previews are now self-service. Add the `preview` label to a pull request in this repository and it deploys; every commit after that redeploys on its own. A preview waits only for its images to be published, never for the test suite, so it exists even when the tests are red — and it runs the same artifacts staging and production run, so what you see is what ships. A comment on the pull request carries the preview link, and GitHub's native deployment link opens it too. Removing the label, closing the pull request, or converting it back to draft removes the stack. Up to three previews run at once by default, and when the host is full the pull request comment names the ones holding the slots.
 
-Preview stacks use their own database, message broker, credentials, and Docker networks, and reach neither the staging Docker socket, its data, nor any integration credential. Previews never run for forks, nor for changes to the deployment workflows themselves. Stacked pull requests each get their own preview.
+Each preview starts from a copy of staging's database, so workspaces and synced work are already there — and that copy is silenced before the app starts: review triggers, agent bindings and sweep schedules off, queued jobs cancelled, and the sign-in identity dropped so the preview issues its own tokens. It reads staging's event stream on a consumer of its own. Agent runs and inbound webhooks stay off. Previews never run for forks, nor for changes to the deployment workflows themselves. Stacked pull requests each get their own preview.
 
-**Operators:** follow the preview runbook before enabling the Coolify application. It requires a `preview` repository label, a preview-only Coolify application, two scoped Coolify secrets, and the repository variables listed there — including the optional `PREVIEW_MAX_ACTIVE` limit. Keep Coolify's automatic repository webhook disabled.
+**Operators:** follow the preview runbook before enabling the Coolify application. It requires a `preview` repository label, a preview-only Coolify application, two scoped Coolify secrets, and the repository variables listed there — including the optional `PREVIEW_MAX_ACTIVE` limit. Previews must be deployed onto the staging host: they seed from its database and read its event stream. Keep Coolify's automatic repository webhook disabled.

docker/preview/.env.example

@@ -26,6 +26,17 @@ HEPHAESTUS_AUTH_BOOTSTRAP_ADMINS=
 GH_OAUTH_CLIENT_ID=
 GH_OAUTH_CLIENT_SECRET=
 
+# Staging's broker, reached over its external `shared-network`. The application server consumes from
+# it with a durable named per deploy, so previews never compete for one consumer.
+NATS_SERVER=nats://nats-server:4222
+
+# The running staging PostgreSQL container. seed-loader takes one pg_dump from it on a preview's
+# first deploy, applies the preview policy, and refuses to mark the preview seeded if that policy
+# did not take — so a failure here leaves the preview un-booted rather than live on unsilenced data.
+PREVIEW_SEED_SOURCE_CONTAINER=app-postgres-1
+PREVIEW_SEED_SOURCE_USERNAME=root
+PREVIEW_SEED_SOURCE_DATABASE=hephaestus
+
 # Coolify supplies these values for each PR. Do not define them manually.
 # SOURCE_COMMIT=
 # COOLIFY_BRANCH=

docker/preview/README.md

@@ -25,17 +25,31 @@ hold, each enforced before Coolify is asked to deploy:
   attestation naming this repository's `reusable-docker-build.yml` as signer, checked before Coolify
   is asked to pull it. Nothing is built on the deployment host, so a preview cannot pass on a
   lookalike of the shipped image.
-- The stack has a fresh PostgreSQL database and private NATS server. It has no staging network,
-  staging database copy, staging encryption key, integration credentials, or Docker socket.
-- Agent execution, repository checkout, inbound webhooks, recurring sync, and external integrations
-  are disabled. The stack has normal outbound internet access, but no staging credential, Docker
-  network membership, or host control socket.
-
-The application server runs without Linux capabilities and with `no-new-privileges`. PostgreSQL and
-NATS data live in PR-specific volumes. The stack declares no networks of its own: Coolify runs every
-preview of this application under one Compose project named after the application UUID, so a network
-named here would be shared by all of them at once. Each preview gets Coolify's own per-preview
-network instead, which its proxy joins to reach the webapp and API.
+- The database is this preview's own, seeded from staging so it starts with real data. The clone is
+  taken with `pg_dump` — staging's data volume is never mounted — and the preview policy runs before
+  the application server is allowed to boot: every review trigger, agent binding and sweep schedule
+  is disabled, queued jobs are cancelled, pending deliveries are failed, and the instance identity
+  (`login_provider`, `jwt_signing_key`, `issued_jwt`) is dropped so the preview signs its own tokens.
+  The seed loader verifies that against the database and refuses to mark the preview seeded
+  otherwise, so a policy that silently did not apply leaves the preview un-booted rather than live.
+- The application server reads staging's JetStream, so a preview sees the events a shared GitHub App
+  delivers there. Its durable is named per deploy, so previews never compete for one consumer, and
+  it expires 72h after the preview stops reading — a preview is deleted, not shut down, so it never
+  removes its own.
+- Agent execution, repository checkout, inbound webhooks and recurring sync stay disabled, which is
+  what keeps a stack holding real data from acting on it.
+
+Two things follow from that, and both are deliberate rather than incidental. Only the seed loader
+holds the Docker socket, read-only, because `pg_dump` and `psql` run inside the two database
+containers; every service that runs pull-request code is refused it. And only the application server
+joins staging's network, to reach the broker. The database and the SPA stay on Coolify's per-preview
+network — the one it creates and attaches its proxy to. This file defines no network of its own:
+Coolify runs every preview of this application under one Compose project named after the application
+UUID, so a network defined here would be `<uuid>_backend` for all of them at once, private-looking
+and shared. `staging-shared` is joined by name, which makes it a decision rather than a side effect.
+
+The application server runs without Linux capabilities and with `no-new-privileges`. PostgreSQL
+keeps a PR-specific volume.
 
 Deployment authority is deliberately the same as push authority;
 [ADR 0035](../../docs/decisions/0035-pull-request-previews-are-label-gated.md) records why, and what
@@ -49,16 +63,16 @@ pull request's own copy of it defines that pull request's stack. Two rules hold
 works alone: the controller refuses to deploy a head that introduces changes anywhere under
 `docker/preview/` — compared against the default branch, so a stacked layer cannot inherit an edit
 from the layer below — and `ci-compose-validate.yml` renders the file on every pull request and fails if
-the stack gains a way out of its sandbox — a socket, a build stage, a published port, an external
-network, an unbounded memory limit, a network every preview would share, or a flipped integration
-switch.
+the stack gains a way out of its sandbox — a build stage, a published port, an unbounded memory
+limit, a network every preview would share, the Docker socket on anything but the seed loader or
+writable on that, or a flipped integration switch.
 `scripts/check-preview-stack.ts` is the authoritative list; this paragraph is not.
 
 ## Host capacity
 
-Each stack is capped at about 3 GiB (2 GiB application server, 512 MiB PostgreSQL, 256 MiB each for
-NATS and the webapp). Its CPU ceilings total 2.0 across the four services, so several previews
-oversubscribe a small host on paper. That is intended: a preview is idle almost all the time, and a
+Each stack is capped at about 2.8 GiB once running (2 GiB application server, 512 MiB PostgreSQL,
+256 MiB webapp); the seed loader adds 512 MiB while it runs and then exits. Its CPU ceilings total
+2.75 across the four services, so several previews oversubscribe a small host on paper. That is intended: a preview is idle almost all the time, and a
 ceiling stops one stack from taking the box rather than reserving capacity for it.
 
 `PREVIEW_MAX_ACTIVE` caps concurrent previews and defaults to 3. It has to leave roughly 3 GiB of
@@ -89,7 +103,12 @@ Create one Docker Compose application for `ls1intum/Hephaestus` on branch `main`
 5. Leave `SOURCE_COMMIT`, `COOLIFY_BRANCH`, and the `SERVICE_*` variables to Coolify. Define nothing
    on this application beyond `.env.example`; anything else does not belong here.
 6. Disable **Connect to predefined network**. Coolify attaches its proxy to each generated preview
-   network; the services do not need the shared `coolify` network.
+   network; the services do not need the shared `coolify` network. The one network this stack joins,
+   staging's `shared-network`, it names itself.
+7. The deployment host must be the one running staging, because the seed loader reaches staging's
+   Postgres through the host's Docker socket and the application server reaches its broker over
+   `shared-network`. Both are checked at deploy time: a missing seed source fails the preview
+   rather than starting it on an empty database.
 
 ## GitHub configuration