@arcote.tech/arc-cli 0.6.2 → 0.7.1

package/src/deploy/bootstrap.ts

@@ -1,3 +1,4 @@
+import { spawn } from "bun";
 import { mkdirSync, writeFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -5,12 +6,39 @@ import { runAnsible } from "./ansible";
 import { generateCaddyfile } from "./caddyfile";
 import { generateCompose } from "./compose";
 import type { DeployConfig } from "./config";
+import { generateHtpasswd } from "./htpasswd";
 import { runTerraform } from "./terraform";
 import { saveDeployConfig } from "./config";
 import { ok, log, err } from "../platform/shared";
 import { writeStateMarker, STATE_MARKER_PATH } from "./remote-state";
 import type { RemoteState } from "./remote-state";
-import { assertExec, canSsh, scpUpload, waitForSsh } from "./ssh";
+import { assertExec, baseSshArgs, canSsh, scpUpload, sshExec, waitForSsh } from "./ssh";
+import type { DeployTarget } from "./config";
+
+/**
+ * Wait until *any* of the supplied SSH targets accepts a connection. Polls
+ * all targets in parallel each round; the first one that succeeds wins.
+ * Useful when we don't know whether the host is on its first ansible-less
+ * boot (root only) or already hardened (deploy user only).
+ */
+async function waitForAnySsh(
+  targets: DeployTarget[],
+  opts: { timeoutMs?: number; intervalMs?: number } = {},
+): Promise<void> {
+  const timeout = opts.timeoutMs ?? 300_000;
+  const interval = opts.intervalMs ?? 5_000;
+  const start = Date.now();
+  while (Date.now() - start < timeout) {
+    const results = await Promise.all(targets.map((t) => canSsh(t)));
+    if (results.some(Boolean)) return;
+    await Bun.sleep(interval);
+  }
+  throw new Error(
+    `Timed out waiting for SSH on ${targets
+      .map((t) => `${t.user}@${t.host}`)
+      .join(" or ")}`,
+  );
+}
 
 // ---------------------------------------------------------------------------
 // Bootstrap orchestrator.
@@ -33,6 +61,8 @@ export interface BootstrapInputs {
   cliVersion: string;
   /** sha256 of deploy.arc.json — used for the remote state marker. */
   configHash: string;
+  /** Force the ansible run even when the host is already bootstrapped. */
+  forceAnsible?: boolean;
 }
 
 export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
@@ -64,16 +94,31 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
     saveDeployConfig(rootDir, cfg);
 
     log("Waiting for SSH to come up...");
-    await waitForSsh({ ...cfg.target, user: "root" });
+    // On a brand-new VM only root exists; on a re-applied (no-op) terraform
+    // the deploy user already exists and root login is disabled by ansible
+    // hardening. Probe both — succeed on whichever lands first.
+    await waitForAnySsh([
+      { ...cfg.target, user: "root" },
+      { ...cfg.target, user: cfg.target.user },
+    ]);
     ok("SSH reachable");
   }
 
