Skip to content

Parcours — the guided path

The documentation is a map, organized by system. This page is the walk: the same pages, in the order a newcomer should live them. Follow it top to bottom and you go from an empty machine to a running hub, a fused entity, a métier chat that cites its sources, and a workflow that flags what stopped moving.

Who it is for. An integrator or tester discovering lumnik — nothing assumed beyond Docker and a terminal. Format: three half-days. Every step gives you a goal, the page to follow, and a checkpoint — you know it worked when… Do the steps; don't just read them.

The one rule

Run every command from the repository root unless a page says otherwise. Half of all mysterious failures are a wrong working directory.

Before you start, you need: a machine with Docker, Go 1.24+ (to build lm), and Ollama if you want local models — the deploy page lists the details.

Half-day 1 — defrost reading

Goal of the day: legacy data flows into the hub, read-only, and you can prove nothing was lost.

1. The pitch — 10 min. Read the Home page. It tells you what lumnik is (a read-only defrost of legacy ERPs) and, just as important, what it is not (not a migration, not a BI project).

2. Deploy the hub — 30 min. Follow Deploy lumnik, self-host path: one command, deploy/selfhost/up.sh. It generates all secrets into a local .env — your credentials live there, including HUBADMIN_PASSWORD. You know it worked when: the script reports the stack healthy and prints where the hub answers.

3. Meet lm — 20 min. The 60-second Quickstart builds the lm binary, logs in, and applies your first manifest. You know it worked when: lm login succeeds and lm version prints today's build.

4. The WOW — 60–90 min. This is the heart of the first half-day. Read The WOW, step by step, then replay it yourself with The WOW, hands-on: a SOAP Siebel and a CSV fused into one canonical Customer, asked in natural language. You know it worked when: you ask a question in French and the answer cites its sources.

5. How a connector is built — 30 min. Now that you have seen one run, read Overview & validator and the manifest you just used, CSV file. Every other source type follows the same grammar — the full list is on the shelf below.

6. The honesty of ingestion — 20 min. Read Seeing what was ingested, skipped, and quarantined. You know it worked when: on your own run report you can verify the conservation invariant: records_in = records_out + records_skipped.

Half-day 2 — defrost reasoning

Goal of the day: the ingested data answers questions — honestly, and only to the people entitled to ask.

1. Fuse sources into one truth — 40 min. Read Entities — fuse and inspect the Customer entity you applied during the WOW. You know it worked when: you can find the _conflicts ledger and explain why a row is in it.

2. The five guards — 30 min. Read Ask honesty — the five guards. This page is lumnik's spine: an abstention is a feature, a confident wrong answer is the cardinal sin. You know it worked when: you can name the guard that stops a hallucinated table name.

3. Scopes — 30 min. Read Scopes: a scope is a connector tag, granted as a Keycloak role. Zero scope roles = tenant-wide; one or more = bound. You know it worked when: a scope-bound user gets 403 scope not granted outside their métier — and sees answers inside it.

4. Models & providers — 20 min. Read Models & providers to know which LLM answers you, and how to swap it (Ollama local or a remote provider).

5. The integrator's cockpit — 40 min. Skim the CLI & TUI reference, then open the TUI with lm ui and redo yesterday's WOW checks without leaving it. You know it worked when: you can find any connector run and its report using only the TUI.

6. Who may do what — 20 min. Read Roles & permissions and skim RLS & database roles: tenant isolation is enforced by the database itself, not by application code being careful.

Half-day 3 — defrost time and the apps

Goal of the day: the hub stops being a mirror and starts finding things — and each métier gets a surface.

1. Views — see — 30 min. Read Views and apply the WOW's saved view. You know it worked when: GET /api/views lists it and a scoped user can render it.

2. Processes — react — 30 min. Read Processes: declarative reactions to data.row.changed, always refusable, never writing to the source.

3. Workflows — declare the lifecycle — 45 min. Read Workflows. This is the third defrost axis: the ERP shows current state; lumnik, ingesting repeatedly, reconstructs time — and a declared lifecycle plus a dormancy threshold turns silence into an alert. You know it worked when: the métier chat answers a lifecycle question from your declared graph, not from imagination.

4. Inbox — decide — 20 min. Read Inbox: where decision.* events (including decision.dormant.<workflow>) wait for a human, and the ack gesture.

5. The métier PWA — 30 min. Read The métier PWA and open /app/ on a phone: cards on a phone, a table on a tablet, the same scope rules as everywhere else.

6. Run it for real — 40 min. Read Backup & restore and Upgrade — the two pages you must have practiced before the day you need them. You know it worked when: you have run one backup and know where it landed.

If you get stuck

Lessons from the first strangers who walked this path — each of these cost someone an hour:

  • Wrong directory. Commands assume the repository root. When a relative path fails, check where you are before checking anything else.
  • The first minute is not an outage. Right after the stack starts, the hub can briefly answer 401 or refuse connections. Wait a minute and retry before diagnosing.
  • The ghost binary. After rebuilding lm, run lm version. If it prints an old build, your PATH serves a stale copy — prefer a symlink to your build over cp.
  • Credentials. Everything is generated at install time into the .env next to up.sh. If a login page surprises you, the answer is in that file.
  • Ollama pulls one model at a time. One ollama pull <model> per line, and make sure ollama serve isn't already running before starting it again.

If a step of this parcours doesn't match what you experience, that gap is a bug in the documentation — please report it. The stumbles of the first walkers are how this page got honest.

The reference shelf

Everything not on the walk above, so nothing in the documentation is orphaned. Come back here when the need arises — not before.

More source types — same manifest grammar as CSV: JDBC · REST (and its details) · GraphQL and SOAP — request shapes on the REST engine · Kafka inbound · File sources SFTP/S3 · CSV details · Transform at ingestion

Integrations & API: HTTP API for ask · Admin API

Extending the hub: Hooks guide · Hooks cookbook

Enterprise identity: Bring your own IdP · SCIM deprovisioning

Day-2 operations: Observability · Rate limits

Deploying at scale: The cloud edition (commercial) ships a Kubernetes/Helm path — not part of this repository.