Tutorial: set up the starter

The starter runs IdentityFlow locally with its sign-in service and PostgreSQL, ready for a browser request.

The tutorial uses the starter, the example project delivered with IdentityFlow. On this page you install it, check it, and start it once. After setup, continue to run a vacation approval.

IdentityFlow is provided to customers directly. If you don’t have the starter project and the IdentityFlow program yet, write to contact@kenoxa.de.

Tutorial setup

Prerequisites

• macOS on Apple Silicon (macOS 13.5 or later) or Linux x64. On Windows, use the Linux files inside WSL2.
• Node.js 26.8.1, exactly, with the npm it ships with. The starter’s checks accept no other version. Setup does not install Node.js; get it from nodejs.org/dist/v26.8.1.
• Docker with Compose v2, running: Docker Desktop or OrbStack on macOS, Docker Engine or Docker Desktop on Linux.
• mkcert, with its local certificate authority installed once. The starter’s sign-in service answers only over HTTPS, and mkcert makes your browser and Node.js trust its certificate. On Debian or Ubuntu, install the packages mkcert and libnss3-tools first.
• On Linux, the tools unzip, file, tar and sha256sum.

mkcert -install

You do not need your own PostgreSQL. The starter runs PostgreSQL 18.6 in Docker, and every Workflow Test run starts its own database container.

Windows with WSL2: files, Docker and certificate trust

On WSL2, keep the project in the WSL file system, such as ~/identity-flow-workshop-v0.3.1, not under /mnt/c, and enable Docker Desktop’s WSL2 integration for your distribution. Your browser runs on Windows, so it has to trust the mkcert certificate as well; the WSL2 section of the starter’s README.md shows the two commands.

On WSL2, your browser saves downloads in the Windows Downloads folder, which is not ~/Downloads inside WSL. Copy the delivered archive there first, with your Windows user name in place of YourWindowsUser:

mkdir -p ~/Downloads
cp /mnt/c/Users/YourWindowsUser/Downloads/identity-flow-* ~/Downloads/

Install and verify the release

Unpack the archive into your home folder and change into the starter project. Leave the program and Workflow Test archives where they are, next to the project; the setup script installs them:

unzip ~/Downloads/identity-flow-workshop-v0.3.1.zip -d ~
cd ~/identity-flow-workshop-v0.3.1/identity-flow-workshop-starter-v0.3.1

Run the setup script for your platform from that folder. On macOS:

bash setup-macos.sh

On Linux and WSL2:

bash setup-linux.sh

The script prints a table with each prerequisite, what it detected, and whether that is enough. Then it:

1. finds the program and Workflow Test distribution archives in the project folder, the folder above it, or ~/Downloads, and installs them into bin/;
2. on macOS, asks before it removes the download quarantine from bin/. Answer with Enter or yes;
3. runs npm ci, which installs exactly the package versions package-lock.json records;
4. runs npm run workshop:verify, which checks this machine and this project.

When setup reaches verification, its last line is npm run workshop:verify: PASS or npm run workshop:verify: FAIL. If a prerequisite is missing, it stops earlier. Either way, a failure comes with a STOP: line that names the reason and a Fix: line with the next action. Fix that one item and run the same setup command again. The full output is in .runtime/setup-install.log and .runtime/setup-verify.log. If IFLOW_DISTRIBUTION_MISSING remains after setup, send the setup output and .runtime/setup-install.log to contact@kenoxa.de.

First verification

On a machine that has never started the starter, verification stops at IFLOW_IMAGE_MISSING, IFLOW_WORKSHOP_NOT_STARTED or IFLOW_FIXTURES_NOT_RUNNING, because the starter’s containers are not there yet. Start the starter in the background, then verify again:

npm run workshop:start -- --background
npm run workshop:verify

workshop:start downloads the two container images it needs if they are missing, which needs network access. It starts PostgreSQL and the local sign-in service in Docker, then the IdentityFlow program from bin/, and returns once IdentityFlow answers. It prints the program’s process ID, the address http://127.0.0.1:4173, the log file, and the command that stops it.

workshop:start runs PostgreSQL and the HTTPS sign-in service in Docker, and the IdentityFlow program from bin/ on your machine.

