0025, Octl bundles a stack/ directory

Status: Accepted Date: 2026-03 Stakeholders: Bobby Nannier

Context

ionctl deploy starts the full local Ionize stack. It needs compose.dev.yml, Kratos and Hydra configs, identity schemas, init-db.sql, seed scripts.

Two options for sourcing these:

• Reference the platform repo. Octl clones or downloads from GitHub. Always current, requires network.
• Bundle into ionctl's npm package. Ship a stack/ directory inside @nannier/ionctl. Single source.

Decision

Bundle. ionctl's npm package includes a stack/ directory with the canonical dev configs.

Consequences

• npx @nannier/ionctl deploy works from any empty directory. No git clone platform required first.
• Bundle size. Octl's package is larger (~500KB) than it would be otherwise. Acceptable.
• Stack updates are ionctl releases. When platform/dev config changes, the bundle in ionctl needs a corresponding update. CI synchronizes via a pre-release script that copies the latest configs from a pinned platform commit.
• Bundle drift risk. If ionctl's bundled configs and the live platform repo diverge, dev environments may not match what's deployed via Deploy. Tested by CI but worth periodic audit.

Related

• Get Started, Quickstart with ionctl
• Internals, Octl stack bundle