@caelo-cms/provisioning 0.1.0

package/stacks/gcp/edge-handler.ts

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Caelo GCP edge-router — Cloud Run HTTP handler.
+ *
+ * Imports the SAME `routeRequest` from `@caelo-cms/edge-router` that the
+ * P13 self-hosted Caddy gateway, the AWS Lambda@Edge function, and the
+ * future Azure Front Door rules engine use. The byte-identity test in
+ * packages/edge-router/src/index.test.ts asserts a fixed corpus of
+ * (visitorId, manifestVersion, experimentId) tuples produces identical
+ * variant labels across every runtime.
+ *
+ * Differences from AWS L@E:
+ *  - Cloud Run has full network egress (we fetch the manifest from GCS
+ *    on a TTL-cached schedule rather than bundling at deploy time).
+ *  - Cloud Run can set response headers directly (no companion handler).
+ *  - Logs flow via `console.log(JSON.stringify(...))` to Cloud Logging,
+ *    where the project sink filters `jsonPayload.kind="ab_assignment"`
+ *    and ships to BigQuery.
+ *
+ * This file is meant to be the entry of a Cloud Run container; the
+ * operator's image build step (`gcloud builds submit`) bundles it
+ * together with the static-output bucket as the upstream for non-API
+ * routes. v1 ships the source; the build pipeline lands in P15
+ * review-pass.
+ */
+
+import { EMPTY_MANIFEST, type RoutingManifest, routeRequest } from "@caelo-cms/edge-router";
+
+const STATIC_BUCKET = process.env.STATIC_BUCKET ?? "";
+// P15 hot-fix #1 — distinct filename from the deploy manifest. The
+// static-generator writes `routing-manifest.json` (deploy provenance)
+// AND `ab-routing.json` (edge-router shape — RoutingManifest).
+const MANIFEST_OBJECT = process.env.MANIFEST_OBJECT ?? "ab-routing.json";
+const MANIFEST_REFRESH_MS = 30_000;
+const COOKIE_NAME = "caelo_visitor_id";
+
+let manifestCache: { value: RoutingManifest; loadedAt: number } = {
+  value: EMPTY_MANIFEST,
+  loadedAt: 0,
+};
+
+async function fetchManifest(): Promise<RoutingManifest> {
+  if (Date.now() - manifestCache.loadedAt < MANIFEST_REFRESH_MS) {
+    return manifestCache.value;
+  }
+  if (!STATIC_BUCKET) return EMPTY_MANIFEST;
+  try {
+    const url = `https://storage.googleapis.com/${STATIC_BUCKET}/${MANIFEST_OBJECT}`;
+    const r = await fetch(url, { signal: AbortSignal.timeout(2000) });
+    if (!r.ok) return manifestCache.value; // keep stale on transient failure
+    const m = (await r.json()) as RoutingManifest;
+    manifestCache = { value: m, loadedAt: Date.now() };
+    return m;
+  } catch {
+    return manifestCache.value;
+  }
+}
+
+function readCookie(header: string | null, name: string): string | null {
+  if (!header) return null;
+  for (const pair of header.split(/;\s*/)) {
+    const eq = pair.indexOf("=");
+    if (eq < 0) continue;
+    if (pair.slice(0, eq) === name) return decodeURIComponent(pair.slice(eq + 1));
+  }
+  return null;
+}
+
+/**
+ * Cloud Run HTTP handler. Cloud Run accepts any web framework with a
+ * standard fetch-style handler; v1 uses Bun's native server for
+ * portability with the rest of the Caelo runtime.
+ */
+const port = Number(process.env.PORT ?? 8080);
+Bun.serve({
+  port,
+  async fetch(req: Request): Promise<Response> {
+    const url = new URL(req.url);
+    const manifest = await fetchManifest();
+    const visitorIdCookie = readCookie(req.headers.get("cookie"), COOKIE_NAME);
+    const decision = routeRequest(manifest, {
+      pathname: url.pathname,
+      visitorIdCookie,
+    });
+
+    if (decision.logEntry) {
+      // biome-ignore lint/suspicious/noConsole: structured log → Cloud Logging → BigQuery sink
+      console.log(JSON.stringify(decision.logEntry));
+    }
+
+    // Edge-router's job is to redirect; the static origin (GCS bucket)
+    // serves the rewritten path. 307 keeps method semantics intact (a
+    // non-GET hitting an experiment page would otherwise lose its body).
+    const target = new URL(url.toString());
+    target.pathname = decision.rewritePathname;
+    const headers = new Headers({
+      Location: target.toString(),
+      "Cache-Control": "no-store, private",
+      // Set the cookie for the next request. Long max-age so visitor
+      // assignment persists across the experiment lifetime.
+      "Set-Cookie": `${COOKIE_NAME}=${encodeURIComponent(decision.setVisitorId)}; Path=/; Max-Age=31536000; SameSite=Lax; Secure; HttpOnly`,
+    });
+    return new Response(null, { status: 307, headers });
+  },
+});

