Documentation

# Linux x86_64 — download v0.8.1 from GitHub releases
curl -LO https://github.com/supanadit/ezx/releases/download/0.8.1/ezx-0.8.1-linux-amd64
mv ezx-0.8.1-linux-amd64 ezx
chmod +x ezx

# or build from the repo root
go build -o ezx ./app

// entrypoint.js
const { env, chain, log } = require("ezx");

chain.run({
  nodes: [
    {
      name: "app",
      process: {
        binaryPath: "/bin/sh",
        arguments: ["-c", "echo 'GREETING='$GREETING"],
        environment: ["GREETING=Hello from ezx"],
        filterEnv: ["PHP_MEMORY_LIMIT"],
      },
    },
    {
      name: "sidecar",
      dependsOn: ["app"],
      needParentReady: true,
      process: { binaryPath: "/bin/sh", arguments: ["-c", "echo sidecar ready"] },
    },
  ],
});

log.info("entrypoint complete");

./ezx bootstrap entrypoint.js

const { chain } = require("ezx");

chain.run({
  nodes: [
    { name: "postgres", process: { binaryPath: "postgres", arguments: ["-D", "/var/lib/postgresql/data"] } },
    {
      name: "pgbouncer",
      dependsOn: ["postgres"],
      needParentReady: true,   // waits until postgres readiness passes
      process: { binaryPath: "pgbouncer", arguments: ["/etc/pgbouncer/pgbouncer.ini"] },
      restart: { mode: "always", backoff: 2e9 },
    },
  ],
});

const { chain } = require("ezx");

const PGDATA = "/var/lib/postgresql/data";

chain.run({
  nodes: [
    {
      name: "initdb",
      oneshot: true,
      process: { binaryPath: "/usr/local/bin/initdb", arguments: ["--username=postgres", "--pwfile=/tmp/ezx-pwfile", PGDATA], user: "postgres", group: "postgres" },
    },
    {
      name: "stanza-create",
      oneshot: true,
      dependsOn: ["initdb"],
      process: { binaryPath: "/usr/bin/pgbackrest", arguments: ["stanza-create", "--stanza=main", "--pg1-path=" + PGDATA] },
    },
    {
      name: "postgres",
      exec: true,
      dependsOn: ["initdb", "stanza-create"],
      process: { binaryPath: "/usr/local/bin/postgres", arguments: ["-D", PGDATA], user: "postgres", group: "postgres" },
    },
  ],
});

process: {
  binaryPath: "/usr/bin/pgbouncer",
  arguments: ["/etc/pgbouncer/pgbouncer.ini"],
  log: {
    stdout: "file",                 // route stdout to a rotating file
    filePath: "/var/log/ezx/pgbouncer.log",
    maxBytes: 5 * 1024 * 1024,      // rotate at 5 MiB (default 10 MiB)
    maxBackups: 2,                  // keep .log + .1 + .2 (default 3)
    stderr: "stderr",               // stderr still goes to container stderr
  },
},

readiness: { type: "exec",  exec: ["pg_isready", "-h", "/run/postgresql"], interval: 1e9, timeout: 5e9, maxAttempts: 30 }
readiness: { type: "tcp",   tcp: { host: "127.0.0.1", port: 5432 } }
readiness: { type: "http",  http: { url: "http://127.0.0.1:8008/master", expectStatus: 200 } }

// execExpect: exit code 0 is not enough — the output must match too.
readiness: {
  type: "exec",
  exec: ["psql", "-c", "select pg_is_in_recovery()"],
  execExpect: "f",   // only the primary is "ready"
}

// POSTGRESQL_CONFIG_LOG_DESTINATION=stderr
// becomes log_destination = 'stderr' in postgresql.conf
const { chain } = require("ezx");