-  if (state.kind === "unreachable" || state.kind === "no-docker") {
+  // Ansible only runs on fresh hosts (unreachable / no-docker) by default —
+  // it's idempotent but slow (~30–60s) and the host config rarely drifts.
+  // `--force-bootstrap` re-runs it on demand (after editing the embedded
+  // playbook, or to recover from manual host edits).
+  const needAnsible =
+    state.kind === "unreachable" ||
+    state.kind === "no-docker" ||
+    inputs.forceAnsible === true;
+
+  if (needAnsible) {
     log("Running Ansible bootstrap (Docker + firewall + SSH hardening)...");
     // Run as root whenever the configured user can't SSH (covers both freshly
     // provisioned VMs and second-attempt deploys after ansible failure).
     const deployUserWorks =
-      state.kind === "no-docker" && (await canSsh(cfg.target));
+      state.kind !== "unreachable" && (await canSsh(cfg.target));
     const asRoot = !deployUserWorks;
     await runAnsible({
       target: cfg.target,
@@ -83,7 +128,21 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
     ok("Host bootstrapped");
   }
 
-  if (state.kind !== "ready") {
+  // Force upStack whenever:
+  //   - stack isn't fully ready, OR
+  //   - marker is missing (legacy v0.5 deploy with no .arc-state.json), OR
+  //   - configHash differs from last bootstrap (deploy.arc.json changed), OR
+  //   - registry container isn't running (e.g. legacy stack predates v0.7)
+  // Without this, an old v0.5 stack (no registry container) is classified as
+  // "ready" and bootstrap is skipped — then `docker login` on the next step
+  // hits a vhost that doesn't exist and fails with a TLS error.
+  const needUpStack =
+    state.kind !== "ready" ||
+    state.marker === null ||
+    state.marker.configHash !== inputs.configHash ||
+    !(await isRegistryRunning(cfg));
+
+  if (needUpStack) {
     await upStack(inputs);
     ok("Docker stack up");
   }
@@ -96,16 +155,50 @@ export async function bootstrap(inputs: BootstrapInputs): Promise<void> {
   });
 }
 
+/**
+ * Returns true iff `registry` service is up in /opt/arc/docker-compose.yml.
+ * Used by bootstrap to detect legacy v0.5 stacks that have no registry
+ * container and need a fresh stack write + restart.
+ */
+async function isRegistryRunning(cfg: DeployConfig): Promise<boolean> {
+  const res = await sshExec(
+    cfg.target,
+    `cd ${cfg.target.remoteDir} && docker compose ps --status running --format '{{.Service}}' 2>/dev/null || true`,
+    { quiet: true },
+  );
+  return res.stdout
+    .split("\n")
+    .map((s) => s.trim())
+    .includes("registry");
+}
+
 async function upStack(inputs: BootstrapInputs): Promise<void> {
   const { cfg } = inputs;
   const workDir = join(tmpdir(), "arc-deploy", `stack-${Date.now()}`);
   mkdirSync(workDir, { recursive: true });
 
-  writeFileSync(join(workDir, "Caddyfile"), generateCaddyfile(cfg));
-  writeFileSync(
-    join(workDir, "docker-compose.yml"),
-    generateCompose({ cfg, cliVersion: inputs.cliVersion }),
+  // Pre-flight DNS — without registry.<domain> resolving to the host, Caddy's
+  // ACME challenge for the registry vhost will fail. Better to bail with a
+  // clear message than let the operator chase TLS retries for 10 minutes.
+  await assertRegistryDnsResolves(cfg);
+
+  // Generate htpasswd locally from the password env var. Never write the
+  // plaintext password to disk; only the bcrypt hash leaves this process.
+  const password = process.env[cfg.registry.passwordEnv];
+  if (!password) {
+    throw new Error(
+      `Registry password env var ${cfg.registry.passwordEnv} is not set. ` +
+        `Set it (e.g. \`export ${cfg.registry.passwordEnv}=...\`) before bootstrap.`,
+    );
+  }
+  const htpasswdLine = await generateHtpasswd(
+    cfg.registry.username,
+    password,
   );
+  writeFileSync(join(workDir, "htpasswd"), htpasswdLine);
+
+  writeFileSync(join(workDir, "Caddyfile"), generateCaddyfile(cfg));
+  writeFileSync(join(workDir, "docker-compose.yml"), generateCompose({ cfg }));
 
   // Ensure remoteDir exists
   await assertExec(
@@ -118,6 +211,10 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
       `mkdir -p ${cfg.target.remoteDir}/${name}`,
     );
   }
+  await assertExec(
+    cfg.target,
+    `mkdir -p ${cfg.target.remoteDir}/registry-auth`,
+  );
 
   await scpUpload(
     cfg.target,
@@ -129,9 +226,172 @@ async function upStack(inputs: BootstrapInputs): Promise<void> {
     join(workDir, "docker-compose.yml"),
     `${cfg.target.remoteDir}/docker-compose.yml`,
   );
+  await scpUpload(
+    cfg.target,
+    join(workDir, "htpasswd"),
+    `${cfg.target.remoteDir}/registry-auth/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(
     cfg.target,
-    `cd ${cfg.target.remoteDir} && docker compose pull --ignore-pull-failures && docker compose up -d`,
+    `touch ${cfg.target.remoteDir}/.env`,
+  );
+
+  // 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.
+  await assertExec(
+    cfg.target,
+    `cd ${cfg.target.remoteDir} && docker compose pull --ignore-pull-failures caddy registry && docker compose up -d caddy registry`,
+  );
+
+  // Wait for the registry vhost to respond (Caddy ACME issuance takes a few
+  // seconds on first start), then docker login on the host. This caches
+  // credentials in /home/<user>/.docker/config.json so subsequent `docker
+  // compose pull arc-<env>` from the per-deploy step can fetch app images.
+  await sshDockerLogin(cfg);
+
+  // Bring up any arc-<env> services whose images are already published.
+  // The :? fallback in compose makes services with no ARC_IMAGE_<ENV> set
+  // fail their up step — we filter those out by reading .env first.
+  const knownEnvs = await listConfiguredEnvs(cfg);
+  if (knownEnvs.length > 0) {
+    await assertExec(
+      cfg.target,
+      `cd ${cfg.target.remoteDir} && docker compose up -d ${knownEnvs
+        .map((e) => `arc-${e}`)
+        .join(" ")}`,
+    );
+  }
+}
+
+/**
+ * Log in to the private registry from the deploy user's account on the host.
+ * Required so `docker compose pull arc-<env>` works on subsequent deploys
+ * (compose runs docker from the deploy user's perspective; that user's
+ * `.docker/config.json` is where the registry token lives).
+ */
+async function sshDockerLogin(cfg: DeployConfig): Promise<void> {
+  const password = process.env[cfg.registry.passwordEnv];
+  if (!password) {
+    throw new Error(
+      `Registry password env var ${cfg.registry.passwordEnv} is not set on the deploy host (CLI machine).`,
+    );
+  }
+  // Stream password over SSH stdin — never reach the command line (no shell
+  // history, no `ps`, no double-shell-escape bugs). The remote shell pipes
+  // its own stdin straight into `docker login --password-stdin`.
+  const cmd = `docker login ${cfg.registry.domain} -u ${cfg.registry.username} --password-stdin`;
+  const proc = spawn({
+    cmd: [
+      "ssh",
+      ...baseSshArgs(cfg.target),
+      `${cfg.target.user}@${cfg.target.host}`,
+      "--",
+      cmd,
+    ],
+    stdin: "pipe",
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  if (proc.stdin) {
+    await (proc.stdin as any).write(new TextEncoder().encode(password));
+    await (proc.stdin as any).end?.();
+  }
+  const exit = await proc.exited;
+  if (exit !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(
+      `Server-side docker login failed (exit ${exit}): ${stderr.trim()}`,
+    );
+  }
+}
+
+/**
+ * Read /opt/arc/.env on the host and return env names that have an
+ * `ARC_IMAGE_<ENV>=...` line set. Used by bootstrap to decide which arc-<env>
+ * services can safely be started (the others would fail compose var
+ * substitution with `:?`).
+ */
+async function listConfiguredEnvs(cfg: DeployConfig): Promise<string[]> {
+  const res = await sshExec(
+    cfg.target,
+    `cat ${cfg.target.remoteDir}/.env 2>/dev/null || true`,
+    { quiet: true },
   );
+  const set = new Set<string>();
+  for (const line of res.stdout.split("\n")) {
+    const m = line.match(/^ARC_IMAGE_([A-Z0-9_]+)=/);
+    if (!m) continue;
+    const lowerName = m[1].toLowerCase().replace(/_/g, "-");
+    if (lowerName in cfg.envs) set.add(lowerName);
+  }
+  return [...set];
+}
+
+/**
+ * Verify that `<registry.domain>` resolves to the target host's IP. If DNS
+ * isn't propagated yet, Caddy's ACME challenge for the registry vhost will
+ * fail repeatedly. Fail fast with an actionable hint instead.
+ */
+async function assertRegistryDnsResolves(cfg: DeployConfig): Promise<void> {
+  // Source of truth for "is the DNS update live?" is the authoritative NS for
+  // the apex domain — public resolvers (8.8.8.8 / 1.1.1.1) cache for minutes
+  // after a record change and disagree among themselves during propagation.
+  // Let's Encrypt ACME validates against the authoritative NS too, so this
+  // matches what Caddy will see when it tries to issue the cert.
+  const apex = apexDomain(cfg.registry.domain);
+  let nameservers = await digQuery("8.8.8.8", "NS", apex);
+  nameservers = nameservers.map((s) => s.replace(/\.$/, ""));
+
+  // Sources to query, in order: authoritative NS, then public resolvers.
+  // Accept the first source where any answer matches target.host.
+  const sources = [...nameservers, "1.1.1.1", "8.8.8.8"];
+  let lastAnswers: string[] = [];
+
+  for (const source of sources) {
+    const answers = await digQuery(source, "A", cfg.registry.domain);
+    if (answers.length === 0) continue;
+    lastAnswers = answers;
+    if (answers.includes(cfg.target.host)) return;
+  }
+
+  if (lastAnswers.length === 0) {
+    throw new Error(
+      `Registry DNS not configured: ${cfg.registry.domain} doesn't resolve. ` +
+        `Add an A record pointing to ${cfg.target.host} and re-run deploy.`,
+    );
+  }
+  throw new Error(
+    `Registry DNS mismatch: ${cfg.registry.domain} resolves to [${lastAnswers.join(", ")}], ` +
+      `but target host is ${cfg.target.host}. Update the A record before continuing.`,
+  );
+}
+
+function apexDomain(host: string): string {
+  // Naive eTLD+1 extraction: last 2 labels. Works for `.pl`, `.com`, etc.
+  // For `.co.uk` style TLDs the authoritative NS query still returns the
+  // correct NS — dig handles the SOA chase upstream.
+  const parts = host.split(".");
+  return parts.slice(-2).join(".");
+}
+
+async function digQuery(
+  server: string,
+  type: "A" | "NS",
+  name: string,
+): Promise<string[]> {
+  const proc = spawn({
+    cmd: ["dig", `@${server}`, "+short", "+time=3", "+tries=1", type, name],
+    stdout: "pipe",
+    stderr: "ignore",
+  });
+  const exit = await proc.exited;
+  if (exit !== 0) return [];
+  return (await new Response(proc.stdout).text())
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
 }

package/src/deploy/caddyfile.ts

@@ -3,18 +3,16 @@ import type { DeployConfig } from "./config";
 // ---------------------------------------------------------------------------
 // Caddyfile generator
 //
-// Two kinds of blocks are produced:
+// Two kinds of vhosts:
 //
-//  1. Public site blocks (80/443) — one per env, routed by Host header.
-//     Reverse-proxy to arc-<env>:5005 BUT strip any /api/deploy/* path so
-//     the hot-swap endpoint never leaks to the internet.
+//  1. Public env blocks (80/443) — one per env, routed by Host header.
+//     Plain reverse-proxy to arc-<env>:5005. No /api/deploy/* paths exist
+//     in v0.7 (deploy goes through docker push, not HTTP), so there's
+//     nothing to block at the Caddy level.
 //
-//  2. Internal management listener on 127.0.0.1:2019 — handles
-//     /env/<name>/api/deploy/* paths by rewriting and proxying to
-//     arc-<name>:5005/api/deploy/*. This is the ONLY path to the deploy
-//     API from off-host; the listener is bound to loopback inside the
-//     Caddy container, and docker-compose publishes 127.0.0.1:2019:2019.
-//     CLI reaches it via `ssh -L`.
+//  2. Private Docker Registry vhost — proxies registry.<domain> to the
+//     in-cluster `registry:2` service. htpasswd basic auth is enforced on
+//     the registry container side; Caddy just terminates TLS.
 // ---------------------------------------------------------------------------
 
 export function generateCaddyfile(cfg: DeployConfig): string {
@@ -35,24 +33,22 @@ export function generateCaddyfile(cfg: DeployConfig): string {
   // Public blocks — one per env
   for (const [name, env] of Object.entries(cfg.envs)) {
     lines.push(`${env.domain} {${tlsDirective}`);
-    lines.push("    @deploy path /api/deploy /api/deploy/*");
-    lines.push("    respond @deploy 404");
-    lines.push("");
     lines.push(`    reverse_proxy arc-${name}:5005`);
     lines.push("}");
     lines.push("");
   }
 
-  // Internal management listener
-  lines.push("# Loopback-only management listener (SSH tunnel access).");
-  lines.push("http://127.0.0.1:2019 {");
-  lines.push("    bind 127.0.0.1");
-  for (const [name] of Object.entries(cfg.envs)) {
-    lines.push(`    handle_path /env/${name}/* {`);
-    lines.push(`        reverse_proxy arc-${name}:5005`);
-    lines.push(`    }`);
-  }
-  lines.push("    respond 404");
+  // 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
+  // triggers 413 on the first layer push).
+  lines.push(`${cfg.registry.domain} {${tlsDirective}`);
+  lines.push("    reverse_proxy registry:5000 {");
+  lines.push("        header_up Host {host}");
+  lines.push("    }");
+  lines.push("    request_body {");
+  lines.push("        max_size 5GB");
+  lines.push("    }");
   lines.push("}");
 
   return lines.join("\n") + "\n";

package/src/deploy/compose.ts

@@ -1,41 +1,32 @@
 import type { DeployConfig } from "./config";
 
 // ---------------------------------------------------------------------------
-// docker-compose.yml generator — v0.6
+// 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
+//   - arc-<env> per entry in deploy.arc.json envs (bind-mounts project dir)
 //
-// arc-<env> uses `arcote/runtime:1` (generic image). CLI version is passed
-// via ARC_CLI_VERSION env var — entrypoint installs arc-cli on first boot,
-// then `arc platform start` decides between pre-deploy and full mode based
-// on volume state. No user code or node_modules on host disk (everything
-// lives in named volumes, populated via /api/deploy/* multipart pushes).
+// 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.
 // ---------------------------------------------------------------------------
 
 export interface ComposeOptions {
   cfg: DeployConfig;
-  /** CLI version used by entrypoint.sh to `bun add @arcote.tech/arc-cli@VER`. */
-  cliVersion: string;
 }
 
-const RESERVED_ENV = new Set(["PORT", "ARC_DEPLOY_API", "ARC_CLI_VERSION"]);
-
-export function generateCompose({ cfg, cliVersion }: ComposeOptions): string {
+export function generateCompose({ cfg }: ComposeOptions): string {
   const lines: string[] = [];
   lines.push("# Generated by `arc platform deploy` — do not edit by hand.");
   lines.push("");
   lines.push("services:");
-
-  // Caddy
   lines.push("  caddy:");
   lines.push("    image: caddy:2-alpine");
   lines.push("    restart: unless-stopped");
   lines.push("    ports:");
   lines.push('      - "80:80"');
   lines.push('      - "443:443"');
-  lines.push('      - "127.0.0.1:2019:2019"');
   lines.push("    volumes:");
   lines.push("      - ./Caddyfile:/etc/caddy/Caddyfile:ro");
   lines.push("      - caddy_data:/data");
@@ -44,28 +35,57 @@ export function generateCompose({ cfg, cliVersion }: ComposeOptions): string {
   lines.push("      - arc-net");
   lines.push("");
 
-  // Per-env runtime containers
+  // Private Docker Registry — `arc platform deploy` pushes app images here,
+  // arc-<env> containers pull from here. htpasswd auth file is uploaded by
+  // bootstrap (generated locally from the password env var).
+  lines.push("  registry:");
+  lines.push("    image: registry:2");
+  lines.push("    restart: unless-stopped");
+  lines.push("    volumes:");
+  lines.push("      - registry_data:/var/lib/registry");
+  lines.push("      - ./registry-auth/htpasswd:/auth/htpasswd:ro");
+  lines.push("    environment:");
+  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");
+  lines.push("    expose:");
+  lines.push('      - "5000"');
+  lines.push("");
+
   for (const [name, env] of Object.entries(cfg.envs)) {
+    const upperName = name.toUpperCase().replace(/-/g, "_");
     lines.push(`  arc-${name}:`);
-    lines.push("    image: pkrasinski/arc-runtime:1");
+    // 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
+    // pull caddy registry` doesn't fail with `:?` interpolation errors on this
+    // service before the first deploy ever sets ARC_IMAGE_<ENV>.
+    lines.push(
+      `    image: \${ARC_IMAGE_${upperName}:-arc-${name}:not-deployed}`,
+    );
+    lines.push(`    container_name: arc-${name}`);
     lines.push("    restart: unless-stopped");
     lines.push("    volumes:");
-    lines.push(`      - arc-platform-${name}:/app/.arc/platform`);
+    // Only the data volume — user code lives entirely inside the image.
+    // SQLite + uploads persist across redeploys.
     lines.push(`      - arc-data-${name}:/app/.arc/data`);
-    lines.push("      - arc-cli-cache:/app/.arc/cli");
-    lines.push("      - arc-bun-cache:/root/.bun/install/cache");
     lines.push("    environment:");
     lines.push("      PORT: 5005");
-    lines.push('      ARC_DEPLOY_API: "1"');
-    lines.push(`      ARC_CLI_VERSION: ${JSON.stringify(cliVersion)}`);
     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"]);
     for (const [k, v] of Object.entries(userEnv)) {
-      if (RESERVED_ENV.has(k)) continue;
+      if (reserved.has(k)) continue;
       lines.push(`      ${k}: ${JSON.stringify(v)}`);
     }
+    // ENTRYPOINT + CMD come from the image — no `command:` override needed.
     lines.push("    networks:");
     lines.push("      - arc-net");
     lines.push("    expose:");
@@ -73,17 +93,14 @@ export function generateCompose({ cfg, cliVersion }: ComposeOptions): string {
     lines.push("");
   }
 
-  // Networks + volumes
   lines.push("networks:");
   lines.push("  arc-net:");
   lines.push("");
   lines.push("volumes:");
   lines.push("  caddy_data:");
   lines.push("  caddy_config:");
-  lines.push("  arc-cli-cache:");
-  lines.push("  arc-bun-cache:");
+  lines.push("  registry_data:");
   for (const [name] of Object.entries(cfg.envs)) {
-    lines.push(`  arc-platform-${name}:`);
     lines.push(`  arc-data-${name}:`);
   }
 

package/src/deploy/config.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, writeFileSync } from "fs";
 import { join } from "path";
+import { applyDeployGlobals, loadDeployEnvFiles } from "./env-file";
 
 // ---------------------------------------------------------------------------
 // deploy.arc.json — single source of truth for deployment configuration.
@@ -54,10 +55,20 @@ export interface DeployProvision {
   ansible?: DeployProvisionAnsible;
 }
 
+export interface DeployRegistry {
+  /** Full domain — Caddy reverse-proxies this to the registry:5000 container. */
+  domain: string;
+  /** htpasswd basic-auth username. Default: `deploy`. */
+  username: string;
+  /** Name of env var holding the htpasswd password. Never inline the secret. */
+  passwordEnv: string;
+}
+
 export interface DeployConfig {
   target: DeployTarget;
   envs: Record<string, DeployEnv>;
   caddy: DeployCaddy;
+  registry: DeployRegistry;
   provision?: DeployProvision;
 }
 
@@ -76,8 +87,17 @@ export function deployConfigExists(rootDir: string): boolean {
 }
 
 /**
- * Load deploy.arc.json, expand `${VAR}` references against process.env,
- * and validate shape. Throws with a precise error on any issue.
+ * Load deploy.arc.json + side-car env files (deploy.arc.env for globals,
+ * deploy.arc.<env>.env for per-env secrets), expand `${VAR}` references
+ * against process.env, and validate shape.
+ *
+ * Resolution order (last wins):
+ *   1. deploy.arc.json `envs.<name>.envVars` (declared in config)
+ *   2. deploy.arc.<name>.env (sidecar file, gitignored)
+ *   3. existing process.env values (CI/CD secret store)
+ *
+ * Globals from `deploy.arc.env` populate process.env (without overriding
+ * existing values), so terraform/dockerLogin/ansible see them naturally.
  */
 export function loadDeployConfig(rootDir: string): DeployConfig {
   const path = deployConfigPath(rootDir);
@@ -91,8 +111,33 @@ export function loadDeployConfig(rootDir: string): DeployConfig {
   } catch (e) {
     throw new Error(`Invalid JSON in ${DEPLOY_CONFIG_FILE}: ${(e as Error).message}`);
   }
+
+  // Read env names from raw JSON (pre-validation) to know which sidecar
+  // files to look for. Validation runs next.
+  const envNames = isObject(parsed) && isObject(parsed.envs)
+    ? Object.keys(parsed.envs)
+    : [];
+  const envFiles = loadDeployEnvFiles(rootDir, envNames);
+
+  // Globals → process.env (without overriding) so downstream code can read
+  // HCLOUD_TOKEN, ARC_REGISTRY_PASSWORD etc. as if they were exported in shell.
+  applyDeployGlobals(envFiles.globals);
+
   const expanded = expandEnvVars(parsed, process.env);
-  return validateDeployConfig(expanded);
+  const validated = validateDeployConfig(expanded);
+
+  // Merge sidecar per-env vars into cfg.envs[name].envVars.
+  // Existing keys (declared in deploy.arc.json) win over sidecar — config is
+  // the source of truth for variable NAMES, sidecar provides VALUES for
+  // anything not pinned otherwise.
+  for (const [envName, vars] of Object.entries(envFiles.perEnv)) {
+    if (!(envName in validated.envs)) continue;
+    const env = validated.envs[envName];
+    const merged: Record<string, string> = { ...vars, ...(env.envVars ?? {}) };
+    validated.envs[envName] = { ...env, envVars: merged };
+  }
+
+  return validated;
 }
 
 export function saveDeployConfig(rootDir: string, cfg: DeployConfig): void {
@@ -139,6 +184,20 @@ export function validateDeployConfig(input: unknown): DeployConfig {
   const target = requireObject(input, "target");
   const envs = requireObject(input, "envs");
   const caddy = requireObject(input, "caddy");
+  const registry = requireObject(input, "registry");
+
+  const registryDomain = requireString(registry, "registry.domain");
+  if (!/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(registryDomain)) {
+    throw new Error(
+      `deploy.arc.json: registry.domain "${registryDomain}" doesn't look like a domain`,
+    );
+  }
+  const passwordEnv = requireString(registry, "registry.passwordEnv");
+  if (!/^[A-Z][A-Z0-9_]*$/.test(passwordEnv)) {
+    throw new Error(
+      `deploy.arc.json: registry.passwordEnv "${passwordEnv}" must be an UPPER_SNAKE_CASE env var name`,
+    );
+  }
 
   const validated: DeployConfig = {
     target: {
@@ -152,6 +211,11 @@ export function validateDeployConfig(input: unknown): DeployConfig {
     caddy: {
       email: requireString(caddy, "caddy.email"),
     },
+    registry: {
+      domain: registryDomain,
+      username: optionalString(registry, "registry.username") ?? "deploy",
+      passwordEnv,
+    },
   };
 
   const envKeys = Object.keys(envs);