Get started
Self-host Keyring
Keyring is one container plus a Postgres database. This guide runs it with Docker Compose on your own machine, then on any host that runs containers. To deploy on Unkey Deploy, follow Deploy Keyring to Unkey Deploy.
Run it with Docker Compose
You need Docker with Compose v2.
Clone the repository, create an encryption key, and start the stack:
git clone https://github.com/unkeyed/keyring.git cd keyring echo "ENCRYPTION_KEY=$(openssl rand -base64 32)" >> .env docker compose up -d --build --waitENCRYPTION_KEYencrypts the webhook secrets and two-factor seeds Keyring stores, so a database backup alone does not reveal them. Keep.envwith your other secrets. Compose builds the image, starts Postgres 17 and Keyring, and returns when both pass their health checks.Check that Keyring is up:
curl -i http://localhost:8080/healthzThe answer is
HTTP/1.1 200 OK.Print the setup link:
docker compose logs app | grep -A2 'Open this link'Open the link, enter your name and email, and register a passkey with your fingerprint, face, or device PIN. You are the first user. The link works once. Sign-in covers providers, two-factor, and passwords.
Postgres keeps its data in the db volume that docker-compose.yml declares. docker compose down stops the stack and keeps the data. docker compose down -v also deletes the data.
Change the ports
If port 8080 or 5432 is taken, set KEYRING_PORT or KEYRING_DB_PORT when you start the stack:
KEYRING_PORT=18080 KEYRING_DB_PORT=15432 docker compose up -d --build --wait
Set other variables
Compose passes ENCRYPTION_KEY, ENCRYPTION_KEY_PREVIOUS, ENRICHMENT_DAILY_LIMIT, CONTEXT_DEV_API_KEY, PUBLIC_URL, SETUP_TOKEN, PASSWORD_LOGIN, ALLOWED_EMAIL_DOMAINS, and the GOOGLE_*, GITHUB_*, and OIDC_* variables from your shell or from a .env file next to docker-compose.yml. To turn on enrichment, put the key in .env and restart:
echo 'CONTEXT_DEV_API_KEY=your-context-dev-key' >> .env
docker compose up -d --wait
For any other variable, create docker-compose.override.yml. Compose merges it into docker-compose.yml on every docker compose command:
services:
app:
environment:
UNKEY_ROOT_KEY: your-unkey-root-key
UNKEY_API_ID: api_123
Configuration lists every variable.
Compose publishes Keyring and Postgres on 127.0.0.1 only. To reach Keyring from other machines, put an HTTPS proxy in front of it and set PUBLIC_URL to the proxy's URL.
Run it on any container host
Use the prebuilt image ghcr.io/unkeyed/keyring on any host that runs containers, such as Fly.io, Railway, Render, Kubernetes, or a VM with Docker. Each release is tagged with its version, for example ghcr.io/unkeyed/keyring:0.1.0, and the newest release is also latest. The image is built for linux/amd64 and linux/arm64.
Create a Postgres database that the host can reach, and copy its connection URL.
Start the container with
DATABASE_URL, the HTTPS URL people will open Keyring at asPUBLIC_URL, and anENCRYPTION_KEYfromopenssl rand -base64 32that you store with your other secrets:docker run -d --name keyring -p 8080:8080 \ -e DATABASE_URL='postgres://user:pass@db.example.com:5432/keyring' \ -e PUBLIC_URL=https://crm.example.com \ -e ENCRYPTION_KEY='your-32-byte-base64-key' \ ghcr.io/unkeyed/keyring:latestPoint the host's health check at
GET /healthz. It returns 200 while the process runs and does not query the database.Put HTTPS in front of Keyring at
PUBLIC_URL. If the proxy writes the client address to a header, setCLIENT_IP_HEADERto it, so failed sign-ins and other per-address limits apply per client instead of to everyone behind the proxy at once.Open the setup link from the container log (
docker logs keyring) and register a passkey. The setup link explains it.
The container contract is short:
- Keyring listens on
$PORT, which defaults to8080. - On
SIGTERM, Keyring stops taking new requests and waits up to 20 seconds for open requests to finish. - Keyring keeps no state on disk. You can run several replicas against one database. Migrations, setup links, sign-in steps, and enrichment jobs are safe to run on every replica at once.
- Keyring writes JSON logs to stdout.
To test webhooks from a provider against Keyring on your laptop, expose port 8080 through a tunnel, for example cloudflared tunnel --url http://localhost:8080, and use the tunnel's URL as your host.
Upgrade
Pull or build the new image and restart the container. Keyring applies new migrations when it starts and has no command to undo them, so back up the database before you upgrade.
An upgrade from a version that seeded ADMIN_EMAIL and ADMIN_PASSWORD signs everyone out, because a password alone no longer signs anyone in. Unset both variables, restart, and open the setup link from the log with the admin's email. That account gets a passkey and keeps its data. Then teammates can sign in with a provider, or you can remove and re-invite them.
With Docker Compose:
git pull
docker compose up -d --build --wait
Back up
All state is in Postgres. Back it up as you would any Postgres database, for example with pg_dump. With Docker Compose:
docker compose exec -T db pg_dump -U keyring keyring > keyring-backup.sql
Recover a locked-out account
If someone loses every way to sign in, such as their only passkey, run keyring recover with their email. It needs the same DATABASE_URL and PUBLIC_URL as the server:
DATABASE_URL='postgres://...' PUBLIC_URL=https://crm.example.com keyring recover ada@example.com
With Docker, run docker run --rm -e DATABASE_URL=... -e PUBLIC_URL=... ghcr.io/unkeyed/keyring recover ada@example.com. The command prints a link that works once, for an hour. Opening it registers a new passkey for that account and signs it out everywhere else. Only someone with the database credentials can run it, and they can change every account anyway.
To avoid needing it, give every account two ways to sign in, such as a passkey on a laptop and one on a phone. Settings > Account warns while an account has only one.