Tutorial · Build it

Stage 1 — Get it live

Install the incident-desk template as lumen and deploy it — a URL, a handbook, a code review, and an app in the portal catalogue, before it has any data.

By the end of this page Lumen is running on a public URL, listed in the portal, and reviewed — with nothing behind it yet. That is the point: the first stage gets you something real before there is any data or AI to reason about.

Say this to your code agent

Deploy the incident desk template as lumen.

Install the Dibbla template "incident-desk" into a new directory as "lumen".
Keep the REVIEW.md and docs/index.md the template ships — do not delete them —
and confirm the handbook has a subtitle. Then deploy the project to Dibbla with
the alias "lumen" and a conventional commit message. When it is live, curl the
app's /api/health and report the URL back to me.

What happens next

Your code assistant takes that prompt and does the work for you. It installs the ready-made incident-desk template into a new folder called lumen, checks that the two files a deploy needs are already in place, and ships it to Dibbla under the name lumen. You do not have to know what any of those files are — the template already contains them.

A code assistant is not deterministic, so the exact steps it takes may vary from one run to the next. That is fine: what matters is the end state, and the end state is the same every time.

When it finishes, you have a live app on a public URL — something like https://lumen-0ee1f995.dibbla.app — that you can open in a browser right now. It also shows up in your portal catalogue at app.dibbla.com, with a one-line subtitle and an Open button, so colleagues can find it too.

Open it and you will see the incident list with a first-run banner: the app is healthy, but there is no data behind it yet. That is expected at this stage — Stage 2 gives it a database and the banner goes away.

Under the hood the CLI & code behind this step — optional

1. Install the template

The incident-desk template ships everything a deploy needs — a Dockerfile, a handbook, and a REVIEW.md. List what is available, then install it under the alias lumen:

$dibbla template list
$dibbla template install incident-desk lumen
$cd lumen

The installer scaffolds the project and runs it locally so you can see it before you ship it.

On a headless machine the last step is skipped

The bootstrap ends by trying to open the running app in a browser. On a machine with no desktop browser that step fails with exit code 3 — the project is installed correctly and the failure is cosmetic. The installer also leaves a dev server running in the background and does not stop it; leave it while you work, or kill it before you move on.

2. Keep the handbook and the review

A bare project has to be given two files before it will deploy; this template ships both, so it passes the gate as-is. Know what they are before you change them:

docs/index.md — the end-user handbook. Its frontmatter carries a subtitle:, the one line colleagues read under the app name in the portal catalogue. The template’s subtitle describes an incident desk; leave it, or rewrite it in your own words — a subtitle that does not match the app is worse than a terse one.
REVIEW.md — the pre-deploy guardrails report. Without it, the deploy refuses to start:

✗ deploy blocked: pre-deploy review incomplete
  • missing REVIEW.md (pre-deploy guardrails report)

The report answers five checks — secrets and credentials, database access, outbound calls, what the app exposes without authentication, and the personal data it holds: which fields, how a person is deleted, who else receives them. The template’s REVIEW.md already answers them for a fresh incident desk with no database bound yet, which is exactly the state you are deploying in:

---
Review-status: Ok
One-Sentence-Summary: "Incident-desk starter; no database bound yet, no external writes."
---

## Pre-deploy guardrails report

- [x] Security: no secrets in the image; `.env` excluded from the build context
- [x] Database usage: none yet — a first-run banner shows until one is bound
- [x] REST / API call patterns: same-origin only
- [x] External system writes: none
- [x] Personal data (GDPR): none stored or processed yet

You will revisit this file as later stages add a database and an AI call — the review is meant to track what the app actually does.

3. Deploy

$dibbla deploy --alias lumen -m "feat: initial deploy"
deploy ok  ·  https://lumen-0ee1f995.dibbla.app  ·  41.7s

The -m message is not decoration — every deploy is a commit in the Dibbla-managed repository for your app, and that message is its subject. Write it the way you would write a git commit.

The URL is your alias plus a short suffix — here 0ee1f995 — that identifies your organisation, so two organisations can both own an app called lumen. You pass the bare alias lumen to every command; the suffix only ever appears in the hostname.

A slow deploy is not a failed deploy

Builds over about 100 seconds can return a Cloudflare 524 to the client while the backend finishes successfully. Wait a couple of minutes and run dibbla apps list before retrying — and if you do retry, use --update, never --force.

4. Check it

You cannot know the hostname suffix beforehand — read it from the deploy output, or from dibbla apps list:

$dibbla apps list
$curl https://lumen-0ee1f995.dibbla.app/api/health
{"app":"Lumen","database":"absent","status":"ok"}

Open the URL and the incident list renders with a first-run banner: the app is healthy but no database is bound yet, which the health check reports as "database":"absent". Stage 2 fixes that.

Lumen also appears in the portal catalogue (app.dibbla.com) with the subtitle from docs/index.md and an Open button — the colleague-facing surface, ready before there is anything to store.

Next: it is live, but empty

Lumen runs, but the first-run banner is telling you the truth — there is nothing behind it. Stage 2 gives it a managed database, seeded the moment it boots.

Stage 2 → Give it data

Also at this point

Connect an AI agent — Lumen is now a real platform resource, so this is the earliest point where an agent connection can prove more than a handshake. Connect over OAuth, let the agent identify you, and ask it to find lumen and report the same live status you just checked. This is an optional route around the tutorial spine; Stage 2 still assumes only the CLI and your code assistant.
Custom domains — “live” and “live at a name you chose” are the same thought, seconds apart. Lumen is fine on its platform alias for this tutorial; a domain purchase is a real-world errand the tutorial can’t hand you, not a build step.
Application checks — step 4 above was a curl you ran once, by hand, and it was true for exactly that second. A dibbla-checks.yaml next to the Dockerfile is the same question written down, so you can ask it again after every deploy without remembering the command. Lumen does not need one to work, which is why this is not a stage — but the moment you care whether a deploy broke something, this is where that lives.

← Previous

Before you start

Stage 2 — Give it data