@envsync-cloud/deploy-cli 0.6.2 → 0.6.4

package/README.md

@@ -40,13 +40,13 @@ bunx @envsync-cloud/deploy-cli <command>
 ```text
 envsync-deploy preinstall
 envsync-deploy setup
-envsync-deploy bootstrap
-envsync-deploy deploy
+envsync-deploy bootstrap [--dry-run]
+envsync-deploy deploy [--dry-run]
 envsync-deploy health [--json]
-envsync-deploy upgrade
-envsync-deploy upgrade-deps
-envsync-deploy backup
-envsync-deploy restore <archive>
+envsync-deploy upgrade [--dry-run]
+envsync-deploy upgrade-deps [--dry-run]
+envsync-deploy backup [--dry-run]
+envsync-deploy restore <archive> [--dry-run]
 ```
 
 ## Quick Start
@@ -63,6 +63,8 @@ Write the desired self-hosted config:
 npx @envsync-cloud/deploy-cli setup
 ```
 
+`setup` requires an exact release version such as `0.6.2`. Channel names like `stable` and `latest` are not accepted for self-hosted installs.
+
 Bootstrap infra, migrations, RustFS, and OpenFGA:
 
 ```bash
@@ -77,7 +79,7 @@ npx @envsync-cloud/deploy-cli deploy
 
 The staged flow is:
 - `setup` writes desired config
-- `bootstrap` starts infra and persists generated runtime env state
+- `bootstrap` starts base infra, runs OpenFGA and miniKMS migrations, starts runtime infra, and persists generated runtime env state
 - `deploy` starts the pending API and frontend services
 
 Check service health:
