Skip to content

You're viewing the prerelease documentation siteContent here is for testing and may differ from the live docs.

Go to live docs

Self-Hosting Overview

Run your own instance and every secret, account and log line stays on infrastructure you control. You decide how accounts are authenticated, whether the instance is reachable from the public internet at all, and what branding the interface carries.

The mode decides what else has to be running, so settle it before you install.

simple is the shipped default and needs only the Valkey/Redis datastore. full adds a SQL database for accounts, which defaults to SQLite at sqlite://data/auth.db; PostgreSQL is a supported option rather than a requirement. In a container that file needs a mounted volume to survive a restart.

Simple or Full covers what each mode unlocks, where that database has to live, and how hard the mode is to switch later.

In a hurry, with a Valkey or Redis you already run? The single docker run form in Install with Docker brings up an instance on port 3000 with a generated SECRET value. Everything else on this page still applies once it is up.

  • Images and variants — which of the published images to run, and how the release tags work.
  • Install with Docker — the two Compose stacks the project ships.
  • Install on Linux — a bare-metal install on Debian or Ubuntu. No other distribution family is covered by the project’s install tests.
  • Run as a service — the systemd units the repository ships, and the Procfile runner for hosts without systemd.
  • Reverse proxy and TLS — the application never terminates TLS, so a proxy in front of it is assumed. Read this before you expose the instance.
  • Verify your install — prove the instance is genuinely serving before you hand it to anyone, and create the first account: the site-operator role is granted from the CLI only.

Upgrading an existing install? The Upgrade Guides list the available guides, newest first. Start with the first guide after the release you run now and work forward, and read the release notes for every intervening release.

The Configuration reference describes the configuration files and their main sections. The Configuration generator builds starting files from a few choices about your deployment, and Environment variables lists every variable, grouped by subsystem.

Recommended for an instance running authentication mode simple:

  • 2+ CPU cores
  • 2GB+ RAM
  • 10GB+ disk space

A full-mode deployment that also runs PostgreSQL, the background worker and the scheduler needs roughly double that.

Some administrative work has no screen in the application and is done from the instance’s command line.

Transferring an organization to a new owner is the main one. Organization owners have no screen or endpoint for it, so the transfer is yours to perform. For automation, the Colonel API exposes the same operation at POST /api/colonel/organizations/:org_id/transfer-ownership; it requires the colonel role, takes the organization’s name as confirmation, and applies immediately with no preview.

Membership preconditions, the write gate, postchecks and recovery limits: the operator transfer procedure.

The end-user side of this is Ownership and transfer, which is what your users will have read before they ask you.