Analytics cookies only (Google Analytics, PostHog). No ad networks, no cross-site tracking. See our privacy policy.
Updated Sep 2026
verified on Ubuntu 26.04 · Sep 2026Self-host Pocket ID, a small passkey-only OIDC provider, on a VPS. It runs as one container with SQLite, with the encryption key generated up front and HTTPS through Caddy, which passkeys require.
Pocket ID is a small OpenID Connect provider. Users sign in with passkeys only. There are no passwords to set, reset or leak. You register Pocket ID as the OIDC provider in apps that support "Sign in with OIDC", and your users authenticate with a fingerprint, a phone or a hardware key. It is written in Go with a SvelteKit frontend and licensed BSD-2-Clause.
It is built for small self-hosted setups: a homelab, a family, a small team. It has user and group management, per-client access restrictions, and an audit log. It doesn't federate LDAP or speak SAML, and it doesn't try to be Keycloak. If you need a login wall in front of apps that have no OIDC support, you need a forward-auth tool instead, such as Tinyauth or Authelia. Pocket ID vs Authelia and Authentik vs Pocket ID cover the trade-offs.
Measured idle on our test box, Pocket ID used about 18 MB of RAM and about 120 MB of disk for the image. The catalog's conservative floor is 256 MB RAM. Any entry-level VPS works, and Pocket ID can easily share a box with the apps that use it. The SQLite database stays small: it holds users, passkey public keys, OIDC clients and the audit log.
This guide assumes Docker Engine, the Compose plugin and a ufw firewall are
set up. If they aren't, work through
Docker & Compose on Ubuntu. Open only
SSH and the reverse-proxy ports:
sudo ufw allow OpenSSH
sudo ufw allow 80
sudo ufw allow 443
sudo ufw status verbose
Create an A record for id.example.com pointing at the server.
Paid link — we earn a commission if you shop through it.
Pocket ID publishes an official compose file and an environment template. Start from those:
mkdir -p ~/pocket-id && cd ~/pocket-id
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/pocket-id/pocket-id/main/docker-compose.yml
[ -f .env ] || curl -fsSL -o .env https://raw.githubusercontent.com/pocket-id/pocket-id/main/.env.example
cat docker-compose.yml
The compose file runs pocketid/pocket-id:v2, stores everything in ./data,
and has a built-in health check. Change two things before the first start.
1. The environment. The template leaves ENCRYPTION_KEY empty, and Pocket
ID v2 refuses to start without one. The key encrypts sensitive data stored by
Pocket ID, so generate it once and keep it. APP_URL must be the public HTTPS
address. TRUST_PROXY=true lets Pocket ID read the client IP and scheme from
the forwarded headers. Only set it when, as below, nothing except the reverse
proxy can reach the container.
grep -q '^ENCRYPTION_KEY=.\+' .env || sed -i "s|^ENCRYPTION_KEY=.*|ENCRYPTION_KEY=$(openssl rand -base64 32)|" .env
sed -i \
-e 's|^APP_URL=.*|APP_URL=https://id.example.com|' \
-e 's|^TRUST_PROXY=.*|TRUST_PROXY=true|' \
.env
chmod 600 .env
grep -E '^(APP_URL|TRUST_PROXY|PUID|PGID)=' .env
The grep -q guard means a re-run never replaces a key that is already in use.
2. The port. Upstream publishes port 1411 on every interface. Bind it to the loopback interface so that Caddy is the only way in:
sed -i 's|^\(\s*\)- 1411:1411|\1- "127.0.0.1:1411:1411"|' docker-compose.yml
grep -n 1411 docker-compose.yml
Start it and check the health endpoint:
docker compose up -d
timeout 90 bash -c 'until curl -fsS -o /dev/null http://127.0.0.1:1411/healthz; do sleep 3; done' && echo "healthz OK"
docker compose ps
HTTPS is required, not just recommended. Browsers only offer WebAuthn, the API behind passkeys, on secure origins, so a Pocket ID served over plain HTTP on a public IP can't register or use a passkey. Install Caddy as described in Automatic HTTPS with Caddy and add:
id.example.com {
reverse_proxy 127.0.0.1:1411
}
The hostname in the Caddyfile, APP_URL in .env, and the address you open in
the browser must all be the same. A passkey is bound to the domain it was
created on, so passkeys registered on one hostname don't work on another.
If Caddy runs as a container, put it on the same Docker network and use
reverse_proxy pocket-id:1411.
Open https://id.example.com/setup. This one-time page creates the first admin
account: enter your name and email, then register a passkey when the browser
asks. After that, /setup is closed and you sign in at the root URL.
Then, in the admin area:
https://id.example.com/.well-known/openid-configuration, which most apps
ask for.TRUST_PROXY=true is set.
A directly reachable container would accept forged forwarded headers..env private. It holds ENCRYPTION_KEY. If you lose it, the data
Pocket ID encrypted with it can't be recovered, and anyone who has it can
decrypt that data from a stolen backup.Everything lives in ./data: the SQLite database pocket-id.db and
uploads/ with logos and profile pictures. .env holds the encryption key.
The container writes ./data as UID 1000, which may not be your login user, so
the archive is created with sudo. Stop the container for a clean copy of the
database. It is back up within seconds:
cd ~/pocket-id
docker compose stop
sudo tar czf pocket-id-backup-$(date +%F).tar.gz data .env docker-compose.yml
docker compose start
sudo chown "$USER": pocket-id-backup-*.tar.gz
tar tzf pocket-id-backup-$(date +%F).tar.gz | grep -c pocket-id.db
The archive contains the encryption key. Encrypt it (for example with
gpg --symmetric) before you copy it off the server.
The v2 tag follows the latest Pocket ID 2.x release, so upgrading is a pull:
cd ~/pocket-id
docker compose pull
docker compose up -d
Back up first. Pocket ID migrates its database on startup, and an older
version refuses to run against a newer schema unless you explicitly set
ALLOW_DOWNGRADE. Read the changelog before you move to a new major version
(a new image tag such as v3).
The container exits right after starting. Run docker compose logs pocket-id.
The usual cause is an empty or missing ENCRYPTION_KEY, or a ./data folder
the container can't write to. Upstream's compose sets PUID/PGID to 1000.
If the files belong to another user, fix it with sudo chown -R 1000:1000 data.
The browser never offers to create a passkey. You're not on HTTPS, or the
hostname differs from APP_URL. Open the exact https:// URL from .env.
An app rejects the login with a redirect or callback error. The app's callback URL must match one registered on the OIDC client in Pocket ID character for character, including the scheme and any trailing path.
Audit log shows the proxy's IP for every sign-in. TRUST_PROXY isn't
enabled, or the proxy doesn't send X-Forwarded-For. Caddy sends it by
default.
You're done when:
https://id.example.com loads with a valid certificate;https://id.example.com/.well-known/openid-configuration returns the
discovery document;data and .env is stored off the server.Next, connect your first app as an OIDC client. Many self-hosted apps have a generic OIDC login option. For apps that don't, put a forward-auth layer such as Tinyauth in front of them. Tinyauth can itself use Pocket ID as its OAuth provider.
We estimate about 25 minutes of hands-on time for "How to Deploy Pocket ID on a VPS"; this is an editorial estimate, not a measurement.
The "How to Deploy Pocket ID on a VPS" guide was verified end-to-end on Ubuntu 26.04 (Sep 2026).