Setting up Colibri

If configuration is incomplete the process refuses to start, and prints every missing setting at once:

Deployment configuration is incomplete:
  - vault provider 'infisical': Not configured. Set: INFISICAL_SITE_URL, INFISICAL_CLIENT_ID, INFISICAL_CLIENT_SECRET
  - cron provider 'qstash': Not configured. Set: QSTASH_TOKEN

That is the primary setup interface. It goes wherever your platform sends container logs, needs no credentials, and cannot be skipped.

A fresh deployment does not stop there. It starts in setup mode: it serves this guide and the setup page, answers its health check, and returns 503 for everything else. No variable is needed to get there. Setup mode stays on until you turn it off — configuring everything is not enough, because finishing setup is the only moment anyone can be sure a human looked at the result.

Once a deployment has turned setup off with COLIBRI_DISABLE_SETUP_MODE=1, an incomplete configuration becomes fatal again. That is deliberate: a deployment that worked once and comes back misconfigured is a regression, and refusing to start fails the rollout and leaves the previous version serving, where dropping into a wizard would report the deploy healthy while 503ing every request.

Once running, /admin shows the same capabilities plus live connectivity — whether the vault actually answers, whether credentials are accepted.

Reading the states

1. Deploy. Bring up the four services — API, app, worker, website — along with Postgres, Redis and an S3-compatible bucket. The deployment artifact wires those together; you do not have to.
2. Open the deployment. Any URL redirects to the setup page while configuration is incomplete. Nothing else answers.
3. Configure the third-party services the setup page lists — a secrets vault, email delivery, scheduling — in the environment the deployment was started with, redeploying as you go. The page reflects what is set on each restart.
4. Finish setup. The setup page reveals the last step once everything is configured: redeploy with COLIBRI_DISABLE_SETUP_MODE=1. That takes the deployment out of setup mode and starts serving the product.

Step four is a real step, not a formality: until it is done, a later configuration mistake would quietly land the deployment back on a wizard instead of failing the rollout.

A database, a cache, an object store and a signing secret. Unlike the sections below these are not a choice — they are wiring, and a deployment artifact that bundles its own dependencies will have set them for you.

They are listed because the process cannot start without them. While setup is allowed the requirement is relaxed so the deployment can boot far enough to tell you what is missing; once you turn setup off they are hard requirements again.

Where a connection's credentials are stored. Required — Colibri will not start without one.

SECRET_PROVIDERS is a comma-separated list of providers to enable. New secrets are written through the first one listed. Existing secrets are always read back through whichever provider wrote them, so adding a provider is safe; removing one that still holds secrets is not.

infisical

Create the machine identity under Access Control → Identities → Universal Auth, and grant it permission to create projects, folders and secrets. Colibri creates one project per organization on demand, so there is no project id to configure.

INFISICAL_ENVIRONMENT takes the environment's slug, not its display name. The environment shown as "Production" has the slug prod; setting production makes every read and write 404.

memory

An in-process store for local development and tests. Values are unencrypted and lost on restart, so it refuses to run when NODE_ENV=production.

Verification and organization-invitation email. Two transports, and Colibri picks between them by a single rule: RESEND_API_KEY set means Resend, otherwise SMTP_HOST selects SMTP. They are never both active.

One of RESEND_API_KEY or SMTP_HOST is required — there is no implicit fallback, and a deployment with neither will not start. Earlier versions defaulted to a local mail catcher, which made an unconfigured deployment look healthy while every verification and invitation email went nowhere.

Runs datasource imports on a schedule, through QStash.

One-shot imports fall back to direct HTTP when QStash is unavailable; scheduled imports do not, and will fail.

/admin is gated separately from the product. See ADMIN_API_TOKEN and ADMIN_EMAILS; the page itself explains what is missing when neither is set.

Status: self-hosted deployment is still being shaped. Everything here is accurate for the current release, but the operational guidance has not yet been proven against a real customer install — expect it to get more specific as it is.