How to Deploy Pocket ID on a VPS

#Install Pocket ID (Docker Compose)

Pocket ID publishes an official compose file and an environment template. Start from those:

copymkdir -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.

copygrep -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:

copysed -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:

copydocker 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 + domain via Caddy

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.

#First-run setup

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:

1. Add users and groups. Invite users by email (needs SMTP) or create a one-time login link to send them. They register their own passkey when they first sign in.
2. Create an OIDC client for each app. Pocket ID shows the client ID, the client secret and the discovery URL, https://id.example.com/.well-known/openid-configuration, which most apps ask for.
3. Restrict the client to groups if not every user should reach every app.

#Securing it

• Register at least two passkeys for the admin account, for example a phone and a hardware key. There is no password to fall back on, so a single lost device means you are locked out.
• Keep the port on the loopback interface while TRUST_PROXY=true is set. A directly reachable container would accept forged forwarded headers.
• Configure SMTP under the application settings. Pocket ID can then email sign-in alerts and one-time access codes.
• Keep .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.

#Backups

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:

copycd ~/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.

#Upgrades

The v2 tag follows the latest Pocket ID 2.x release, so upgrading is a pull:

copycd ~/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).

#Troubleshooting

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.

#Verification + next steps

You're done when:

• https://id.example.com loads with a valid certificate;
• you can sign in with a passkey from two different devices;
• https://id.example.com/.well-known/openid-configuration returns the discovery document;
• an encrypted backup of 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.