chain.run({
  nodes: [{
    name: "postgres",
    files: [{
      path: "/etc/postgresql/postgresql.conf",
      operations: [{
        type: "set-property",
        fromEnvPattern: "^POSTGRESQL_CONFIG_(.+)$",
        nameTransform: "lower",
        pattern: "^\\s*#?\\s*${name}\\s*=.*",
        value: "${name} = ${value}",
        valueFormat: "auto",
      }],
    }],
    // files are provisioned before the process starts
    process: {
      binaryPath: "postgres",
      arguments: ["-D", "/var/lib/postgresql/data"],
    },
  }],
});

// PROMETHEUS_ENABLE_WEB_LIFECYCLE=true
// THANOS_QUERY_STORE_ADDRESSES=store1:10901,store2:10901
// becomes: --web.enable-lifecycle --endpoint=store1:10901 --endpoint=store2:10901
const { chain } = require("ezx");

chain.run({
  nodes: [{
    name: "thanos",
    process: {
      binaryPath: "thanos",
      argOperations: [
        { when: { name: "PROMETHEUS_ENABLE_WEB_LIFECYCLE", value: "true" }, flag: "--web.enable-lifecycle", format: "bare-flag" },
        { flag: "--endpoint", fromEnv: "THANOS_QUERY_STORE_ADDRESSES", split: "," },
      ],
    },
  }],
});

const { config } = require("ezx");

// 1. Flat key=value (postgresql.conf) — auto value formatting
const postgresql = config.build({
  comment: "PostgreSQL configuration generated by container",
  separator: " = ",
  valueFormat: "auto",
  properties: [["listen_addresses", "*"], ["port", 5432], ["shared_buffers", "256MB"]],
});

// 2. Table/matrix (pg_hba.conf) — column-aligned rows
const pgHba = config.build({
  rows: [["local", "all", "postgres", "trust"], ["host", "all", "all", "0.0.0.0/0", "md5"]],
});

// 3. INI sections (pgbackrest.conf)
const pgbackrest = config.build({
  separator: "=",
  sections: { global: { "log-level-console": "info" }, default: { "pg1-port": 5432 } },
});

const b = config.builder({ separator: "=", valueFormat: "none" });
const srv = b.section("server");
srv.set("port", 8080);
srv.setIf("host", env.get("HOST", "")); // skipped when empty
srv.setFlag("tls", true);               // tls=y (skipped when false)

const { yaml } = require("ezx");
const doc = yaml.build({
  scope: "postgres-cluster",
  postgresql: { listen: "0.0.0.0:5432", parameters: { hot_standby: "on" } },
});
// scope: postgres-cluster
// postgresql:
//   listen: 0.0.0.0:5432
//   parameters:
//     hot_standby: "on"

const { process, log } = require("ezx");

// One-shot with inherited output; blocks until exit, returns the code.
const code = process.run({ name: "init", process: { binaryPath: "/bin/sh", arguments: ["-c", "echo hi"] } });

// Capture output; check: true throws on non-zero exit.
const { stdout } = process.capture({
  process: { binaryPath: "pg_ctl", arguments: ["status"] },
  check: true,
});

// Long-running spawn returns a handle.
const h = process.spawn({ name: "app", process: { binaryPath: "/bin/app" } });
h.start([]);                // start (idempotent); env array appended after inherited
log.info("pid=%d", h.pid());
h.wait();                   // blocks → exit code
h.signal("SIGTERM");        // TERM | INT | KILL | QUIT | HUP only

// Run initdb as the postgres user, like the official entrypoint.
process.run({
  name: "initdb",
  process: {
    binaryPath: "initdb",
    arguments: ["-D", PGDATA],
    user: "postgres",           // name or numeric UID
    group: "postgres",          // optional; default = user's primary group
  },
  check: true,
});

const { chain, scheduler } = require("ezx");

