Guided path — three half-days
Guided onboarding
From an empty machine to a running hub, a fused entity, scoped chat that cites its sources, and a workflow that flags what stopped moving — in three half-days.
Run every command from the repository root unless a page says otherwise.
git clone https://github.com/icreated/lumnik-open.git && cd lumnik-open
That repository is the open edition. A step marked Pro needs lumnik Pro with the AI on:
the chat, lm ask, the models. On the open edition, read the step and skip its checkpoint.
See The two editions.
The three half-days at a glance
Deploy the hub, meet lm, run the WOW, and prove that ingestion stayed read-only and lost nothing.
Six steps, ≈ 3 h
Understand entities, the ask guards, scopes, models, and the TUI an integrator operates from.
Six steps, 3 h
Move from a mirror of the source to views, processes, workflows, inbox decisions, and the PWA.
Six steps, ≈ 3 h 15
Half-day 1 — defrost reading
Goal of the day: legacy data flows into the hub, read-only, and you can prove nothing was lost.
Read the Home page: what lumnik is (a read-only defrost of legacy systems) and what it is not (not a migration, not a BI project).
You know it landed when: you can explain why lumnik is neither a migration nor a BI project.
Decide what the hub carries — The two editions, Choosing what your hub offers. Then follow Deploy lumnik: ./deploy/selfhost/up.sh --build. Your passwords are in the .env it writes, at the root of the clone.
You know it worked when: the script ends like this:
==> hub is healthy
hubadmin: per-install password set (HUBADMIN_PASSWORD in .env)
integrator: per-install password set (INTEGRATOR_PASSWORD in .env)
Hub: http://localhost:8080 (health: /q/health)
Keycloak: http://localhost:8180/realms/lumnik
Next: point lm at the hub — server http://localhost:8080, OIDC http://localhost:8180/realms/lumnik
lmFollow the Quickstart: install lm, log in, put a first file into the hub.
You know it worked when: lm connector list shows the connector your first file registered.
$ lm connector list
NAME TYPE TENANT SCHED WINDOW STATUS LAST RUN
stock_count csv-file 1
Run The WOW: a SOAP Siebel and a CSV fused into one Customer.
You know it worked when: lm entity get customer lists the fused customers. Pro: a question asked in French answers with the SQL it ran.
Read Connectors overview and CSV & files, the manifest you just used. Every source type follows the same grammar.
You know it landed when: you can explain the relationship between manifest, endpoint, and ingestion report.
Read Seeing what was ingested, skipped, and quarantined.
You know it worked when: on the WOW's cust-csv run, you read IN = OUT + SKIPPED. Every skipped row is counted. lm dlq list shows the ones set aside.
$ lm run get 3e9f353a
ID CONNECTOR ENDPOINT STATUS IN OUT SKIPPED DEAD-LETTERS STARTED ENDED
3e9f353a cust-csv default Completed 8 8 0 0 2026-10-24 21:57 2026-10-24 21:57
Half-day 2 — defrost reasoning
Goal of the day: the ingested data answers questions — sources shown, and only to the people entitled to ask.
Read Entities — fuse and read the Customer entity you applied during the WOW.
You know it worked when: you find the _conflicts ledger and can say why C-200 is in it.
$ lm entity get customer --filter customer_code=C-200
CUSTOMER_CODE NAME SEGMENT EMAIL CITY _CONFLICTS
C-200 Marie SILVER m@x.fr Lyon {"name": [{"src": "cust_siebel", "value": "Marie"}, {"src": "t_cust_csv", "value": "MARIE A."}]}
Read When Ask refuses: what lm ask says, and what to do.
You know it worked when: you can say what to do when lm ask answers « la question ne correspond pas au schéma déclaré ».
Read Scopes:
- a connector or an entity declares its scopes:
scopes: [clients]; - a user receives a scope as the Keycloak role
scope:<tag>; - a user with no scope role sees the whole tenant. A user with one or more sees only those scopes.
The bundled realm has no scope-bound user: create one in Keycloak with the realm role scope:desk (Add a user, Grant a business scope).
To work as that second user, give lm a second context. Open the login link in a private browser window: a normal window signs you in as integrator again.
lm config set-context desk --server http://localhost:8080 \
--oidc-issuer http://localhost:8180/realms/lumnik
lm config use-context desk
lm login
lm config use-context selfhost switches back to integrator.
You know it worked when: a user holding only scope:desk is refused the customer entity, whose scope is clients.
$ lm entity get customer # as a user holding scope:desk
Error: access refused (403): scope not granted
Read Models & providers: which model answers, and how to swap it (local Ollama or a remote provider).
You know it worked when: you know whether your install answers from Ollama or a remote provider.
Skim the CLI & TUI reference, then open the TUI with lm ui: type :runs and Enter, pick a run with the arrow keys, press d to describe it. ? lists every key.
You know it worked when: you can find any connector run and its report using only the TUI.
Read Roles & permissions and skim RLS & database roles.
You know it worked when: signed in as hubadmin (tenant 11, password HUBADMIN_PASSWORD in .env), you see none of tenant 1's decisions from the WOW.
Give lm a hubadmin context and sign in as in step 3 (private window), then:
$ lm inbox --all
ID WHEN PROCESS MESSAGE ENTITY_KEY
Half-day 3 — defrost time and the apps
Goal of the day: the hub stops being a mirror and starts finding things — and each team gets an app.
Read Views and save the WOW's view: lm view apply -f docs/demo/wow-customer/clients-view.yaml.
You know it worked when: lm view list lists it and a user holding scope:clients renders it.
$ lm view list
NAME SCOPE TITLE
clients-desk clients Clients
$ lm view clients-desk --filter city=Lyon
Clients · city=Lyon
Code client Nom Ville Segment
C-200 Marie Lyon SILVER
C-500 Claire Martin Lyon
C-800 Albert Camus Lyon
C-900 Saint Exupery Lyon
Read Processes: a declared rule raises a decision when a new or changed row matches it. A process never writes to the source.
You know it landed when: you can say which rows make a process fire, and why re-running an unchanged export fires nothing.
Read Workflows: a declared lifecycle over a status column, and a dormancy threshold that turns a document left unmoved into an alert.
You know it worked when: you replayed the WOW's step 9: lm workflow apply reports EN LITIGE as undeclared. Pro: scoped chat answers a lifecycle question from your declared graph.
Read Inbox: decisions and dormancy alerts wait there for a human. lm inbox ack closes one.
You know it worked when: an acked decision leaves lm inbox and shows [acked] in lm inbox --all.
Read The PWA, then:
- open
https://<your-host>/app/— cards on a phone, a table on a tablet; - a phone cannot reach your laptop's
localhost: put the TLS proxy in front first; - choose each app's tabs with one line of its manifest:
spec.tabs.
You know it worked when: you see the same scope boundary on the phone and on the desktop.
Read Backup & restore and Upgrade, and practise both before you need them.
You know it worked when: ./deploy/selfhost/backup.sh ends with ==> done: <folder> and you know where that folder is.
If you get stuck
Common stumbles:
- 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
401or refuse connections. Wait a minute and retry before diagnosing. - The ghost binary. After rebuilding
lm, runlm version. If it prints an old build, your PATH serves a stale copy. - Credentials. Every password is generated at install time into
.env, at the root of the clone. If a login page surprises you, the answer is in that file. - Ollama pulls one model at a time. Write one
ollama pull <model>per line. Before you startollama serve, check that it is not already running.
If a step does not match what you see, report it — it is a documentation bug.
The reference shelf
Everything not on the walk above, for when you need it.
More source types — same manifest grammar as CSV: JDBC · REST · GraphQL · SOAP · Kafka inbound · Transform at ingestion
Integrations & API — HTTP API for ask · Admin API
Enterprise identity — Bring your own IdP · SCIM deprovisioning
Day-2 operations — Observability · Rate limits · Sizing & load tests
Deploying at scale — the cloud edition (commercial) ships a Kubernetes/Helm path; not part of this repository.