@envsync-cloud/deploy-cli 0.6.2 → 0.6.3

package/README.md

@@ -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:

package/dist/index.js

@@ -17,6 +17,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 +46,7 @@ var REQUIRED_BOOTSTRAP_ENV_KEYS = [
   "OPENFGA_STORE_ID",
   "OPENFGA_MODEL_ID"
 ];
+var SEMVER_VERSION_RE = /^\d+\.\d+\.\d+$/;
 function run(cmd, args, opts = {}) {
   const result = spawnSync(cmd, args, {
     cwd: opts.cwd,
@@ -203,16 +205,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 +656,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 +752,7 @@ ${renderEnvList({
     volumes:
       - keycloak_db_data:/var/lib/postgresql/data
     networks: [envsync]
-
+${includeRuntimeInfra ? `
   keycloak:
     image: ${config.images.keycloak}
     entrypoint: ["/bin/sh", "-lc"]
@@ -671,7 +779,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 +792,7 @@ ${renderEnvList({
     volumes:
       - openfga_db_data:/var/lib/postgresql/data
     networks: [envsync]
-
+${includeRuntimeInfra ? `
   openfga:
     image: openfga/openfga:v1.12.0
     command: run
@@ -695,7 +803,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 +816,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 +827,7 @@ ${renderEnvList({
     MINIKMS_GRPC_ADDR: "0.0.0.0:50051",
     MINIKMS_TLS_ENABLED: "false"
   })}
-    networks: [envsync]
+    networks: [envsync]` : ""}
 
   clickstack:
     image: ${config.images.clickstack}
@@ -797,8 +905,9 @@ function writeDeployArtifacts(config, generated) {
   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(BOOTSTRAP_BASE_STACK_FILE, renderStack(config, runtimeEnv, "base"));
+  writeFile(BOOTSTRAP_STACK_FILE, renderStack(config, runtimeEnv, "bootstrap"));
+  writeFile(STACK_FILE, renderStack(config, runtimeEnv, "full"));
   writeFile(NGINX_WEB_CONF, renderNginxConf("web"));
   writeFile(NGINX_LANDING_CONF, renderNginxConf("landing"));
   writeFile(OTEL_AGENT_CONF, renderOtelAgentConfig(config));
@@ -840,6 +949,38 @@ function buildKeycloakImage(imageTag, repoRoot = REPO_ROOT) {
 function stackNetworkName(config) {
   return `${config.services.stack_name}_envsync`;
 }
+function assertSwarmManager() {
+  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.");
+  }
+}
+function waitForCommand(config, label, image, command, timeoutSeconds = 120, env = {}, volumes = []) {
+  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)) {
+      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,6 +994,39 @@ 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) {
+  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"
+  ]);
+}
+function runMiniKmsMigrate(config, runtimeEnv) {
+  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"
+  ]);
+}
 function runBootstrapInit(config) {
   const output = run(
     "docker",
@@ -969,7 +1143,9 @@ async function cmdPreinstall() {
 async function cmdSetup() {
   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 +1159,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,8 +1213,7 @@ 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}`);
@@ -1046,15 +1224,23 @@ async function cmdSetup() {
 async function cmdBootstrap() {
   const { config, generated } = loadState();
   const nextGenerated = ensureGeneratedRuntimeState(generated);
+  const runtimeEnv = buildRuntimeEnv(config, nextGenerated);
+  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);
+  run("docker", ["stack", "deploy", "-c", BOOTSTRAP_BASE_STACK_FILE, config.services.stack_name]);
+  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);
+  run("docker", ["stack", "deploy", "-c", BOOTSTRAP_STACK_FILE, config.services.stack_name]);
+  waitForHttpService(config, "keycloak", "http://keycloak:8080/realms/master");
+  waitForHttpService(config, "openfga", "http://openfga:8090/stores");
   waitForTcpService(config, "minikms", "minikms", 50051);
   const initResult = runBootstrapInit(config);
   const bootstrappedGenerated = normalizeGeneratedState({
@@ -1072,7 +1258,12 @@ async function cmdBootstrap() {
 }
 async function cmdDeploy() {
   const { config, generated } = loadState();
+  assertSwarmManager();
   assertBootstrapState(generated);
+  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.");
+  }
   ensureRepoCheckout(config);
   writeDeployArtifacts(config, generated);
   buildKeycloakImage(config.images.keycloak);
@@ -1124,7 +1315,10 @@ async function cmdHealth(asJson) {
 }
 async function cmdUpgrade() {
   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);
   await cmdDeploy();
 }
@@ -1187,6 +1381,7 @@ async function cmdBackup() {
   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"));
@@ -1216,6 +1411,7 @@ async function cmdRestore(archivePath) {
   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"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@envsync-cloud/deploy-cli",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "CLI for self-hosted EnvSync deployment on Docker Swarm",
   "type": "module",
   "bin": {