@@ -98,6 +100,13 @@ Restore from an existing backup archive:
 npx @envsync-cloud/deploy-cli restore /path/to/envsync-backup.tar.gz
 ```
 
+Preview mutating commands without changing the host:
+
+```bash
+npx @envsync-cloud/deploy-cli bootstrap --dry-run
+npx @envsync-cloud/deploy-cli deploy --dry-run
+```
+
 ## Links
 
 - Repository: https://github.com/EnvSync-Cloud/envsync

package/dist/index.js

@@ -6,6 +6,7 @@ import { spawnSync } from "child_process";
 import fs from "fs";
 import path from "path";
 import readline from "readline";
+import chalk from "chalk";
 var HOST_ROOT = "/opt/envsync";
 var DEPLOY_ROOT = "/opt/envsync/deploy";
 var RELEASES_ROOT = "/opt/envsync/releases";
@@ -17,6 +18,7 @@ var DEPLOY_ENV = "/etc/envsync/deploy.env";
 var DEPLOY_YAML = "/etc/envsync/deploy.yaml";
 var VERSIONS_LOCK = "/opt/envsync/deploy/versions.lock.json";
 var STACK_FILE = "/opt/envsync/deploy/docker-stack.yaml";
+var BOOTSTRAP_BASE_STACK_FILE = "/opt/envsync/deploy/docker-stack.bootstrap.base.yaml";
 var BOOTSTRAP_STACK_FILE = "/opt/envsync/deploy/docker-stack.bootstrap.yaml";
 var TRAEFIK_DYNAMIC_FILE = "/opt/envsync/deploy/traefik-dynamic.yaml";
 var KEYCLOAK_REALM_FILE = "/opt/envsync/deploy/keycloak-realm.envsync.json";
@@ -45,6 +47,34 @@ var REQUIRED_BOOTSTRAP_ENV_KEYS = [
   "OPENFGA_STORE_ID",
   "OPENFGA_MODEL_ID"
 ];
+var SEMVER_VERSION_RE = /^\d+\.\d+\.\d+$/;
+var currentOptions = { dryRun: false };
+function formatShellArg(arg) {
+  if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(arg)) return arg;
+  return JSON.stringify(arg);
+}
+function formatCommand(cmd, args) {
+  return [cmd, ...args].map(formatShellArg).join(" ");
+}
+function logSection(title) {
+  console.log(`
+${chalk.bold.blue(title)}`);
+}
+function logStep(message) {
+  console.log(`${chalk.cyan("[step]")} ${message}`);
+}
+function logInfo(message) {
+  console.log(`${chalk.blue("[info]")} ${message}`);
+}
+function logSuccess(message) {
+  console.log(`${chalk.green("[ok]")} ${message}`);
+}
+function logDryRun(message) {
+  console.log(`${chalk.magenta("[dry-run]")} ${message}`);
+}
+function logCommand(cmd, args) {
+  console.log(chalk.dim(`$ ${formatCommand(cmd, args)}`));
+}
 function run(cmd, args, opts = {}) {
   const result = spawnSync(cmd, args, {
     cwd: opts.cwd,
@@ -83,6 +113,13 @@ function writeFile(target, content, mode) {
   fs.writeFileSync(target, content, "utf8");
   if (mode != null) fs.chmodSync(target, mode);
 }
+function writeFileMaybe(target, content, mode) {
+  if (currentOptions.dryRun) {
+    logDryRun(`Would write ${target}`);
+    return;
+  }
+  writeFile(target, content, mode);
+}
 function exists(target) {
   return fs.existsSync(target);
 }
@@ -203,16 +240,120 @@ function getDeployCliVersion() {
     return process.env.npm_package_version ?? "0.0.0";
   }
 }
-function defaultSourceConfig() {
+function assertSemverVersion(version, label = "release version") {
+  if (!SEMVER_VERSION_RE.test(version)) {
+    throw new Error(`Invalid ${label} '${version}'. Expected an exact semver like 0.6.2.`);
+  }
+}
+function versionedImages(version) {
+  assertSemverVersion(version);
+  return {
+    api: `ghcr.io/envsync-cloud/envsync-api:${version}`,
+    keycloak: `envsync-keycloak:${version}`,
+    web: `ghcr.io/envsync-cloud/envsync-web-static:${version}`,
+    landing: `ghcr.io/envsync-cloud/envsync-landing-static:${version}`
+  };
+}
+function defaultSourceConfig(version) {
   return {
     repo_url: "https://github.com/EnvSync-Cloud/envsync.git",
-    ref: `v${getDeployCliVersion()}`
+    ref: `v${version}`
   };
 }
+function resolveReleaseVersion(raw) {
+  const releaseVersion = raw.release?.version;
+  if (releaseVersion) {
+    assertSemverVersion(releaseVersion);
+    return releaseVersion;
+  }
+  if (typeof raw.release_channel === "string" && raw.release_channel.length > 0) {
+    if (SEMVER_VERSION_RE.test(raw.release_channel)) {
+      return raw.release_channel;
+    }
+    if (raw.release_channel === "stable" || raw.release_channel === "latest") {
+      throw new Error(
+        "Legacy release channel config is no longer supported for self-hosted installs. Set an exact release version in /etc/envsync/deploy.yaml."
+      );
+    }
+    throw new Error(`Invalid legacy release channel '${raw.release_channel}'. Set an exact release version in /etc/envsync/deploy.yaml.`);
+  }
+  return getDeployCliVersion();
+}
+function requireDefined(value, label) {
+  if (value === void 0) {
+    throw new Error(`Missing ${label} in ${DEPLOY_YAML}. Run setup again.`);
+  }
+  return value;
+}
 function normalizeConfig(raw) {
+  const version = resolveReleaseVersion(raw);
+  const derivedImages = versionedImages(version);
+  const { release_channel: _legacyReleaseChannel, ...rest } = raw;
+  const rootDomain = requireDefined(raw.domain?.root_domain, "domain.root_domain");
+  const acmeEmail = requireDefined(raw.domain?.acme_email, "domain.acme_email");
   return {
-    ...raw,
-    source: raw.source ?? defaultSourceConfig()
+    ...rest,
+    source: {
+      repo_url: raw.source?.repo_url ?? "https://github.com/EnvSync-Cloud/envsync.git",
+      ref: `v${version}`
+    },
+    release: {
+      version
+    },
+    domain: {
+      root_domain: rootDomain,
+      acme_email: acmeEmail
+    },
+    images: {
+      api: derivedImages.api,
+      keycloak: derivedImages.keycloak,
+      web: derivedImages.web,
+      landing: derivedImages.landing,
+      clickstack: raw.images?.clickstack ?? "clickhouse/clickstack-all-in-one:latest",
+      traefik: raw.images?.traefik ?? "traefik:v3.1",
+      otel_agent: raw.images?.otel_agent ?? "otel/opentelemetry-collector-contrib:0.111.0"
+    },
+    services: {
+      stack_name: requireDefined(raw.services?.stack_name, "services.stack_name"),
+      api_port: requireDefined(raw.services?.api_port, "services.api_port"),
+      clickstack_ui_port: requireDefined(raw.services?.clickstack_ui_port, "services.clickstack_ui_port"),
+      clickstack_otlp_http_port: requireDefined(raw.services?.clickstack_otlp_http_port, "services.clickstack_otlp_http_port"),
+      clickstack_otlp_grpc_port: requireDefined(raw.services?.clickstack_otlp_grpc_port, "services.clickstack_otlp_grpc_port"),
+      keycloak_port: requireDefined(raw.services?.keycloak_port, "services.keycloak_port"),
+      rustfs_port: requireDefined(raw.services?.rustfs_port, "services.rustfs_port"),
+      rustfs_console_port: requireDefined(raw.services?.rustfs_console_port, "services.rustfs_console_port")
+    },
+    auth: {
+      keycloak_realm: requireDefined(raw.auth?.keycloak_realm, "auth.keycloak_realm"),
+      admin_user: requireDefined(raw.auth?.admin_user, "auth.admin_user"),
+      admin_password: requireDefined(raw.auth?.admin_password, "auth.admin_password"),
+      web_client_id: requireDefined(raw.auth?.web_client_id, "auth.web_client_id"),
+      api_client_id: requireDefined(raw.auth?.api_client_id, "auth.api_client_id"),
+      cli_client_id: requireDefined(raw.auth?.cli_client_id, "auth.cli_client_id")
+    },
+    observability: {
+      retention_days: requireDefined(raw.observability?.retention_days, "observability.retention_days"),
+      public_obs: requireDefined(raw.observability?.public_obs, "observability.public_obs")
+    },
+    backup: {
+      output_dir: requireDefined(raw.backup?.output_dir, "backup.output_dir"),
+      encrypted: requireDefined(raw.backup?.encrypted, "backup.encrypted")
+    },
+    smtp: {
+      host: requireDefined(raw.smtp?.host, "smtp.host"),
+      port: requireDefined(raw.smtp?.port, "smtp.port"),
+      secure: requireDefined(raw.smtp?.secure, "smtp.secure"),
+      user: requireDefined(raw.smtp?.user, "smtp.user"),
+      pass: requireDefined(raw.smtp?.pass, "smtp.pass"),
+      from: requireDefined(raw.smtp?.from, "smtp.from")
+    },
+    exposure: {
+      public_auth: requireDefined(raw.exposure?.public_auth, "exposure.public_auth"),
+      public_obs: requireDefined(raw.exposure?.public_obs, "exposure.public_obs"),
+      mailpit_enabled: requireDefined(raw.exposure?.mailpit_enabled, "exposure.mailpit_enabled"),
+      s3_public: requireDefined(raw.exposure?.s3_public, "exposure.s3_public"),
+      s3_console_public: requireDefined(raw.exposure?.s3_console_public, "exposure.s3_console_public")
+    }
   };
 }
 function emptyGeneratedState() {
@@ -550,8 +691,10 @@ function renderOtelAgentConfig(config) {
     "      exporters: [otlphttp/clickstack]"
   ].join("\n") + "\n";
 }
-function renderStack(config, runtimeEnv, includeAppServices) {
+function renderStack(config, runtimeEnv, mode) {
   const hosts = domainMap(config.domain.root_domain);
+  const includeRuntimeInfra = mode !== "base";
+  const includeAppServices = mode === "full";
   const apiEnvironment = {
     ...runtimeEnv,
     OTEL_EXPORTER_OTLP_ENDPOINT: "http://otel-agent:4318",
@@ -644,7 +787,7 @@ ${renderEnvList({
     volumes:
       - keycloak_db_data:/var/lib/postgresql/data
     networks: [envsync]
-
+${includeRuntimeInfra ? `
   keycloak:
     image: ${config.images.keycloak}
     entrypoint: ["/bin/sh", "-lc"]
