fix(ci): give each preview its own network and resolvable services

The first real preview deployment failed with UnknownHostException: postgres.
Coolify renames every compose service to `<service>-pr-<id>`, so the bare
service name resolves to nothing inside a preview; it publishes the renamed
hosts as SERVICE_NAME_*, which the appserver now uses for its database and
NATS URLs.

Diagnosing that surfaced a second defect. Coolify runs every preview of an
application under one Compose project, named after the application UUID with no
pull request in it, so the networks this file declared were `<uuid>_backend` and
`<uuid>_frontend` for all previews at once — two concurrent previews would have
shared them, and one could reach the other's database. Coolify's proxy was never
on those networks anyway; it joins the per-preview network it creates. The stack
now declares none, and check-preview-stack.ts fails if one comes back.

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

Author: FelixTJDietrich

.changeset/previews-reach-their-own-services.md

@@ -0,0 +1,6 @@
+---
+---
+
+This corrects the preview stack before pull request previews reach a release, so the behaviour
+described in the previews release note is the behaviour that ships. Nothing an operator has already
+deployed changes.

docker/preview/README.md

@@ -32,8 +32,10 @@ hold, each enforced before Coolify is asked to deploy:
   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. Coolify's proxy reaches the webapp and API on the frontend
-network; the database and NATS broker also use an internal backend network.
+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.
 
 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
