@arcote.tech/arc-cli 0.7.4 → 0.7.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcote.tech/arc-cli",
-  "version": "0.7.4",
+  "version": "0.7.6",
   "description": "CLI tool for Arc framework",
   "module": "index.ts",
   "main": "dist/index.js",
@@ -12,12 +12,14 @@
     "build": "bun build --target=bun ./src/index.ts --outdir=dist --external @arcote.tech/arc --external @arcote.tech/arc-ds --external @arcote.tech/arc-react --external @arcote.tech/platform && chmod +x dist/index.js"
   },
   "dependencies": {
-    "@arcote.tech/arc": "^0.7.4",
-    "@arcote.tech/arc-ds": "^0.7.4",
-    "@arcote.tech/arc-react": "^0.7.4",
-    "@arcote.tech/arc-host": "^0.7.4",
-    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.4",
-    "@arcote.tech/platform": "^0.7.4",
+    "@arcote.tech/arc": "^0.7.6",
+    "@arcote.tech/arc-ds": "^0.7.6",
+    "@arcote.tech/arc-react": "^0.7.6",
+    "@arcote.tech/arc-host": "^0.7.6",
+    "@arcote.tech/arc-adapter-db-sqlite": "^0.7.6",
+    "@arcote.tech/arc-adapter-db-postgres": "^0.7.6",
+    "@arcote.tech/arc-otel": "^0.7.6",
+    "@arcote.tech/platform": "^0.7.6",
     "@clack/prompts": "^0.9.0",
     "commander": "^11.1.0",
     "chokidar": "^3.5.3",

package/src/commands/platform-deploy.ts

@@ -2,12 +2,14 @@ import { existsSync, readFileSync } from "fs";
 import { dirname, join } from "path";
 import { fileURLToPath } from "url";
 import { bootstrap } from "../deploy/bootstrap";
+import { postgresEnvs } from "../deploy/compose";
 import {
   deployConfigExists,
   loadDeployConfig,
   saveDeployConfig,
 } from "../deploy/config";
 import { updateEnvDeployment } from "../deploy/deploy-env";
+import { ensurePersistedSecret } from "../deploy/env-file";
 import { buildImage, sanitizeImageName } from "../deploy/image";
 import { detectRemoteState } from "../deploy/remote-state";
 import { dockerLogin, dockerPush } from "../deploy/registry";
@@ -74,6 +76,27 @@ export async function platformDeploy(
   }
   cfg = loadDeployConfig(ws.rootDir);
 
+  // For every env opted into postgres, make sure the sidecar password is
+  // materialised in `deploy.arc.<env>.env` (gitignored) and in process.env.
+  // Compose generation interpolates `${ARC_PG_PASSWORD_<UPPER>}` later; this
+  // step has to happen before bootstrap renders + uploads compose.yml.
+  const pgEnvs = postgresEnvs(cfg);
+  for (const pg of pgEnvs) {
+    ensurePersistedSecret(ws.rootDir, pg.name, pg.passwordKey, () =>
+      crypto.randomUUID().replace(/-/g, ""),
+    );
+  }
+
+  // Observability stack — one Grafana password per deployment (stack-wide,
+  // not per-env). Persisted in `deploy.arc.env` (globals) so subsequent
+  // deploys reuse the same login.
+  if (cfg.observability?.enabled) {
+    const key = cfg.observability.adminPasswordEnv ?? "ARC_OBSERVABILITY_PASSWORD";
+    ensurePersistedSecret(ws.rootDir, "globals", key, () =>
+      crypto.randomUUID().replace(/-/g, ""),
+    );
+  }
+
   // Filter envs if an arg was provided
   const targetEnvs = envArg
     ? envArg in cfg.envs

package/src/deploy/bootstrap.ts

@@ -7,6 +7,7 @@ import { generateCaddyfile } from "./caddyfile";
 import { generateCompose } from "./compose";
 import type { DeployConfig } from "./config";
 import { generateHtpasswd } from "./htpasswd";
+import { generateObservabilityConfigs } from "./observability-configs";
 import { runTerraform } from "./terraform";
 import { saveDeployConfig } from "./config";
 import { ok, log, err } from "../platform/shared";
@@ -160,6 +161,31 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
  * Used by bootstrap to detect legacy v0.5 stacks that have no registry
  * container and need a fresh stack write + restart.
  */
+/**
+ * Atomically set `KEY=value` in a remote `.env`-style file. Replaces an
+ * existing line with the same key or appends one. Same awk pattern used by
+ * deploy-env.ts to update ARC_IMAGE_<ENV>; values are shell-escaped so
+ * passwords containing `$`, `"`, etc. survive intact.
+ */
+async function writeEnvLine(
+  target: DeployTarget,
+  envPath: string,
+  key: string,
+  value: string,
+): Promise<void> {
+  const escapedValue = value.replace(/"/g, '\\"').replace(/\$/g, "\\$");
+  const script = [
+    `touch ${envPath} && `,
+    `awk -v line="${key}=${escapedValue}" -v key="${key}=" '`,
+    `  BEGIN { replaced=0 } `,
+    `  $0 ~ "^"key { print line; replaced=1; next } `,
+    `  { print } `,
+    `  END { if (!replaced) print line } `,
+    `' ${envPath} > ${envPath}.tmp && mv ${envPath}.tmp ${envPath}`,
+  ].join("");
+  await assertExec(target, script);
+}
+
 async function isRegistryRunning(cfg: DeployConfig): Promise<boolean> {
   const res = await sshExec(
     cfg.target,
@@ -200,6 +226,30 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
   writeFileSync(join(workDir, "Caddyfile"), generateCaddyfile(cfg));
   writeFileSync(join(workDir, "docker-compose.yml"), generateCompose({ cfg }));
 
+  // Observability config files + Caddy basic-auth htpasswd for Grafana.
+  // Bundled together so a deploy without `observability.enabled` skips it
+  // all (no orphan files left on the remote).
+  let observabilityFiles: Record<string, string> | null = null;
+  let observabilityHtpasswd: string | null = null;
+  if (cfg.observability?.enabled) {
+    observabilityFiles = generateObservabilityConfigs(cfg);
+    const adminPasswordEnv =
+      cfg.observability.adminPasswordEnv ?? "ARC_OBSERVABILITY_PASSWORD";
+    const adminPassword = process.env[adminPasswordEnv];
+    if (!adminPassword) {
+      throw new Error(
+        `bootstrap: ${adminPasswordEnv} not set — observability needs a Grafana admin password.`,
+      );
+    }
+    // Caddy basic_auth import file uses `username bcrypt_hash` syntax.
+    observabilityHtpasswd = await generateHtpasswd("admin", adminPassword);
+    mkdirSync(join(workDir, "observability"), { recursive: true });
+    for (const [relPath, contents] of Object.entries(observabilityFiles)) {
+      writeFileSync(join(workDir, relPath), contents);
+    }
+    writeFileSync(join(workDir, "observability-htpasswd"), observabilityHtpasswd);
+  }
+
   // Ensure remoteDir exists
   await assertExec(
     cfg.target,
@@ -232,6 +282,30 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
     `${cfg.target.remoteDir}/registry-auth/htpasswd`,
   );
 
+  // Upload observability assets when enabled. Caddyfile imports
+  // `observability-htpasswd` from /etc/caddy (volume-mounted), so it has
+  // to land in the same dir as Caddyfile on the host. The collector /
+  // tempo / loki / prometheus / grafana configs go into a sibling
+  // `observability/` directory referenced by compose bind-mounts.
+  if (observabilityFiles && observabilityHtpasswd) {
+    await assertExec(
+      cfg.target,
+      `mkdir -p ${cfg.target.remoteDir}/observability`,
+    );
+    for (const relPath of Object.keys(observabilityFiles)) {
+      await scpUpload(
+        cfg.target,
+        join(workDir, relPath),
+        `${cfg.target.remoteDir}/${relPath}`,
+      );
+    }
+    await scpUpload(
+      cfg.target,
+      join(workDir, "observability-htpasswd"),
+      `${cfg.target.remoteDir}/observability-htpasswd`,
+    );
+  }
+
   // Ensure /opt/arc/.env exists so docker compose doesn't error on var
   // substitution. Per-env ARC_IMAGE_<ENV> lines are written by deploy.
   await assertExec(
@@ -239,6 +313,38 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
     `touch ${cfg.target.remoteDir}/.env`,
   );
 
+  // Propagate the Grafana admin password to /opt/arc/.env when observability
+  // is enabled. Compose interpolates `${ARC_OBSERVABILITY_PASSWORD:?}` into
+  // the grafana service's GF_SECURITY_ADMIN_PASSWORD env.
+  if (cfg.observability?.enabled) {
+    const key =
+      cfg.observability.adminPasswordEnv ?? "ARC_OBSERVABILITY_PASSWORD";
+    const value = process.env[key];
+    if (!value) {
+      throw new Error(
+        `bootstrap: ${key} not set — observability needs a Grafana admin password.`,
+      );
+    }
+    await writeEnvLine(cfg.target, `${cfg.target.remoteDir}/.env`, key, value);
+  }
+
+  // Propagate postgres sidecar passwords to /opt/arc/.env so compose can
+  // interpolate `${ARC_PG_PASSWORD_<UPPER>}` for both the pg container and
+  // arc-<env>'s DATABASE_URL. Local source is `deploy.arc.<env>.env` /
+  // process.env (populated by `ensurePersistedSecret` in platform-deploy).
+  // Idempotent: re-runs with the same value are no-ops.
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type !== "postgres") continue;
+    const key = `ARC_PG_PASSWORD_${name.toUpperCase().replace(/-/g, "_")}`;
+    const value = process.env[key];
+    if (!value) {
+      throw new Error(
+        `bootstrap: ${key} not set — postgres env "${name}" requires a password`,
+      );
+    }
+    await writeEnvLine(cfg.target, `${cfg.target.remoteDir}/.env`, key, value);
+  }
+
   // Pre-register the deploy user with the private registry so containers can
   // pull. We do this AFTER `docker compose up -d caddy registry` runs (below)
   // — the registry needs to be reachable for `docker login` to succeed.

package/src/deploy/caddyfile.ts

@@ -30,14 +30,48 @@ export function generateCaddyfile(cfg: DeployConfig): string {
   lines.push("}");
   lines.push("");
 
-  // Public blocks — one per env
+  // Public blocks — one per env. When observability is on, add a `/otel/*`
+  // path that forwards browser-side OTLP/HTTP to the collector. Strips the
+  // /otel prefix so the collector sees the same /v1/{traces,logs,metrics}
+  // paths it would receive from same-network senders.
   for (const [name, env] of Object.entries(cfg.envs)) {
     lines.push(`${env.domain} {${tlsDirective}`);
-    lines.push(`    reverse_proxy arc-${name}:5005`);
+    if (cfg.observability?.enabled) {
+      lines.push("    handle_path /otel/* {");
+      lines.push("        reverse_proxy otel-collector:4318");
+      lines.push("    }");
+      lines.push("    handle {");
+      lines.push(`        reverse_proxy arc-${name}:5005`);
+      lines.push("    }");
+    } else {
+      lines.push(`    reverse_proxy arc-${name}:5005`);
+    }
     lines.push("}");
     lines.push("");
   }
 
+  // Observability subdomain — Grafana UI behind Caddy basic-auth. Reuses
+  // the apex of the first env's domain (e.g. observability.app.example.com
+  // when the primary env is app.example.com). Caddy issues a separate
+  // ACME certificate for this hostname.
+  if (cfg.observability?.enabled) {
+    const firstEnv = Object.values(cfg.envs)[0];
+    if (firstEnv) {
+      const subdomain = cfg.observability.subdomain ?? "observability";
+      const apex = apexOf(firstEnv.domain);
+      const observabilityDomain = `${subdomain}.${apex}`;
+      lines.push(`${observabilityDomain} {${tlsDirective}`);
+      // Basic-auth credentials live in the same htpasswd file used for the
+      // registry — bootstrap appends an "admin" line with bcrypted password.
+      lines.push("    basic_auth {");
+      lines.push("        import /etc/caddy/observability-htpasswd");
+      lines.push("    }");
+      lines.push("    reverse_proxy grafana:3000");
+      lines.push("}");
+      lines.push("");
+    }
+  }
+
   // Private Docker Registry — Caddy proxies HTTPS termination + Let's Encrypt;
   // the registry:2 container handles its own htpasswd basic auth upstream.
   // 5 GiB request body cap fits real app images comfortably (default 100MB
@@ -53,3 +87,12 @@ export function generateCaddyfile(cfg: DeployConfig): string {
 
   return lines.join("\n") + "\n";
 }
+
+/** Apex of a (possibly-subdomain) host. `app.example.com` → `example.com`,
+ *  `example.com` → `example.com`, `example.co.uk` → `co.uk` (approximate —
+ *  good enough for the observability subdomain). */
+function apexOf(host: string): string {
+  const parts = host.split(".");
+  if (parts.length <= 2) return host;
+  return parts.slice(-2).join(".");
+}

package/src/deploy/compose.ts

@@ -3,13 +3,18 @@ import type { DeployConfig } from "./config";
 // ---------------------------------------------------------------------------
 // docker-compose.yml generator
 //
-// Services:
-//   - caddy (public 80/443, loopback 127.0.0.1:2019 for deploy tunnel)
-//   - arc-<env> per entry in deploy.arc.json envs (bind-mounts project dir)
+// Services emitted, in order:
+//   - caddy      (public 80/443, loopback 127.0.0.1:2019 for deploy tunnel)
+//   - registry   (private image store on arc-net, fronted by Caddy auth)
+//   - arc-<env>  (one per entry in deploy.arc.json envs)
+//   - arc-db-<env> (one per env that opts into `db: { type: "postgres" }`)
 //
-// No custom images: vanilla `caddy:2-alpine` and `oven/bun:1-alpine` from
-// Docker Hub. The Arc CLI and user's built artifacts come via the volume
-// mount at /opt/arc/<env>/ — rsynced by the deploy command.
+// SQLite envs persist `/app/.arc/data` in a named volume per env. Postgres
+// envs run a `postgres:16-alpine` sidecar on the docker network — the arc
+// container connects via `DATABASE_URL`, no port is exposed to the host.
+//
+// No custom images: vanilla `caddy:2-alpine`, `registry:2`, `postgres:*`,
+// and `oven/bun:1-alpine` from Docker Hub.
 // ---------------------------------------------------------------------------
 
 export interface ComposeOptions {
@@ -29,6 +34,14 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push('      - "443:443"');
   lines.push("    volumes:");
   lines.push("      - ./Caddyfile:/etc/caddy/Caddyfile:ro");
+  if (cfg.observability?.enabled) {
+    // Bind-mounted in even when the file is absent (Caddy reads it lazily
+    // on observability vhost requests). Always-defined avoids compose
+    // bouncing the container when observability is later disabled.
+    lines.push(
+      "      - ./observability-htpasswd:/etc/caddy/observability-htpasswd:ro",
+    );
+  }
   lines.push("      - caddy_data:/data");
   lines.push("      - caddy_config:/config");
   lines.push("    networks:");
@@ -48,8 +61,6 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push("      REGISTRY_AUTH: htpasswd");
   lines.push('      REGISTRY_AUTH_HTPASSWD_REALM: "Arc Registry"');
   lines.push("      REGISTRY_AUTH_HTPASSWD_PATH: /auth/htpasswd");
-  // Large image layers (framework peers + arc-cli bundle + chunks) need a
-  // generous upload limit. Default 100MB triggers 413 on real apps.
   lines.push('      REGISTRY_HTTP_HOST: "https://' + cfg.registry.domain + '"');
   lines.push("    networks:");
   lines.push("      - arc-net");
@@ -58,7 +69,8 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push("");
 
   for (const [name, env] of Object.entries(cfg.envs)) {
-    const upperName = name.toUpperCase().replace(/-/g, "_");
+    const upperName = upperEnvName(name);
+    const usePostgres = env.db?.type === "postgres";
     lines.push(`  arc-${name}:`);
     // Image ref comes from /opt/arc/.env, written per-deploy with the content
     // hash of the latest build. Default to a placeholder so `docker compose
@@ -69,18 +81,52 @@ export function generateCompose({ cfg }: ComposeOptions): string {
     );
     lines.push(`    container_name: arc-${name}`);
     lines.push("    restart: unless-stopped");
-    lines.push("    volumes:");
-    // Only the data volume — user code lives entirely inside the image.
-    // SQLite + uploads persist across redeploys.
-    lines.push(`      - arc-data-${name}:/app/.arc/data`);
+    if (usePostgres) {
+      lines.push("    depends_on:");
+      lines.push(`      arc-db-${name}:`);
+      lines.push("        condition: service_healthy");
+    }
+    // SQLite envs need a writable volume for `/app/.arc/data`. Postgres
+    // envs keep their state in the sidecar volume; no host-side bind needed.
+    if (!usePostgres) {
+      lines.push("    volumes:");
+      lines.push(`      - arc-data-${name}:/app/.arc/data`);
+    }
     lines.push("    environment:");
     lines.push("      PORT: 5005");
     const userEnv = env.envVars ?? {};
     if (!("NODE_ENV" in userEnv)) {
       lines.push("      NODE_ENV: production");
     }
-    // PORT is reserved — user envVars can't override.
-    const reserved = new Set(["PORT"]);
+    if (usePostgres) {
+      // Connection string follows the docker-internal DNS name + the
+      // password sourced from `deploy.arc.<env>.env`. `arc platform deploy`
+      // ensures `ARC_PG_PASSWORD_<UPPER>` exists in that file before
+      // assembling compose, so the `${VAR:?}` interpolation never fails.
+      lines.push(
+        `      DATABASE_URL: "postgresql://arc:\${ARC_PG_PASSWORD_${upperName}:?missing ARC_PG_PASSWORD_${upperName}}@arc-db-${name}:5432/arc"`,
+      );
+    }
+    if (cfg.observability?.enabled) {
+      // OTel SDK reads OTEL_EXPORTER_OTLP_ENDPOINT and stripts /v1/<signal>
+      // onto it. service.name + deployment.environment land as resource
+      // attributes, which Grafana uses for service-level filtering.
+      lines.push("      ARC_OTEL_ENABLED: \"true\"");
+      lines.push("      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318");
+      lines.push(`      OTEL_SERVICE_NAME: arc-${name}`);
+      lines.push(
+        `      OTEL_RESOURCE_ATTRIBUTES: "service.namespace=arc,deployment.environment=${name}"`,
+      );
+    }
+    // PORT + DATABASE_URL + OTEL_* are reserved — user envVars can't override them.
+    const reserved = new Set([
+      "PORT",
+      "DATABASE_URL",
+      "ARC_OTEL_ENABLED",
+      "OTEL_EXPORTER_OTLP_ENDPOINT",
+      "OTEL_SERVICE_NAME",
+      "OTEL_RESOURCE_ATTRIBUTES",
+    ]);
     for (const [k, v] of Object.entries(userEnv)) {
       if (reserved.has(k)) continue;
       lines.push(`      ${k}: ${JSON.stringify(v)}`);
@@ -93,6 +139,137 @@ export function generateCompose({ cfg }: ComposeOptions): string {
     lines.push("");
   }
 
+  // Postgres sidecars (after the arc services so the YAML reads top-down:
+  // app -> its database). One service per opted-in env.
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type !== "postgres") continue;
+    const upperName = upperEnvName(name);
+    const image = env.db.image ?? "postgres:16-alpine";
+    lines.push(`  arc-db-${name}:`);
+    lines.push(`    image: ${image}`);
+    lines.push(`    container_name: arc-db-${name}`);
+    lines.push("    restart: unless-stopped");
+    lines.push("    environment:");
+    lines.push("      POSTGRES_USER: arc");
+    lines.push("      POSTGRES_DB: arc");
+    lines.push(
+      `      POSTGRES_PASSWORD: \${ARC_PG_PASSWORD_${upperName}:?missing ARC_PG_PASSWORD_${upperName}}`,
+    );
+    lines.push("    volumes:");
+    lines.push(`      - arc-pgdata-${name}:/var/lib/postgresql/data`);
+    lines.push("    healthcheck:");
+    lines.push('      test: ["CMD-SHELL", "pg_isready -U arc -d arc"]');
+    lines.push("      interval: 5s");
+    lines.push("      timeout: 3s");
+    lines.push("      retries: 20");
+    lines.push("    networks:");
+    lines.push("      - arc-net");
+    // No `ports:` — the database is only reachable from other containers
+    // on `arc-net`. Exposing 5432 to the host would defeat the isolation.
+    lines.push("");
+  }
+
+  // Observability sidecars — only when `observability.enabled`. Five
+  // services come up together: otel-collector receives OTLP from app
+  // containers (and from the browser via the public /otel route), fans out
+  // to Tempo/Loki/Prometheus; Grafana ties them into a single UI fronted
+  // by Caddy basic-auth on a separate subdomain.
+  if (cfg.observability?.enabled) {
+    lines.push("  otel-collector:");
+    lines.push("    image: otel/opentelemetry-collector-contrib:0.114.0");
+    lines.push("    container_name: arc-otel-collector");
+    lines.push("    restart: unless-stopped");
+    lines.push("    command: [\"--config=/etc/otelcol-contrib/config.yaml\"]");
+    lines.push("    volumes:");
+    lines.push(
+      "      - ./observability/otel-collector-config.yaml:/etc/otelcol-contrib/config.yaml:ro",
+    );
+    lines.push("    networks: [arc-net]");
+    lines.push("    expose:");
+    lines.push("      - \"4317\"  # OTLP gRPC");
+    lines.push("      - \"4318\"  # OTLP HTTP");
+    lines.push("      - \"8888\"  # collector self-metrics (Prom scrape)");
+    lines.push("    depends_on:");
+    lines.push("      - tempo");
+    lines.push("      - loki");
+    lines.push("      - prometheus");
+    lines.push("");
+
+    lines.push("  tempo:");
+    lines.push("    image: grafana/tempo:2.6.1");
+    lines.push("    container_name: arc-tempo");
+    lines.push("    restart: unless-stopped");
+    lines.push("    command: [\"-config.file=/etc/tempo.yaml\"]");
+    lines.push("    user: \"0\"  # tempo writes to /var/tempo, owned by root in the image");
+    lines.push("    volumes:");
+    lines.push("      - ./observability/tempo.yaml:/etc/tempo.yaml:ro");
+    lines.push("      - tempo_data:/var/tempo");
+    lines.push("    networks: [arc-net]");
+    lines.push("    expose:");
+    lines.push("      - \"3200\"  # HTTP API for Grafana");
+    lines.push("      - \"4317\"  # OTLP from collector");
+    lines.push("");
+
+    lines.push("  loki:");
+    lines.push("    image: grafana/loki:3.3.2");
+    lines.push("    container_name: arc-loki");
+    lines.push("    restart: unless-stopped");
+    lines.push("    command: [\"-config.file=/etc/loki/local-config.yaml\"]");
+    lines.push("    user: \"0\"");
+    lines.push("    volumes:");
+    lines.push("      - ./observability/loki-config.yaml:/etc/loki/local-config.yaml:ro");
+    lines.push("      - loki_data:/loki");
+    lines.push("    networks: [arc-net]");
+    lines.push("    expose:");
+    lines.push("      - \"3100\"  # HTTP API");
+    lines.push("");
+
+    lines.push("  prometheus:");
+    lines.push("    image: prom/prometheus:v2.55.1");
+    lines.push("    container_name: arc-prometheus");
+    lines.push("    restart: unless-stopped");
+    lines.push("    command:");
+    lines.push("      - \"--config.file=/etc/prometheus/prometheus.yml\"");
+    lines.push("      - \"--storage.tsdb.path=/prometheus\"");
+    lines.push("      - \"--web.enable-remote-write-receiver\"");
+    lines.push("      - \"--enable-feature=exemplar-storage\"");
+    lines.push("    volumes:");
+    lines.push("      - ./observability/prometheus.yml:/etc/prometheus/prometheus.yml:ro");
+    lines.push("      - prometheus_data:/prometheus");
+    lines.push("    networks: [arc-net]");
+    lines.push("    expose:");
+    lines.push("      - \"9090\"  # HTTP API + remote_write receiver");
+    lines.push("");
+
+    const adminPasswordEnv = cfg.observability.adminPasswordEnv ?? "ARC_OBSERVABILITY_PASSWORD";
+    lines.push("  grafana:");
+    lines.push("    image: grafana/grafana:11.4.0");
+    lines.push("    container_name: arc-grafana");
+    lines.push("    restart: unless-stopped");
+    lines.push("    environment:");
+    lines.push("      GF_SECURITY_ADMIN_USER: admin");
+    lines.push(
+      `      GF_SECURITY_ADMIN_PASSWORD: \${${adminPasswordEnv}:?missing ${adminPasswordEnv}}`,
+    );
+    lines.push("      GF_USERS_ALLOW_SIGN_UP: \"false\"");
+    lines.push("      GF_AUTH_ANONYMOUS_ENABLED: \"false\"");
+    // Subpath-less — the upstream URL is served from root via Caddy reverse
+    // proxy on a dedicated subdomain.
+    lines.push("    volumes:");
+    lines.push(
+      "      - ./observability/grafana-datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml:ro",
+    );
+    lines.push("      - grafana_data:/var/lib/grafana");
+    lines.push("    networks: [arc-net]");
+    lines.push("    expose:");
+    lines.push("      - \"3000\"  # Grafana UI (behind Caddy basic-auth)");
+    lines.push("    depends_on:");
+    lines.push("      - tempo");
+    lines.push("      - loki");
+    lines.push("      - prometheus");
+    lines.push("");
+  }
+
   lines.push("networks:");
   lines.push("  arc-net:");
   lines.push("");
@@ -100,9 +277,35 @@ export function generateCompose({ cfg }: ComposeOptions): string {
   lines.push("  caddy_data:");
   lines.push("  caddy_config:");
   lines.push("  registry_data:");
-  for (const [name] of Object.entries(cfg.envs)) {
-    lines.push(`  arc-data-${name}:`);
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type === "postgres") {
+      lines.push(`  arc-pgdata-${name}:`);
+    } else {
+      lines.push(`  arc-data-${name}:`);
+    }
+  }
+  if (cfg.observability?.enabled) {
+    lines.push("  tempo_data:");
+    lines.push("  loki_data:");
+    lines.push("  prometheus_data:");
+    lines.push("  grafana_data:");
   }
 
   return lines.join("\n") + "\n";
 }
+
+function upperEnvName(name: string): string {
+  return name.toUpperCase().replace(/-/g, "_");
+}
+
+/** Env names whose `deploy.arc.<env>.env` file must contain a generated
+ *  `ARC_PG_PASSWORD_<UPPER>` before compose can be rendered. */
+export function postgresEnvs(cfg: DeployConfig): { name: string; passwordKey: string }[] {
+  const out: { name: string; passwordKey: string }[] = [];
+  for (const [name, env] of Object.entries(cfg.envs)) {
+    if (env.db?.type !== "postgres") continue;
+    out.push({ name, passwordKey: `ARC_PG_PASSWORD_${upperEnvName(name)}` });
+  }
+  return out;
+}
+