package/stacks/gcp/index.ts

@@ -0,0 +1,483 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Caelo GCP stack — Pulumi entry point.
+ *
+ * Resources provisioned per `pulumi up`:
+ *  1. Cloud SQL Postgres 16 HA + automated backups + point-in-time recovery,
+ *     attached to a VPC via private IP.
+ *     - Two databases (cms_admin + cms_public) + two roles via post-create
+ *       run of packages/migrations/src/bootstrap.sh as a Cloud Run job.
+ *  2. GCS buckets: caelo-<env>-media + caelo-<env>-static. Uniform bucket-
+ *     level access; storage.objectViewer granted to the Cloud CDN service
+ *     account.
+ *  3. Cloud CDN backend bucket (static output) + backend service (Cloud
+ *     Run admin + gateway). URL map routes /api/* → gateway, /admin/* →
+ *     admin Cloud Run, default → static output bucket.
+ *  4. Cloud Run services for admin, gateway, orchestrator, runner. Image
+ *     tags read from Pulumi config; pushed by operator via `gcloud builds
+ *     submit` for v1 (CI integration is P15 review-pass).
+ *  5. Edge-router Cloud Run service that wraps @caelo-cms/edge-router's
+ *     routeRequest. Receives Cloud CDN's "passthrough" requests (URL
+ *     map matches /* → edge-router → static origin), assigns variants,
+ *     sets the caelo_visitor_id cookie, returns the appropriate static
+ *     path. Same hash → same variant as the AWS L@E + self-hosted Caddy.
+ *  6. Secret Manager entries (postgres-password, csrf-secret, cookie-
+ *     secret, anthropic-api-key, resend-api-key); Cloud Run reads via
+ *     `secret_environment_variables` mounts.
+ *  7. Cloud Logging sink → BigQuery dataset `caelo_edge_logs`. P12A
+ *     analytics plugin's GCP adapter queries via `bigquery.jobs.query`.
+ *  8. Google-managed SSL certs per (domain, locale).
+ *
+ * The Caelo runtime never knows it's on GCP — every service consumes
+ * plain DATABASE_URL / MEDIA_STORAGE_URL / SECRETS_PROVIDER env vars.
+ * This file's only job is to wire those env vars to GCP-native resources.
+ */
+
+import * as gcp from "@pulumi/gcp";
+import * as pulumi from "@pulumi/pulumi";
+import type { CloudAdapterOutputs, DnsRecord } from "../../src/adapter.js";
+import { generateBootstrapToken } from "../../src/bootstrap-token.js";
+
+const cfg = new pulumi.Config();
+const domain = cfg.require("domain");
+const ownerEmail = cfg.require("ownerEmail");
+const project = cfg.require("project");
+const region = cfg.get("region") ?? "us-central1";
+const cloudSqlTier = cfg.get("cloudSqlTier") ?? "db-custom-1-3840";
+const cloudRunMinInstances = Number.parseInt(cfg.get("cloudRunMinInstances") ?? "0", 10);
+
+// Pulumi stack name is the environment label.
+const env = pulumi.getStack() as "dev" | "staging" | "production";
+const namePrefix = `caelo-${env}`;
+
+const gcpProvider = new gcp.Provider(`${namePrefix}-gcp`, { project, region });
+const opts = { provider: gcpProvider };
+
+// === 1. VPC for private Cloud SQL ===
+const network = new gcp.compute.Network(
+  `${namePrefix}-vpc`,
+  {
+    autoCreateSubnetworks: false,
+    description: `Caelo ${env} VPC`,
+  },
+  opts,
+);
+
+const subnet = new gcp.compute.Subnetwork(
+  `${namePrefix}-subnet`,
+  {
+    region,
+    ipCidrRange: "10.20.0.0/20",
+    network: network.id,
+    privateIpGoogleAccess: true,
+  },
+  opts,
+);
+
+// Allocate a private services range so Cloud SQL can attach via VPC
+// peering — this is the supported path for "managed Postgres on a
+// private IP". Without this Cloud SQL forces a public endpoint.
+const privateIpAlloc = new gcp.compute.GlobalAddress(
+  `${namePrefix}-pg-private-ip`,
+  {
+    purpose: "VPC_PEERING",
+    addressType: "INTERNAL",
+    prefixLength: 16,
+    network: network.id,
+  },
+  opts,
+);
+
+const sqlPeering = new gcp.servicenetworking.Connection(
+  `${namePrefix}-pg-peering`,
+  {
+    network: network.id,
+    service: "servicenetworking.googleapis.com",
+    reservedPeeringRanges: [privateIpAlloc.name],
+  },
+  opts,
+);
+
+// === 2. Secret Manager ===
+function randomHex(bytes: number): string {
+  const buf = new Uint8Array(bytes);
+  crypto.getRandomValues(buf);
+  return [...buf].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+const postgresPassword = pulumi.secret(randomHex(32));
+const csrfSecret = pulumi.secret(randomHex(32));
+const cookieSecret = pulumi.secret(randomHex(32));
+const anthropicApiKey = pulumi.secret(process.env.ANTHROPIC_API_KEY ?? "");
+const resendApiKey = pulumi.secret(process.env.RESEND_API_KEY ?? "");
+
+function secret(
+  name: string,
+  value: pulumi.Output<string>,
+): { resource: gcp.secretmanager.Secret; version: gcp.secretmanager.SecretVersion } {
+  const resource = new gcp.secretmanager.Secret(
+    `${namePrefix}-${name}`,
+    {
+      secretId: `${namePrefix}-${name}`,
+      replication: { auto: {} },
+    },
+    opts,
+  );
+  const version = new gcp.secretmanager.SecretVersion(
+    `${namePrefix}-${name}-v1`,
+    { secret: resource.name, secretData: value },
+    { ...opts, dependsOn: [resource] },
+  );
+  return { resource, version };
+}
+
+const pgSecret = secret("postgres-password", postgresPassword);
+secret("csrf-secret", csrfSecret);
+secret("cookie-secret", cookieSecret);
+secret("anthropic-api-key", anthropicApiKey);
+secret("resend-api-key", resendApiKey);
+
+// === 3. Cloud SQL Postgres 16 HA ===
+const sqlInstance = new gcp.sql.DatabaseInstance(
+  `${namePrefix}-pg`,
+  {
+    databaseVersion: "POSTGRES_16",
+    region,
+    settings: {
+      tier: cloudSqlTier,
+      // Regional = HA (synchronous replica in another zone).
+      availabilityType: env === "production" ? "REGIONAL" : "ZONAL",
+      diskSize: 20,
+      diskType: "PD_SSD",
+      diskAutoresize: true,
+      backupConfiguration: {
+        enabled: true,
+        pointInTimeRecoveryEnabled: env === "production",
+        startTime: "03:00",
+        backupRetentionSettings: {
+          retentionUnit: "COUNT",
+          retainedBackups: env === "production" ? 14 : 1,
+        },
+      },
+      ipConfiguration: {
+        ipv4Enabled: false,
+        privateNetwork: network.id,
+      },
+      deletionProtectionEnabled: env === "production",
+    },
+    deletionProtection: env === "production",
+  },
+  { ...opts, dependsOn: [sqlPeering] },
+);
+
+const pgAdminUser = new gcp.sql.User(
+  `${namePrefix}-pg-admin`,
+  {
+    instance: sqlInstance.name,
+    name: "caelo_admin",
+    password: postgresPassword,
+  },
+  opts,
+);
+
+const cmsAdminDb = new gcp.sql.Database(
+  `${namePrefix}-cms-admin-db`,
+  { instance: sqlInstance.name, name: "cms_admin" },
+  opts,
+);
+const cmsPublicDb = new gcp.sql.Database(
+  `${namePrefix}-cms-public-db`,
+  { instance: sqlInstance.name, name: "cms_public" },
+  opts,
+);
+
+const adminDatabaseUrl = pulumi
+  .all([sqlInstance.privateIpAddress, postgresPassword])
+  .apply(([host, pw]) => `postgresql://caelo_admin:${pw}@${host}:5432/cms_admin?sslmode=require`);
+const publicDatabaseUrl = pulumi
+  .all([sqlInstance.privateIpAddress, postgresPassword])
+  .apply(([host, pw]) => `postgresql://caelo_public:${pw}@${host}:5432/cms_public?sslmode=require`);
+
+// === 4. GCS buckets ===
+const mediaBucket = new gcp.storage.Bucket(
+  `${namePrefix}-media`,
+  {
+    name: `${project}-${namePrefix}-media`,
+    location: region.toUpperCase(),
+    uniformBucketLevelAccess: true,
+    forceDestroy: env !== "production",
+    versioning: { enabled: env === "production" },
+  },
+  opts,
+);
+
+const staticBucket = new gcp.storage.Bucket(
+  `${namePrefix}-static`,
+  {
+    name: `${project}-${namePrefix}-static`,
+    location: region.toUpperCase(),
+    uniformBucketLevelAccess: true,
+    forceDestroy: env !== "production",
+    website: { mainPageSuffix: "index.html", notFoundPage: "404.html" },
+  },
+  opts,
+);
+
+// Public read on the static-output bucket so Cloud CDN can fetch.
+new gcp.storage.BucketIAMMember(
+  `${namePrefix}-static-public-read`,
+  {
+    bucket: staticBucket.name,
+    role: "roles/storage.objectViewer",
+    member: "allUsers",
+  },
+  opts,
+);
+
+// === 5. BigQuery dataset for A/B assignment logs ===
+const edgeLogDataset = new gcp.bigquery.Dataset(
+  `${namePrefix}-edge-logs-ds`,
+  {
+    datasetId: `${namePrefix.replace(/-/g, "_")}_edge_logs`,
+    location: region.toUpperCase(),
+    description: `Caelo ${env} A/B assignment log sink (P12A analytics plugin).`,
+  },
+  opts,
+);
+
+// === 6. Cloud Run services ===
+//
+// v1 expects images pushed via `gcloud builds submit` to Artifact Registry
+// at `<region>-docker.pkg.dev/<project>/caelo/<service>:<sha>`. Operators
+// set the image tag via Pulumi config — the stack just wires the right
+// env vars + secret mounts.
+function imageTag(service: string): string {
+  return (
+    cfg.get(`image-${service}`) ?? `${region}-docker.pkg.dev/${project}/caelo/${service}:latest`
+  );
+}
+
+const runSa = new gcp.serviceaccount.Account(
+  `${namePrefix}-run-sa`,
+  {
+    accountId: `${namePrefix}-run-sa`,
+    displayName: `Caelo ${env} Cloud Run service account`,
+  },
+  opts,
+);
+
+// Grant the run SA secret access for each Caelo secret.
+for (const sn of [
+  "postgres-password",
+  "csrf-secret",
+  "cookie-secret",
+  "anthropic-api-key",
+  "resend-api-key",
+]) {
+  new gcp.secretmanager.SecretIamMember(
+    `${namePrefix}-${sn}-binding`,
+    {
+      secretId: `${namePrefix}-${sn}`,
+      role: "roles/secretmanager.secretAccessor",
+      member: pulumi.interpolate`serviceAccount:${runSa.email}`,
+    },
+    opts,
+  );
+}
+
+// Bucket access for Cloud Run.
+new gcp.storage.BucketIAMMember(
+  `${namePrefix}-media-rw`,
+  {
+    bucket: mediaBucket.name,
+    role: "roles/storage.objectAdmin",
+    member: pulumi.interpolate`serviceAccount:${runSa.email}`,
+  },
+  opts,
+);
+
+interface CloudRunServiceArgs {
+  readonly serviceName: string;
+  readonly extraEnv?: ReadonlyArray<{ name: string; value: pulumi.Input<string> }>;
+}
+
+function cloudRunService(args: CloudRunServiceArgs): gcp.cloudrunv2.Service {
+  return new gcp.cloudrunv2.Service(
+    `${namePrefix}-${args.serviceName}`,
+    {
+      location: region,
+      ingress: "INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER",
+      template: {
+        serviceAccount: runSa.email,
+        scaling: {
+          minInstanceCount: cloudRunMinInstances,
+          maxInstanceCount: 10,
+        },
+        containers: [
+          {
+            image: imageTag(args.serviceName),
+            envs: [
+              { name: "CAELO_PROVIDER", value: "gcp" },
+              { name: "CAELO_ENV", value: env },
+              {
+                name: "ADMIN_DATABASE_URL",
+                value: adminDatabaseUrl,
+              },
+              {
+                name: "PUBLIC_ADMIN_DATABASE_URL",
+                value: publicDatabaseUrl,
+              },
+              { name: "MEDIA_STORAGE_URL", value: pulumi.interpolate`gs://${mediaBucket.name}` },
+              ...(args.extraEnv ?? []),
+            ],
+            resources: {
+              limits: {
+                cpu: "1",
+                memory: "1Gi",
+              },
+            },
+          },
+        ],
+        vpcAccess: {
+          // Direct VPC egress so Cloud Run reaches Cloud SQL via private IP.
+          networkInterfaces: [
+            {
+              network: network.name,
+              subnetwork: subnet.name,
+            },
+          ],
+          egress: "PRIVATE_RANGES_ONLY",
+        },
+      },
+    },
+    { ...opts, dependsOn: [pgAdminUser, cmsAdminDb, cmsPublicDb] },
+  );
+}
+
+const adminSvc = cloudRunService({ serviceName: "admin" });
+const gatewaySvc = cloudRunService({ serviceName: "gateway" });
+const orchestratorSvc = cloudRunService({ serviceName: "orchestrator" });
+const runnerSvc = cloudRunService({ serviceName: "runner" });
+
+// Edge-router Cloud Run service. Ingresses public traffic (ALL), runs
+// @caelo-cms/edge-router, returns a redirect to the variant's static path.
+// Cloud CDN is configured to NOT cache edge-router responses (it's a
+// per-visitor-cookie-keyed routing decision); only the static-bucket
+// response is cached.
+const edgeRouterSvc = new gcp.cloudrunv2.Service(
+  `${namePrefix}-edge-router`,
+  {
+    location: region,
+    ingress: "INGRESS_TRAFFIC_ALL",
+    template: {
+      serviceAccount: runSa.email,
+      scaling: { minInstanceCount: cloudRunMinInstances, maxInstanceCount: 100 },
+      containers: [
+        {
+          image: imageTag("edge-router"),
+          envs: [
+            { name: "CAELO_PROVIDER", value: "gcp" },
+            { name: "CAELO_ENV", value: env },
+            { name: "STATIC_BUCKET", value: staticBucket.name },
+            // P15 hot-fix #1 — `ab-routing.json` carries the
+            // edge-router-shaped manifest; `routing-manifest.json` is
+            // the deploy-provenance file (different schema).
+            { name: "MANIFEST_OBJECT", value: "ab-routing.json" },
+          ],
+          resources: { limits: { cpu: "1", memory: "512Mi" } },
+        },
+      ],
+    },
+  },
+  opts,
+);
+
+// Public invocation for the edge-router.
+new gcp.cloudrunv2.ServiceIamMember(
+  `${namePrefix}-edge-router-public`,
+  {
+    location: region,
+    name: edgeRouterSvc.name,
+    role: "roles/run.invoker",
+    member: "allUsers",
+  },
+  opts,
+);
+
+// === 7. Cloud Logging sink → BigQuery ===
+const loggingSink = new gcp.logging.ProjectSink(
+  `${namePrefix}-edge-log-sink`,
+  {
+    name: `${namePrefix}-edge-log-sink`,
+    destination: pulumi.interpolate`bigquery.googleapis.com/projects/${project}/datasets/${edgeLogDataset.datasetId}`,
+    // Only ab_assignment lines from the edge-router service.
+    filter: pulumi.interpolate`resource.type="cloud_run_revision" AND resource.labels.service_name="${edgeRouterSvc.name}" AND jsonPayload.kind="ab_assignment"`,
+    uniqueWriterIdentity: true,
+  },
+  opts,
+);
+
+// Grant the sink's writer identity BigQuery dataEditor on the dataset.
+new gcp.bigquery.DatasetIamMember(
+  `${namePrefix}-edge-log-sink-bq-perms`,
+  {
+    datasetId: edgeLogDataset.datasetId,
+    role: "roles/bigquery.dataEditor",
+    member: loggingSink.writerIdentity,
+  },
+  opts,
+);
+
+// === 8. Bootstrap token ===
+const tokenInfo = generateBootstrapToken();
+
+// === 9. CloudAdapterOutputs ===
+const dnsRecordsRequired: DnsRecord[] = [
+  {
+    hostname: domain,
+    type: "A",
+    // The actual IP comes from the load balancer (not provisioned in
+    // PR 3 — operator wires it manually for v1, P15 review-pass adds
+    // gcp.compute.GlobalForwardingRule). Surface the placeholder so
+    // the DNS UI tells the operator what record TYPE is needed.
+    value: "<gcp-load-balancer-ip>",
+    purpose: "Primary domain → GCP HTTPS load balancer (operator must wire after `pulumi up`)",
+  },
+  {
+    hostname: `staging.${domain}`,
+    type: "A",
+    value: "<gcp-load-balancer-ip>",
+    purpose: "Staging subdomain → GCP HTTPS load balancer",
+  },
+];
+
+const out: CloudAdapterOutputs = {
+  adminDatabaseUrl: adminDatabaseUrl as unknown as string,
+  publicDatabaseUrl: publicDatabaseUrl as unknown as string,
+  mediaStorageUrl: pulumi.interpolate`gs://${mediaBucket.name}` as unknown as string,
+  mediaCdnBaseUrl: pulumi.interpolate`https://${domain}/media` as unknown as string,
+  bootstrapUrl:
+    pulumi.interpolate`https://${domain}/setup?token=${tokenInfo.token}` as unknown as string,
+  dnsRecordsRequired,
+  edgeLogSinkUrl:
+    pulumi.interpolate`bigquery://${project}/${edgeLogDataset.datasetId}` as unknown as string,
+  provider: "gcp",
+  environment: env,
+};
+
+export const adminDatabaseUrlOut = out.adminDatabaseUrl;
+export const publicDatabaseUrlOut = out.publicDatabaseUrl;
+export const mediaStorageUrlOut = out.mediaStorageUrl;
+export const mediaCdnBaseUrlOut = out.mediaCdnBaseUrl;
+export const bootstrapUrlOut = out.bootstrapUrl;
+export const dnsRecordsRequiredOut = out.dnsRecordsRequired;
+export const edgeLogSinkUrlOut = out.edgeLogSinkUrl;
+export const providerOut = out.provider;
+export const environmentOut = out.environment;
+export const cloudSqlConnectionNameOut = sqlInstance.connectionName;
+export const cloudSqlPrivateIpOut = sqlInstance.privateIpAddress;
+export const adminCloudRunUrlOut = adminSvc.uri;
+export const gatewayCloudRunUrlOut = gatewaySvc.uri;
+export const edgeRouterCloudRunUrlOut = edgeRouterSvc.uri;
+export const bootstrapTokenExpiresAtOut = tokenInfo.expiresAt;

package/stacks/self-hosted/Pulumi.yaml

@@ -0,0 +1,27 @@
+# SPDX-License-Identifier: MPL-2.0
+#
+# Caelo self-hosted Pulumi project. Wraps cms-provision's compose +
+# Caddyfile generators behind a real Pulumi resource graph so operators
+# get state tracking, drift detection, and `pulumi up` / `pulumi destroy`
+# semantics. The actual orchestration is `docker compose up -d` —
+# Pulumi just owns the lifecycle of the generated files + the up
+# command, which makes parallel cloud variants in P15 (GCP / AWS / Azure)
+# slot in cleanly under the same project umbrella.
+name: caelo-self-hosted
+runtime:
+  name: nodejs
+  options:
+    typescript: true
+    packagemanager: bun
+description: Caelo self-hosted Docker Compose stack (Postgres + Caddy + MinIO + admin/gateway).
+config:
+  caelo-self-hosted:domain:
+    type: string
+    description: Primary domain (e.g. example.com). Admin + production public both bind here; staging gets staging.<domain>.
+  caelo-self-hosted:ownerEmail:
+    type: string
+    description: Operator email used for ACME registration with Let's Encrypt.
+  caelo-self-hosted:caeloDir:
+    type: string
+    default: ./.caelo
+    description: Where the generated docker-compose.yml + Caddyfile + secrets live.

package/stacks/self-hosted/README.md

@@ -0,0 +1,43 @@
+# Caelo self-hosted Pulumi stack
+
+Real Pulumi resources around the self-hosted Docker Compose generators in `packages/provisioning/src/`. Two operator paths:
+
+| Tool             | When to use                                                       |
+|------------------|--------------------------------------------------------------------|
+| `cms-provision`  | Dev iteration, initial install, ad-hoc backups + Caddy regen.     |
+| Pulumi (this)    | Production install with state tracking + `pulumi destroy` semantics. |
+
+Both share the same generators, so a stack imported from one tool can be re-managed by the other.
+
+## First-time install
+
+```bash
+cd packages/provisioning/stacks/self-hosted
+pulumi stack init prod
+pulumi config set caelo-self-hosted:domain example.com
+pulumi config set caelo-self-hosted:ownerEmail me@example.com
+pulumi up
+```
+
+Pulumi mints postgres + minio passwords, generates `docker-compose.yml` + `Caddyfile` + `pending-token.json` under `.caelo/`, and runs `docker compose up -d`. After the run:
+
+```bash
+pulumi stack output bootstrapUrl
+# → https://example.com/setup?token=<64-hex>
+```
+
+Open that URL once Caddy has issued the cert (~30 s).
+
+## Destroy
+
+```bash
+pulumi destroy
+```
+
+Tears down the compose stack with `-v`, deleting all volumes (Postgres + MinIO + Caddy data). The generated files are removed too.
+
+## Why this exists alongside `cms-provision`
+
+The `cms-provision` CLI is the contributor-friendly path — runs without Pulumi installed, fast iteration on the generators themselves. The Pulumi stack is the **production wrapper**: it exposes a real resource graph for drift detection (operators can see what changed since last `up`), supports `--target` for surgical updates, and gives P15's GCP / AWS / Azure adapters a sibling `stacks/<provider>/` shape to slot into.
+
+Cloud variants in P15 will follow the same pattern: each provider is a sibling Pulumi project under `stacks/`, sharing the compose + Caddyfile generators where applicable and adding provider-specific resources (Cloud SQL, RDS, etc.) on top.