@@ -48,7 +50,8 @@ works alone: the controller refuses to deploy a head that introduces changes any
 `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 non-internal backend, or a flipped integration switch.
+network, an unbounded memory limit, a network every preview would share, or a flipped integration
+switch.
 `scripts/check-preview-stack.ts` is the authoritative list; this paragraph is not.
 
 ## Host capacity

docker/preview/compose.app.yaml

@@ -13,6 +13,11 @@
 # would arrive with sync, notifications and the agent digest requirement switched on, and with the
 # Docker socket mounted — ADR 0035 option 6 has the rendered evidence. scripts/check-preview-stack.ts
 # fails when the reference gains a variable this file neither sets nor records as omitted.
+#
+# This file declares no networks. Coolify runs every preview of this application under one Compose
+# project — the project name is the application UUID, with no pull request in it — so a network named
+# here would be `<uuid>_backend`, shared by every preview at once. Coolify instead gives each preview
+# its own network and attaches its proxy to that, which is what keeps the stacks apart.
 
 services:
   postgres:
@@ -24,8 +29,6 @@ services:
       POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
     volumes:
       - postgres-data:/var/lib/postgresql/data
-    networks:
-      - backend
     security_opt:
       - no-new-privileges:true
     cap_drop:
@@ -61,8 +64,6 @@ services:
     command: ["--jetstream", "--store_dir=/data", "--http_port=8222"]
     volumes:
       - nats-data:/data
-    networks:
-      - backend
     security_opt:
       - no-new-privileges:true
     cap_drop:
@@ -110,11 +111,14 @@ services:
       HEPHAESTUS_TRUSTED_PROXIES: ${HEPHAESTUS_TRUSTED_PROXIES}
       APPLICATION_HOST_URL: https://${SERVICE_FQDN_WEBAPP}
       HEPHAESTUS_AUTH_API_BASE_PATH: ""
-      DATABASE_URL: postgresql://postgres:5432/hephaestus?sslmode=disable
+      # Coolify renames each service to `<service>-pr-<id>` and publishes the renamed hosts as
+      # SERVICE_NAME_*, so the bare service name resolves to nothing inside a preview. The defaults
+      # keep this file runnable on its own.
+      DATABASE_URL: postgresql://${SERVICE_NAME_POSTGRES:-postgres}:5432/hephaestus?sslmode=disable
       DATABASE_USERNAME: hephaestus
       DATABASE_PASSWORD: ${POSTGRES_PASSWORD}
-      NATS_SERVER: nats://nats:4222
-      HEPHAESTUS_SYNC_NATS_SERVER: nats://nats:4222
+      NATS_SERVER: nats://${SERVICE_NAME_NATS:-nats}:4222
+      HEPHAESTUS_SYNC_NATS_SERVER: nats://${SERVICE_NAME_NATS:-nats}:4222
       NATS_ENABLED: "true"
       NATS_DURABLE_CONSUMER_NAME: preview-consumer
       HEPHAESTUS_INTEGRATION_CONSUMER_INACTIVE_THRESHOLD: 24h
@@ -140,9 +144,6 @@ services:
       SENTRY_DSN: ""
       WEBHOOK_SECRET: ${WEBHOOK_SECRET}
       WEBHOOK_EXTERNAL_URL: ""
-    networks:
-      - frontend
-      - backend
     depends_on:
       postgres:
         condition: service_healthy
@@ -189,8 +190,6 @@ services:
       SENTRY_ENVIRONMENT: preview
       SENTRY_DSN: ""
       POSTHOG_ENABLED: "false"
-    networks:
-      - frontend
     depends_on:
       appserver:
         condition: service_healthy
@@ -216,11 +215,6 @@ services:
           memory: 256M
           pids: 128
 
-networks:
-  frontend:
-  backend:
-    internal: true
-
 volumes:
   postgres-data:
   nats-data:

docs/decisions/0035-pull-request-previews-are-label-gated.md

@@ -108,8 +108,8 @@ The gates that remain are the ones that describe *what may run*, not *who asked*
   this rule is load-bearing.
   `ci-compose-validate.yml` holds the other half: on every pull request it renders that file 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 non-internal backend, or a renamed or flipped integration
-  switch. `scripts/check-preview-stack.ts` is the authoritative list, and its own tests prove each
+  network, an unbounded memory limit, a network every preview would share, or a renamed or flipped
+  integration switch. `scripts/check-preview-stack.ts` is the authoritative list, and its own tests prove each
   assertion fails when that escape is present.
 - Every service runs the image CI published for the exact head commit, and each digest must carry a
   build attestation signed by this repository's `reusable-docker-build.yml`, verified before Coolify

scripts/check-preview-stack.test.ts

@@ -23,7 +23,7 @@ interface Service {
 
 interface Stack {
 	services: { appserver: Service; postgres: Service; webapp?: Service };
-	networks: { backend: { internal?: boolean } };
+	networks: Record<string, { internal?: boolean }>;
 }
 
 const sandboxed: Stack = {
@@ -47,7 +47,7 @@ const sandboxed: Stack = {
 			cap_add: ["CHOWN", "DAC_OVERRIDE", "FOWNER", "SETGID", "SETUID"],
 		},
 	},
-	networks: { backend: { internal: true } },
+	networks: {},
 };
 
 /** Clones the good stack, then lets a test break exactly one thing. */
@@ -107,11 +107,11 @@ void describe("preview stack sandbox", () => {
 				/no memory limit/,
 			],
 			[
-				"routable backend",
+				"a network every preview would share",
 				(s) => {
-					s.networks.backend.internal = false;
+					s.networks.backend = { internal: true };
 				},
-				/no longer internal/,
+				/every preview would share/,
 			],
 		];
 
@@ -194,7 +194,6 @@ void describe("preview stack sandbox", () => {
 		assert.deepEqual(findViolations({}), [
 			"the rendered stack declares no services",
 			"the rendered stack has no appserver service, so no switch was checked",
-			"the backend network is gone",
 		]);
 	});
 });

scripts/check-preview-stack.ts

@@ -226,10 +226,15 @@ export function findViolations(stack: unknown): string[] {
 	if (!services.some(([name]) => name === "appserver")) {
 		violations.push("the rendered stack has no appserver service, so no switch was checked");
 	}
-	const backend = records(stack.networks).find(([name]) => name === "backend");
-	if (!backend) violations.push("the backend network is gone");
-	else if (backend[1].internal !== true)
-		violations.push("the backend network is no longer internal");
+	// Coolify runs every preview of this application under one Compose project, named after the
+	// application UUID with no pull request in it. A network named here is therefore `<uuid>_<name>`
+	// for all of them at once, and one preview reaches another's database over it. Coolify's own
+	// per-preview network, which its proxy joins, is what keeps them apart. `default` is Compose's
+	// own and carries the project name too, but nothing joins it once no service names a network.
+	for (const [name] of records(stack.networks)) {
+		if (name === "default") continue;
+		violations.push(`the stack declares the ${name} network, which every preview would share`);
+	}
 
 	return violations;
 }