Workspace setup

To work with Ionize source, patch a bug, add a feature, run a forked version, you need a workspace with the eight repos cloned side-by-side. This page sets that up.

Prerequisites

• Git with SSH or HTTPS access to github.com/bnannier/*.
• Node.js 20+ with npm.
• Bun, curl -fsSL https://bun.sh/install | bash.
• Podman + podman-compose (or Docker + Docker Compose, podman-compose is recommended).
• macOS: Homebrew; ionctl deploy will install missing tooling for you.
• Linux: install Podman via your package manager.

Clone the eight repos

The dev compose.dev.yml uses relative volume mounts (../dashboard, ../auth, ../site) for live reload, so the repos must be siblings of one parent directory:

mkdir Ionize && cd Ionize
for repo in platform dashboard auth site canvas sdk ionctl deploy; do
  git clone git@github.com:bnannier/$repo.git
done

Your layout:

Ionize/
├── platform/
├── dashboard/
├── auth/
├── site/
├── canvas/
├── sdk/
├── ionctl/
└── deploy/

This sibling layout is required, not advisory. If you have a different layout, the volume mounts in compose.dev.yml won't find the source.

Install dependencies in each app repo

for repo in dashboard auth site canvas sdk ionctl; do
  cd Ionize/$repo
  bun install
  cd ..
done

canvas and sdk ship as source-only npm packages. The dev install resolves them via bun's standard package resolution, when Dashboard's package.json declares @nannier/canvas, Bun reads it from the canvas/ sibling directory only when you use a workspace setup. The current Ionize setup is not a Bun monorepo workspace; each app reaches Canvas via the published npm package.

For local dev where you want to edit Canvas and see changes in Dashboard instantly, link manually:

cd Ionize/canvas && bun link
cd ../dashboard && bun link @nannier/canvas

Repeat for the SDK if you're editing it.

Start the stack

Easiest:

npx @nannier/ionctl deploy

Or manually:

cd Ionize/platform/dev
podman compose up -d

See Get Started, Quickstart with podman compose for what each command does and where to look when it fails.

Run a single app outside Compose

For faster iteration on, say, Dashboard:

cd Ionize/dashboard
DATABASE_URL=postgres://dashboard:dashboard@localhost:5432/ionize \
ENCRYPTION_KEY=$(cat ../platform/dev/.env.dev | grep ENCRYPTION_KEY | cut -d= -f2) \
SESSION_SIGNING_KEY=$(cat ../platform/dev/.env.dev | grep SESSION_SIGNING_KEY | cut -d= -f2) \
KRATOS_URL=http://localhost:4101 \
HYDRA_URL=http://localhost:4103 \
bun run dev

You'll need to bring up Postgres separately or have the Compose stack running for the DB. The other Ionize services should be running so Dashboard can talk to them.

Editor setup

• VS Code: open the parent Ionize/ directory as a multi-root workspace. Add a .code-workspace file listing each repo as a folder. TypeScript should "Just Work", each repo has its own tsconfig.json.
• JetBrains: same; open the parent directory as a project, mark each repo as a content root.

Per-repo scripts

Most repos share:

bun run dev          # start dev server
bun run typecheck    # tsc --noEmit
bun run lint         # biome check (dashboard, auth, site)
bun run test         # vitest run
bun run build        # production build

Refer to each repo's package.json for variations.

Inspecting your running deployment

Once you have local source, you can also exec into containers to compare your source against what's actually running:

podman exec ionize-ciam-dashboard-1 cat /app/src/middleware.ts | diff - dashboard/src/middleware.ts

See Develop, Inspecting your containers for the full inspection workflow.

Common setup pitfalls

• Sibling layout missed. If you cloned the repos to ~/projects/<each>/ rather than ~/projects/Ionize/<each>/, the volume mounts fail. Move them into a common parent.
• bun install skipped in one repo. Compose builds the dev image fresh from the volume mount, but if your app expects a built node_modules from the host, install before starting the stack.
• Podman machine not started (macOS). podman machine init && podman machine start first.

Where next

• Develop, Running tests, per-repo test runners.
• Develop, Testing strategy, Vitest + Playwright patterns.
• Develop, Release process, Changesets + GHCR.