chain.run({
  nodes: [
    { name: "postgres", process: { binaryPath: "postgres", arguments: ["-D", "/var/lib/postgresql/data"] } },
    {
      name: "hourly-backup",
      dependsOn: ["postgres"],
      needParentReady: true,
      process: { binaryPath: "pgbackrest", arguments: ["--config=/etc/pgbackrest.conf", "backup"] },
      scheduler: scheduler.build({
        schedule: { expression: "0 * * * *", timezone: "UTC" },
        minInterval: 60e9,   // dedupe: never run twice within 60s
        gate: { type: "exec", exec: ["pg_isready", "-h", "/run/postgresql"] },
      }),
    },
  ],
});

const { api, scheduler, health, chain } = require("ezx");

// Flip readiness from script logic (drives /readyz and /healthz).
health.setReady(true);

// Register api routes BEFORE chain.run — the script blocks inside chain.run,
// so anything after it never executes. Handlers return plain values (JSON).
api.post("/backup/full", () => { scheduler.trigger("hourly-backup"); return { ok: true }; });
api.get("/backup/status", () => scheduler.status("hourly-backup"));

// Per-node readiness: /readyz reports ready only while the probe passes.
chain.run({
  nodes: [{
    name: "app",
    process: { binaryPath: "/bin/app" },
    health: { readyProbe: { type: "http", http: { url: "http://127.0.0.1:3000/healthz" } } },
  }],
});

chain.run({
  nodes: [
    { name: "postgresql", process: { binaryPath: "/bin/sh", arguments: ["-c", "start-postgres"] } },
    { name: "etcd",       dependsOn: ["postgresql"], process: { binaryPath: "etcd" } },
    { name: "pgbouncer",  dependsOn: ["postgresql"], needParentReady: true,
      process: { binaryPath: "pgbouncer", arguments: ["/etc/pgbouncer/pgbouncer.ini"] } },
    { name: "pgpool",     dependsOn: ["pgbouncer"], needParentReady: true, process: { binaryPath: "pgpool" } },
  ],
});

chain.run({
  nodes: [{
    name: "pgbackrest",
    process: {
      binaryPath: "pgbackrest",
      arguments: ["--config=/etc/pgbackrest.conf", "backup"],
      filterEnvPattern: ["^PGBACKREST_"],   // strip consumed secrets before spawn
      environment: ["KEEP=kept"],           // additive entries survive filtering
    },
  }],
});

const { api, scheduler } = require("ezx");

// Only tick while this node is the primary (http gate).
node.scheduler = scheduler.build({
  schedule: { expression: "0 2 * * *", timezone: "UTC" },
  initialDelay: 120e9,
  gate: { type: "http", http: { url: "http://localhost:8008/master" } },
});

// in a real script, register api routes BEFORE chain.run
api.post("/backup/full", () => { scheduler.trigger("backup-full"); return { ok: true }; });
api.get("/backup/status", () => scheduler.status("backup-full"));

const { chain } = require("ezx");

const PGDATA = "/var/lib/postgresql/data";

chain.run({
  nodes: [
    {
      name: "initdb",
      oneshot: true,
      process: { binaryPath: "/usr/local/bin/initdb", arguments: ["--username=postgres", "--pwfile=/tmp/ezx-pwfile", PGDATA], user: "postgres", group: "postgres" },
    },
    {
      name: "pg-hba",
      oneshot: true,
      dependsOn: ["initdb"],
      process: { binaryPath: "/bin/sh", arguments: ["-c", "echo 'local all all trust' >> " + PGDATA + "/pg_hba.conf"] },
    },
    {
      name: "postgres",
      exec: true,
      dependsOn: ["initdb", "pg-hba"],
      process: { binaryPath: "/usr/local/bin/postgres", arguments: ["-D", PGDATA], user: "postgres", group: "postgres" },
    },
  ],
});
// the exec node never returns — postgres is now PID 1 with native signal handling

const { yaml, editor } = require("ezx");
const patroni = yaml.build({
  scope: "postgres-cluster",
  postgresql: { listen: "0.0.0.0:5432", parameters: { hot_standby: "on" } },
});
editor.open("/etc/patroni/patroni.yml").replace(patroni);