workshop:verify prints one workshop: ok line per check and ends with workshop: workshop:verify passed. It checks, in this order:

• Node.js is 26.8.1; Docker and Compose v2 answer; the mkcert certificate authority exists;
• the two container images match images.lock.json;
• the project files are complete, and the configuration contains no literal secret;
• the sign-in configuration routes to the provider acme;
• every test pattern in vitest.config.ts selects at least one file;
• the program and the Workflow Test distribution in bin/ both report 0.3.1 and the same source commit;
• the installed @identity-flow/* packages are 0.3.1;
• PostgreSQL 18.6 and the sign-in service are running.

When the containers are stopped on purpose, npm run workshop:verify -- --tools-only skips the last check.

First run

Open http://127.0.0.1:4173/auth/login in your browser. The page IdentityFlow workshop sign in has one button per prepared account, such as Continue as requester and Continue as vacation-manager. Each button also says what the account is and which division it belongs to. Choose Continue as requester.

IdentityFlow shows only the areas this account can reach. On an empty database, requester sees Assigned to me, My work, Workflow catalog and My access; Instances appears once there is an instance the account may see. The Workflow catalog lists Vacation approval and Multi-role approval. If you see both, the setup works.

Stop the starter before you continue. The next page starts it again in the foreground:

npm run workshop:stop

workshop:stop stops IdentityFlow and the containers and keeps the database.

Recovery

When a command fails, save its output before you run anything else. Every starter command reports a failure as one line workshop: <diagnostic>: <message>, such as workshop: IFLOW_NODE_VERSION_MISMATCH: …, usually followed by workshop: hint: <next action>. The section Diagnostics in the starter’s README.md lists every code.

Then check, in this order: Node.js, Docker and mkcert; the two programs in bin/ and the installed packages; the running containers. npm run workshop:verify checks all three and stops at the first problem. When you ask for help, include its output.

• npm run workshop:status shows whether IdentityFlow is running, with its address and log file. npm run workshop:logs prints the program output of the current run.
• npm run workshop:stop -- --volumes deletes the starter’s database. Use it only when you want to start from an empty database. docker compose down in the project folder does not reach the starter’s containers.
• A restart replays the recorded events; it does not change them.

After fixing the cause, run npm run workshop:verify again before you continue.

Files in the customer download

What you receive

For the tutorial you receive one archive, identity-flow-workshop-v0.3.1.zip. It unpacks into the folder identity-flow-workshop-v0.3.1/, which holds:

File	What it is
identity-flow-workshop-starter-v0.3.1/	The starter project.
identity-flow-v0.3.1-<target>	The IdentityFlow program, one executable. For macOS, a .zip.
identity-flow-test-v0.3.1-<target>	The Workflow Test distribution, the test runner, as an archive.
README.md, CHANGELOG.md	A short setup guide and the release notes.

<target> is macos-arm64 or linux-x64; the archive holds both. Install and run IdentityFlow describes the files for a server.

The starter contains, among others:

• src/workflows/vacation-approval.workflow.ts and src/workflows/multi-role-approval.workflow.ts, the two Workflow Definitions the tutorial uses;
• src/hooks/acme.hooks.ts, which registers the provider acme, the identity hook that tells IdentityFlow what each signed-in account is;
• fixtures/, the prepared test data: invented people, roles and directory entries that acme and the workflows’ bindings read. No real system is involved, and the project contains no credentials;
• tests/workflows/, the Workflow Tests;
• exercises/, 21 practice tasks, each with a task, a start state and a solution;
• config/identity-flow.workshop.conf and authorization.ts, the configuration and the access rules IdentityFlow starts with;
• README.md, the starter’s own reference, including every diagnostic code its commands print.

The starter’s commands are npm scripts, such as npm run workshop:start and npm run test:workflow.

Continue through the tutorial

The three pages after this one use the same project:

1. Build and run a vacation approval: start a request as one account, answer it as another, read what IdentityFlow recorded, run the Workflow Tests, change the approver, and restart IdentityFlow while a request waits.
2. Change a multi-step approval: read a workflow with approval stages in a fixed order, then add a stage.
3. Run the starter’s tests in CI: run the type check and the Workflow Tests in a CI job.