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.
Choose an authentication mode first
Section titled “Choose an authentication mode first”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.
Pick an installation path
Section titled “Pick an installation path”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.
Configure the instance
Section titled “Configure the instance”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.
System requirements
Section titled “System requirements”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.
Operator-only actions
Section titled “Operator-only actions”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.
Getting help
Section titled “Getting help”- The GitHub repository for the source, the release notes and the shipped Compose stacks.
- The issue tracker for bugs, with the release tag and the relevant log lines.
- Contact us directly for anything else.