@@ -659,8 +802,9 @@ ${renderEnvList({
     KC_BOOTSTRAP_ADMIN_USERNAME: config.auth.admin_user,
     KC_BOOTSTRAP_ADMIN_PASSWORD: config.auth.admin_password,
     KC_HTTP_ENABLED: "true",
+    KC_HEALTH_ENABLED: "true",
     KC_PROXY_HEADERS: "xforwarded",
-    KC_HOSTNAME: hosts.auth
+    KC_HOSTNAME_STRICT: "false"
   })}
     volumes:
       - ${KEYCLOAK_REALM_FILE}:/opt/keycloak/data/import/realm.json:ro
@@ -671,7 +815,7 @@ ${renderEnvList({
         - traefik.http.routers.keycloak.rule=Host(\`${hosts.auth}\`)
         - traefik.http.routers.keycloak.entrypoints=websecure
         - traefik.http.routers.keycloak.tls.certresolver=letsencrypt
-        - traefik.http.services.keycloak.loadbalancer.server.port=8080
+        - traefik.http.services.keycloak.loadbalancer.server.port=8080` : ""}
 
   openfga_db:
     image: postgres:17
@@ -684,7 +828,7 @@ ${renderEnvList({
     volumes:
       - openfga_db_data:/var/lib/postgresql/data
     networks: [envsync]
-
+${includeRuntimeInfra ? `
   openfga:
     image: openfga/openfga:v1.12.0
     command: run
@@ -695,7 +839,7 @@ ${renderEnvList({
     OPENFGA_HTTP_ADDR: "0.0.0.0:8090",
     OPENFGA_GRPC_ADDR: "0.0.0.0:8091"
   })}
-    networks: [envsync]
+    networks: [envsync]` : ""}
 
   minikms_db:
     image: postgres:17
@@ -708,7 +852,7 @@ ${renderEnvList({
     volumes:
       - minikms_db_data:/var/lib/postgresql/data
     networks: [envsync]
-
+${includeRuntimeInfra ? `
   minikms:
     image: ghcr.io/envsync-cloud/minikms:sha-735dfe8
     environment:
@@ -719,7 +863,7 @@ ${renderEnvList({
     MINIKMS_GRPC_ADDR: "0.0.0.0:50051",
     MINIKMS_TLS_ENABLED: "false"
   })}
-    networks: [envsync]
+    networks: [envsync]` : ""}
 
   clickstack:
     image: ${config.images.clickstack}
@@ -789,39 +933,59 @@ volumes:
 }
 function writeDeployArtifacts(config, generated) {
   const runtimeEnv = buildRuntimeEnv(config, generated);
-  writeFile(DEPLOY_ENV, renderEnvFile(runtimeEnv), 384);
-  writeFile(
+  logStep("Rendering deploy artifacts");
+  writeFileMaybe(DEPLOY_ENV, renderEnvFile(runtimeEnv), 384);
+  writeFileMaybe(
     INTERNAL_CONFIG_JSON,
     JSON.stringify({ config, generated: mergeGeneratedState(runtimeEnv, generated) }, null, 2) + "\n"
   );
-  writeFile(VERSIONS_LOCK, JSON.stringify(config.images, null, 2) + "\n");
-  writeFile(KEYCLOAK_REALM_FILE, renderKeycloakRealm(config, runtimeEnv));
-  writeFile(TRAEFIK_DYNAMIC_FILE, renderTraefikDynamicConfig(config));
-  writeFile(STACK_FILE, renderStack(config, runtimeEnv, true));
-  writeFile(BOOTSTRAP_STACK_FILE, renderStack(config, runtimeEnv, false));
-  writeFile(NGINX_WEB_CONF, renderNginxConf("web"));
-  writeFile(NGINX_LANDING_CONF, renderNginxConf("landing"));
-  writeFile(OTEL_AGENT_CONF, renderOtelAgentConfig(config));
+  writeFileMaybe(VERSIONS_LOCK, JSON.stringify(config.images, null, 2) + "\n");
+  writeFileMaybe(KEYCLOAK_REALM_FILE, renderKeycloakRealm(config, runtimeEnv));
+  writeFileMaybe(TRAEFIK_DYNAMIC_FILE, renderTraefikDynamicConfig(config));
+  writeFileMaybe(BOOTSTRAP_BASE_STACK_FILE, renderStack(config, runtimeEnv, "base"));
+  writeFileMaybe(BOOTSTRAP_STACK_FILE, renderStack(config, runtimeEnv, "bootstrap"));
+  writeFileMaybe(STACK_FILE, renderStack(config, runtimeEnv, "full"));
+  writeFileMaybe(NGINX_WEB_CONF, renderNginxConf("web"));
+  writeFileMaybe(NGINX_LANDING_CONF, renderNginxConf("landing"));
+  writeFileMaybe(OTEL_AGENT_CONF, renderOtelAgentConfig(config));
+  logSuccess(currentOptions.dryRun ? "Deploy artifacts previewed" : "Deploy artifacts written");
 }
 function saveDesiredConfig(config) {
   const internal = readInternalState();
   const generated = mergeGeneratedState(loadGeneratedEnv(), internal?.generated);
-  writeFile(DEPLOY_YAML, toYaml(config) + "\n");
-  writeFile(
+  logStep(`Saving desired config to ${DEPLOY_YAML}`);
+  writeFileMaybe(DEPLOY_YAML, toYaml(config) + "\n");
+  writeFileMaybe(
     INTERNAL_CONFIG_JSON,
     JSON.stringify({ config, generated }, null, 2) + "\n"
   );
+  logSuccess(currentOptions.dryRun ? "Desired config previewed" : "Desired config saved");
 }
 function ensureRepoCheckout(config) {
+  logStep(`Ensuring pinned repo checkout at ${config.source.ref}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would ensure repo checkout at ${REPO_ROOT}`);
+    return;
+  }
   ensureDir(REPO_ROOT);
   if (!exists(path.join(REPO_ROOT, ".git"))) {
+    logCommand("git", ["clone", config.source.repo_url, REPO_ROOT]);
     run("git", ["clone", config.source.repo_url, REPO_ROOT]);
   }
+  logCommand("git", ["remote", "set-url", "origin", config.source.repo_url]);
   run("git", ["remote", "set-url", "origin", config.source.repo_url], { cwd: REPO_ROOT });
+  logCommand("git", ["fetch", "--tags", "--force", "origin"]);
   run("git", ["fetch", "--tags", "--force", "origin"], { cwd: REPO_ROOT });
+  logCommand("git", ["checkout", "--force", config.source.ref]);
   run("git", ["checkout", "--force", config.source.ref], { cwd: REPO_ROOT });
+  logSuccess(`Pinned repo checkout ready at ${config.source.ref}`);
 }
 function extractStaticBundle(image, targetDir) {
+  logStep(`Extracting static bundle from ${image}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would extract ${image} into ${targetDir}`);
+    return;
+  }
   ensureDir(targetDir);
   const containerId = run("docker", ["create", image], { quiet: true }).trim();
   try {
@@ -829,17 +993,69 @@ function extractStaticBundle(image, targetDir) {
   } finally {
     run("docker", ["rm", "-f", containerId], { quiet: true });
   }
+  logSuccess(`Static bundle extracted to ${targetDir}`);
 }
 function buildKeycloakImage(imageTag, repoRoot = REPO_ROOT) {
   const buildContext = path.join(repoRoot, "packages/envsync-keycloak-theme");
   if (!exists(path.join(buildContext, "Dockerfile"))) {
     throw new Error(`Missing Keycloak Docker build context at ${buildContext}`);
   }
+  logStep(`Building Keycloak image ${imageTag}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would build ${imageTag} from ${buildContext}`);
+    return;
+  }
+  logCommand("docker", ["build", "-t", imageTag, buildContext]);
   run("docker", ["build", "-t", imageTag, buildContext]);
+  logSuccess(`Built Keycloak image ${imageTag}`);
 }
 function stackNetworkName(config) {
   return `${config.services.stack_name}_envsync`;
 }
+function assertSwarmManager() {
+  if (currentOptions.dryRun) {
+    logDryRun("Skipping Docker Swarm manager validation");
+    return;
+  }
+  logStep("Validating Docker Swarm manager state");
+  const state = tryRun("docker", ["info", "--format", "{{.Swarm.LocalNodeState}}|{{.Swarm.ControlAvailable}}"], { quiet: true }).trim();
+  if (state !== "active|true") {
+    throw new Error("Docker Swarm is not initialized on this node. Run 'docker swarm init' or 'envsync-deploy preinstall' first.");
+  }
+  logSuccess("Docker Swarm manager is ready");
+}
+function waitForCommand(config, label, image, command, timeoutSeconds = 120, env = {}, volumes = []) {
+  if (currentOptions.dryRun) {
+    logDryRun(`Would wait for ${label}`);
+    return;
+  }
+  logStep(`Waiting for ${label}`);
+  const deadline = Date.now() + timeoutSeconds * 1e3;
+  while (Date.now() < deadline) {
+    const args = ["run", "--rm", "--network", stackNetworkName(config)];
+    for (const volume of volumes) {
+      args.push("-v", volume);
+    }
+    for (const [key, value] of Object.entries(env)) {
+      args.push("-e", `${key}=${value}`);
+    }
+    args.push(image, "sh", "-lc", command);
+    if (commandSucceeds("docker", args)) {
+      logSuccess(`${label} is ready`);
+      return;
+    }
+    sleepSeconds(2);
+  }
+  throw new Error(`Timed out waiting for ${label}`);
+}
+function waitForPostgresService(config, label, host, user, password) {
+  waitForCommand(config, `${label} database readiness`, "postgres:17", `pg_isready -h ${host} -U ${user}`, 120, {
+    PGPASSWORD: password
+  });
+}
+function waitForRedisService(config) {
+  waitForCommand(config, "redis readiness", "redis:7", "redis-cli -h redis ping | grep PONG");
+}
 function waitForTcpService(config, label, host, port, timeoutSeconds = 120) {
   const deadline = Date.now() + timeoutSeconds * 1e3;
   while (Date.now() < deadline) {
@@ -853,7 +1069,104 @@ function waitForTcpService(config, label, host, port, timeoutSeconds = 120) {
   }
   throw new Error(`Timed out waiting for ${label} at ${host}:${port}`);
 }
+function waitForHttpService(config, label, url, timeoutSeconds = 120) {
+  waitForCommand(config, `${label} HTTP readiness`, "alpine:3.20", `wget -q -O /dev/null ${JSON.stringify(url)}`, timeoutSeconds);
+}
+function runOpenFgaMigrate(config, runtimeEnv) {
+  logStep("Running OpenFGA datastore migrations");
+  if (currentOptions.dryRun) {
+    logDryRun("Would run OpenFGA datastore migrations");
+    logCommand("docker", [
+      "run",
+      "--rm",
+      "--network",
+      stackNetworkName(config),
+      "-e",
+      "OPENFGA_DATASTORE_ENGINE=postgres",
+      "-e",
+      `OPENFGA_DATASTORE_URI=postgres://openfga:${runtimeEnv.OPENFGA_DB_PASSWORD}@openfga_db:5432/openfga?sslmode=disable`,
+      "openfga/openfga:v1.12.0",
+      "migrate"
+    ]);
+    return;
+  }
+  run("docker", [
+    "run",
+    "--rm",
+    "--network",
+    stackNetworkName(config),
+    "-e",
+    "OPENFGA_DATASTORE_ENGINE=postgres",
+    "-e",
+    `OPENFGA_DATASTORE_URI=postgres://openfga:${runtimeEnv.OPENFGA_DB_PASSWORD}@openfga_db:5432/openfga?sslmode=disable`,
+    "openfga/openfga:v1.12.0",
+    "migrate"
+  ]);
+  logSuccess("OpenFGA datastore migrations completed");
+}
+function runMiniKmsMigrate(config, runtimeEnv) {
+  logStep("Running miniKMS datastore migrations");
+  if (currentOptions.dryRun) {
+    logDryRun("Would run miniKMS datastore migrations");
+    logCommand("docker", [
+      "run",
+      "--rm",
+      "--network",
+      stackNetworkName(config),
+      "-e",
+      `PGPASSWORD=${runtimeEnv.MINIKMS_DB_PASSWORD}`,
+      "-v",
+      `${path.join(REPO_ROOT, "docker/minikms/migrations")}:/migrations:ro`,
+      "postgres:17",
+      "sh",
+      "-lc",
+      "psql -h minikms_db -U postgres -d minikms -f /migrations/001_initial_schema.sql && psql -h minikms_db -U postgres -d minikms -f /migrations/002_vault_storage.sql"
+    ]);
+    return;
+  }
+  run("docker", [
+    "run",
+    "--rm",
+    "--network",
+    stackNetworkName(config),
+    "-e",
+    `PGPASSWORD=${runtimeEnv.MINIKMS_DB_PASSWORD}`,
+    "-v",
+    `${path.join(REPO_ROOT, "docker/minikms/migrations")}:/migrations:ro`,
+    "postgres:17",
+    "sh",
+    "-lc",
+    "psql -h minikms_db -U postgres -d minikms -f /migrations/001_initial_schema.sql && psql -h minikms_db -U postgres -d minikms -f /migrations/002_vault_storage.sql"
+  ]);
+  logSuccess("miniKMS datastore migrations completed");
+}
 function runBootstrapInit(config) {
+  logStep("Running API bootstrap init");
+  if (currentOptions.dryRun) {
+    logDryRun("Would run API bootstrap init and persist generated OpenFGA IDs");
+    logCommand("docker", [
+      "run",
+      "--rm",
+      "--network",
+      stackNetworkName(config),
+      "--env-file",
+      DEPLOY_ENV,
+      "-e",
+      "SKIP_ROOT_ENV=1",
+      "-e",
+      "SKIP_ROOT_ENV_WRITE=1",
+      config.images.api,
+      "bun",
+      "run",
+      "scripts/prod-init.ts",
+      "--json",
+      "--no-write-root-env"
+    ]);
+    return {
+      openfgaStoreId: "",
+      openfgaModelId: ""
+    };
+  }
   const output = run(
     "docker",
     [
@@ -880,6 +1193,7 @@ function runBootstrapInit(config) {
   if (!result.openfgaStoreId || !result.openfgaModelId) {
     throw new Error("Bootstrap init did not return OpenFGA IDs");
   }
+  logSuccess("API bootstrap init completed");
   return {
     openfgaStoreId: result.openfgaStoreId,
     openfgaModelId: result.openfgaModelId
@@ -967,9 +1281,12 @@ async function cmdPreinstall() {
   run("bash", ["-lc", "curl -fsSL https://acme-v02.api.letsencrypt.org/directory >/dev/null"]);
 }
 async function cmdSetup() {
+  logSection("Setup");
   const rootDomain = await ask("Root domain", "example.com");
   const acmeEmail = await ask("ACME email", `admin@${rootDomain}`);
-  const channel = await ask("Release channel", "stable");
+  const releaseVersion = await ask("Release version", getDeployCliVersion());
+  assertSemverVersion(releaseVersion, "release version");
+  const releaseImages = versionedImages(releaseVersion);
   const adminUser = await ask("Keycloak admin user", "admin");
   const adminPassword = await ask("Keycloak admin password", randomSecret(12));
   const smtpHost = await ask("SMTP host", "smtp.example.com");
@@ -983,13 +1300,16 @@ async function cmdSetup() {
   const publicObs = await ask("Expose obs.<domain> publicly (true/false)", "true") === "true";
   const mailpitEnabled = await ask("Enable mailpit (true/false)", "false") === "true";
   const config = {
-    source: defaultSourceConfig(),
+    source: defaultSourceConfig(releaseVersion),
+    release: {
+      version: releaseVersion
+    },
     domain: { root_domain: rootDomain, acme_email: acmeEmail },
     images: {
-      api: `ghcr.io/envsync-cloud/envsync-api:${channel}`,
-      keycloak: `envsync-keycloak:${channel}`,
-      web: `ghcr.io/envsync-cloud/envsync-web-static:${channel}`,
-      landing: `ghcr.io/envsync-cloud/envsync-landing-static:${channel}`,
+      api: releaseImages.api,
+      keycloak: releaseImages.keycloak,
+      web: releaseImages.web,
+      landing: releaseImages.landing,
       clickstack: "clickhouse/clickstack-all-in-one:latest",
       traefik: "traefik:v3.1",
       otel_agent: "otel/opentelemetry-collector-contrib:0.111.0"
@@ -1034,29 +1354,59 @@ async function cmdSetup() {
       mailpit_enabled: mailpitEnabled,
       s3_public: true,
       s3_console_public: true
-    },
-    release_channel: channel
+    }
   };
   saveDesiredConfig(config);
-  console.log(`Config written to ${DEPLOY_YAML}`);
-  console.log(`Pinned source checkout: ${config.source.repo_url} @ ${config.source.ref}`);
-  console.log("Create these DNS records:");
+  logSuccess(`Config written to ${DEPLOY_YAML}`);
+  logInfo(`Pinned source checkout: ${config.source.repo_url} @ ${config.source.ref}`);
+  logInfo("Create these DNS records:");
   console.log(JSON.stringify(domainMap(rootDomain), null, 2));
 }
 async function cmdBootstrap() {
+  logSection("Bootstrap");
   const { config, generated } = loadState();
   const nextGenerated = ensureGeneratedRuntimeState(generated);
+  const runtimeEnv = buildRuntimeEnv(config, nextGenerated);
+  logInfo(`Release version: ${config.release.version}`);
+  assertSwarmManager();
   ensureRepoCheckout(config);
   writeDeployArtifacts(config, nextGenerated);
   buildKeycloakImage(config.images.keycloak);
-  run("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
-  waitForTcpService(config, "postgres", "postgres", 5432);
-  waitForTcpService(config, "redis", "redis", 6379);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would deploy base bootstrap stack for ${config.services.stack_name}`);
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+  } else {
+    logStep("Deploying base bootstrap stack");
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+    run("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+    logSuccess("Base bootstrap stack deployed");
+  }
+  waitForPostgresService(config, "postgres", "postgres", "postgres", "envsync-postgres");
+  waitForRedisService(config);
   waitForTcpService(config, "rustfs", "rustfs", 9e3);
-  waitForTcpService(config, "keycloak", "keycloak", 8080);
-  waitForTcpService(config, "openfga", "openfga", 8090);
+  waitForPostgresService(config, "keycloak", "keycloak_db", "keycloak", runtimeEnv.KEYCLOAK_ADMIN_PASSWORD);
+  waitForPostgresService(config, "openfga", "openfga_db", "openfga", runtimeEnv.OPENFGA_DB_PASSWORD);
+  waitForPostgresService(config, "minikms", "minikms_db", "postgres", runtimeEnv.MINIKMS_DB_PASSWORD);
+  runOpenFgaMigrate(config, runtimeEnv);
+  runMiniKmsMigrate(config, runtimeEnv);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would deploy runtime bootstrap stack for ${config.services.stack_name}`);
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
+  } else {
+    logStep("Deploying runtime bootstrap stack");
+    logCommand("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
+    run("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
+    logSuccess("Runtime bootstrap stack deployed");
+  }
+  waitForHttpService(config, "keycloak", "http://keycloak:8080/health/ready", 180);
+  waitForHttpService(config, "openfga", "http://openfga:8090/stores");
   waitForTcpService(config, "minikms", "minikms", 50051);
   const initResult = runBootstrapInit(config);
+  if (currentOptions.dryRun) {
+    logDryRun("Skipping generated OpenFGA ID persistence in preview mode");
+    logSuccess("Bootstrap dry-run completed");
+    return;
+  }
   const bootstrappedGenerated = normalizeGeneratedState({
     openfga: {
       store_id: initResult.openfgaStoreId,
@@ -1068,21 +1418,46 @@ async function cmdBootstrap() {
     }
   });
   writeDeployArtifacts(config, bootstrappedGenerated);
-  console.log("Bootstrap completed.");
+  logSuccess("Bootstrap completed");
 }
 async function cmdDeploy() {
+  logSection("Deploy");
   const { config, generated } = loadState();
+  logInfo(`Release version: ${config.release.version}`);
+  assertSwarmManager();
   assertBootstrapState(generated);
+  if (!currentOptions.dryRun) {
+    const services = listStackServices(config);
+    if (serviceHealth(services, `${config.services.stack_name}_keycloak`) === "missing" || serviceHealth(services, `${config.services.stack_name}_openfga`) === "missing" || serviceHealth(services, `${config.services.stack_name}_minikms`) === "missing") {
+      throw new Error("Bootstrap has not completed successfully. Run 'envsync-deploy bootstrap' again.");
+    }
+  } else {
+    logDryRun("Skipping runtime bootstrap service validation");
+  }
   ensureRepoCheckout(config);
   writeDeployArtifacts(config, generated);
   buildKeycloakImage(config.images.keycloak);
-  ensureDir(`${RELEASES_ROOT}/web/current`);
-  ensureDir(`${RELEASES_ROOT}/landing/current`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would ensure ${RELEASES_ROOT}/web/current exists`);
+    logDryRun(`Would ensure ${RELEASES_ROOT}/landing/current exists`);
+  } else {
+    ensureDir(`${RELEASES_ROOT}/web/current`);
+    ensureDir(`${RELEASES_ROOT}/landing/current`);
+  }
   extractStaticBundle(config.images.web, `${RELEASES_ROOT}/web/current`);
   extractStaticBundle(config.images.landing, `${RELEASES_ROOT}/landing/current`);
-  writeFile(`${RELEASES_ROOT}/web/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
-  writeFile(`${RELEASES_ROOT}/landing/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
+  writeFileMaybe(`${RELEASES_ROOT}/web/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
+  writeFileMaybe(`${RELEASES_ROOT}/landing/current/runtime-config.js`, renderFrontendRuntimeConfig(config));
+  if (currentOptions.dryRun) {
+    logDryRun(`Would deploy full stack for ${config.services.stack_name}`);
+    logCommand("docker", ["stack", "deploy", "-c", STACK_FILE, config.services.stack_name]);
+    logSuccess("Deploy dry-run completed");
+    return;
+  }
+  logStep("Deploying full stack");
+  logCommand("docker", ["stack", "deploy", "-c", STACK_FILE, config.services.stack_name]);
   run("docker", ["stack", "deploy", "-c", STACK_FILE, config.services.stack_name]);
+  logSuccess("Deploy completed");
 }
 async function cmdHealth(asJson) {
   const { config, generated } = loadState();
@@ -1123,17 +1498,28 @@ async function cmdHealth(asJson) {
   console.log(JSON.stringify(checks, null, 2));
 }
 async function cmdUpgrade() {
+  logSection("Upgrade");
   const { config } = loadState();
-  config.images.api = `ghcr.io/envsync-cloud/envsync-api:${config.release_channel}`;
+  config.images = {
+    ...config.images,
+    ...versionedImages(config.release.version)
+  };
   saveDesiredConfig(config);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would upgrade stack to release ${config.release.version}`);
+  }
   await cmdDeploy();
 }
 async function cmdUpgradeDeps() {
+  logSection("Upgrade Dependencies");
   const { config } = loadState();
   config.images.traefik = "traefik:v3.1";
   config.images.clickstack = "clickhouse/clickstack-all-in-one:latest";
   config.images.otel_agent = "otel/opentelemetry-collector-contrib:0.111.0";
   saveDesiredConfig(config);
+  if (currentOptions.dryRun) {
+    logDryRun("Would refresh dependency image tags and redeploy");
+  }
   await cmdDeploy();
 }
 function sha256File(filePath) {
@@ -1145,6 +1531,11 @@ function stackVolumeName(config, name) {
   return `${config.services.stack_name}_${name}`;
 }
 function backupDockerVolume(volumeName, targetDir) {
+  logStep(`Backing up Docker volume ${volumeName}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would back up ${volumeName} into ${targetDir}`);
+    return;
+  }
   ensureDir(targetDir);
   run("docker", [
     "run",
@@ -1158,8 +1549,14 @@ function backupDockerVolume(volumeName, targetDir) {
     "-lc",
     "cd /from && tar -czf /to/volume.tar.gz ."
   ]);
+  logSuccess(`Backed up Docker volume ${volumeName}`);
 }
 function restoreDockerVolume(volumeName, sourceDir) {
+  logStep(`Restoring Docker volume ${volumeName}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would restore ${volumeName} from ${sourceDir}`);
+    return;
+  }
   run("docker", ["volume", "create", volumeName], { quiet: true });
   run("docker", [
     "run",
@@ -1173,20 +1570,35 @@ function restoreDockerVolume(volumeName, sourceDir) {
     "-lc",
     "cd /to && tar -xzf /from/volume.tar.gz"
   ]);
+  logSuccess(`Restored Docker volume ${volumeName}`);
 }
 async function cmdBackup() {
+  logSection("Backup");
   const { config } = loadState();
-  ensureDir(config.backup.output_dir);
   const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:]/g, "-");
   const archiveBase = path.join(config.backup.output_dir, `envsync-backup-${timestamp}`);
   const manifestPath = `${archiveBase}.manifest.json`;
   const tarPath = `${archiveBase}.tar.gz`;
   const staged = path.join(BACKUPS_ROOT, `staging-${timestamp}`);
+  logInfo(`Backup archive target: ${tarPath}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would stage backup files in ${staged}`);
+    for (const volume of STACK_VOLUMES) {
+      backupDockerVolume(stackVolumeName(config, volume), path.join(staged, "volumes", volume));
+    }
+    logDryRun(`Would write manifest ${manifestPath}`);
+    logDryRun(`Would create archive ${tarPath}`);
+    logSuccess("Backup dry-run completed");
+    console.log(tarPath);
+    return;
+  }
+  ensureDir(config.backup.output_dir);
   ensureDir(staged);
   writeFile(path.join(staged, "deploy.env"), fs.readFileSync(DEPLOY_ENV, "utf8"));
   writeFile(path.join(staged, "deploy.yaml"), fs.readFileSync(DEPLOY_YAML, "utf8"));
   writeFile(path.join(staged, "config.json"), fs.readFileSync(INTERNAL_CONFIG_JSON, "utf8"));
   writeFile(path.join(staged, "versions.lock.json"), fs.readFileSync(VERSIONS_LOCK, "utf8"));
+  writeFile(path.join(staged, "docker-stack.bootstrap.base.yaml"), fs.readFileSync(BOOTSTRAP_BASE_STACK_FILE, "utf8"));
   writeFile(path.join(staged, "docker-stack.bootstrap.yaml"), fs.readFileSync(BOOTSTRAP_STACK_FILE, "utf8"));
   writeFile(path.join(staged, "docker-stack.yaml"), fs.readFileSync(STACK_FILE, "utf8"));
   writeFile(path.join(staged, "traefik-dynamic.yaml"), fs.readFileSync(TRAEFIK_DYNAMIC_FILE, "utf8"));
@@ -1205,17 +1617,28 @@ async function cmdBackup() {
     volumes: STACK_VOLUMES.map((volume) => stackVolumeName(config, volume))
   };
   writeFile(manifestPath, JSON.stringify(manifest, null, 2) + "\n");
+  logSuccess("Backup completed");
   console.log(tarPath);
 }
 async function cmdRestore(archivePath) {
   if (!archivePath) throw new Error("restore requires a .tar.gz path");
+  logSection("Restore");
   const restoreRoot = path.join(BACKUPS_ROOT, `restore-${Date.now()}`);
+  logInfo(`Restore archive: ${archivePath}`);
+  if (currentOptions.dryRun) {
+    logDryRun(`Would extract ${archivePath} into ${restoreRoot}`);
+    logDryRun(`Would restore deploy files into ${DEPLOY_ROOT} and ${ETC_ROOT}`);
+    logDryRun("Would restore all managed Docker volumes from the archive");
+    logSuccess("Restore dry-run completed");
+    return;
+  }
   ensureDir(restoreRoot);
   run("bash", ["-lc", `tar -xzf ${JSON.stringify(archivePath)} -C ${JSON.stringify(restoreRoot)}`]);
   writeFile(DEPLOY_ENV, fs.readFileSync(path.join(restoreRoot, "deploy.env"), "utf8"), 384);
   writeFile(DEPLOY_YAML, fs.readFileSync(path.join(restoreRoot, "deploy.yaml"), "utf8"));
   writeFile(INTERNAL_CONFIG_JSON, fs.readFileSync(path.join(restoreRoot, "config.json"), "utf8"));
   writeFile(VERSIONS_LOCK, fs.readFileSync(path.join(restoreRoot, "versions.lock.json"), "utf8"));
+  writeFile(BOOTSTRAP_BASE_STACK_FILE, fs.readFileSync(path.join(restoreRoot, "docker-stack.bootstrap.base.yaml"), "utf8"));
   writeFile(BOOTSTRAP_STACK_FILE, fs.readFileSync(path.join(restoreRoot, "docker-stack.bootstrap.yaml"), "utf8"));
   writeFile(STACK_FILE, fs.readFileSync(path.join(restoreRoot, "docker-stack.yaml"), "utf8"));
   writeFile(TRAEFIK_DYNAMIC_FILE, fs.readFileSync(path.join(restoreRoot, "traefik-dynamic.yaml"), "utf8"));
@@ -1225,11 +1648,16 @@ async function cmdRestore(archivePath) {
   for (const volume of STACK_VOLUMES) {
     restoreDockerVolume(stackVolumeName(config, volume), path.join(restoreRoot, "volumes", volume));
   }
-  console.log("Restore completed. Run 'envsync-deploy deploy' to start services.");
+  logSuccess("Restore completed. Run 'envsync-deploy deploy' to start services.");
 }
 async function main() {
-  const command = process.argv[2];
-  const flag = process.argv[3];
+  const argv = process.argv.slice(2);
+  const command = argv[0];
+  const args = argv.slice(1);
+  currentOptions = {
+    dryRun: args.includes("--dry-run")
+  };
+  const positionals = args.filter((arg) => arg !== "--dry-run");
   switch (command) {
     case "preinstall":
       await cmdPreinstall();
@@ -1244,7 +1672,7 @@ async function main() {
       await cmdDeploy();
       break;
     case "health":
-      await cmdHealth(flag === "--json");
+      await cmdHealth(positionals[0] === "--json");
       break;
     case "upgrade":
       await cmdUpgrade();
@@ -1256,10 +1684,12 @@ async function main() {
       await cmdBackup();
       break;
     case "restore":
-      await cmdRestore(flag ?? "");
+      await cmdRestore(positionals[0] ?? "");
       break;
     default:
-      console.log("Usage: envsync-deploy <preinstall|setup|bootstrap|deploy|health|upgrade|upgrade-deps|backup|restore>");
+      console.log(
+        "Usage: envsync-deploy <preinstall|setup|bootstrap|deploy|health|upgrade|upgrade-deps|backup|restore> [--dry-run]"
+      );
       process.exit(command ? 1 : 0);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envsync-cloud/deploy-cli",
-  "version": "0.6.2",
+  "version": "0.6.4",
   "description": "CLI for self-hosted EnvSync deployment on Docker Swarm",
   "type": "module",
   "bin": {
@@ -39,6 +39,9 @@
     "cli",
     "secrets"
   ],
+  "dependencies": {
+    "chalk": "^5.6.2"
+  },
   "devDependencies": {
     "tsup": "^8.5.0",
     "typescript": "^5.9.2"