Deploy your first app

You have the CLI and you are signed in. This page takes you from nothing to a running app, and then shows you the two places it appears — because the URL is where most platforms stop, and where Dibbla starts.

1. Start from a template

Every bundled template ships a working Dockerfile, which is the one thing a Dibbla deploy requires. List what is available, then install one:

$dibbla template list
$dibbla template install getting-started my-first-app
$cd my-first-app

2. Write the handbook

Before it will deploy, your app needs an end-user handbook at docs/index.md with a one-line subtitle: in its frontmatter. This is not ceremony: the platform renders every .md under docs/ as your app’s handbook, and the subtitle is what colleagues read under the app name when they go looking for it.

---
subtitle: A starting point I am about to make into something useful.
---

# My first app

What it does, who it is for, and how to use it.

Write the subtitle for your app, not for the template — it is the one line colleagues read in the catalogue, and a description that does not match the app is worse than a terse one. (Some templates ship an APP.md at the root instead; either satisfies the requirement, but do not maintain both.)

3. Run the pre-deploy review

The deploy will refuse to start without a REVIEW.md at the root — this is the gate the code review page describes, and it stops here first:

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

Work through the four checks — secrets and credentials, database access, outbound calls, and what your app exposes without authentication — and write what you found:

---
Review-status: Ok
One-Sentence-Summary: "Template starter, no credentials, no database, 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
- [x] REST / API call patterns: same-origin only
- [x] External system writes: none

The example prompt below has a code agent do this properly, including reading the code rather than assuming.

4. Deploy

$dibbla deploy . --alias my-first-app -m "feat: initial deploy"
deploy ok  ·  https://my-first-app-b4687da9.dibbla.app  ·  22.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 identifying your organisation, so two organisations can both have an app called my-first-app. You pass the bare alias to every command; the suffix only appears in the hostname.

Deploy this directory to Dibbla as "my-first-app". Before deploying, run the
pre-deploy guardrails checklist and write REVIEW.md, and make sure there is an
end-user handbook at docs/index.md with a subtitle. Then deploy with a
conventional commit message.

5. See it in both places

Your app now exists on two surfaces, and they answer different questions:

• The console (console.dibbla.com) is the operator’s view: status, replicas, logs, version history, secrets, and the code-review indicator for the deploy you just made.
• The portal (app.dibbla.com) is your colleagues’ view: the My Apps catalogue, where your app appears with its subtitle, its handbook, and an Open button.

That split is the shape of the whole platform: you operate in the console, your organisation consumes in the portal.

Next: your app is live — now what?

The URL is the least interesting thing you just got. Every deploy also brought a code review, a handbook, an access policy, logs, a secret store, an LLM gateway and a place to put your data.

Learn the vocabulary first →