Pocket-ID

Pocket-ID

Docker app from junkerderprovinz's Repository

A small OpenID Connect provider that signs people in with passkeys instead of passwords.

Requirements

A domain with HTTPS in front of the container, for example through Nginx Proxy Manager. Passkeys do not work over plain HTTP or a bare IP address. Generate the encryption key before the first start and keep a copy somewhere safe: without it the stored data cannot be read.
Overview
A small OpenID Connect provider that signs people in with passkeys instead of passwords. Put it in front of the apps on your server that support OIDC login, from the photo library to the dashboards, and all of them share one login: a fingerprint, a face or a security key. Nobody has a password left to reuse or leak. Users, groups and the apps allowed to sign in are managed in the web interface. Data lives in SQLite in the appdata folder unless you point it at PostgreSQL. Browsers only create passkeys over HTTPS, so Pocket ID belongs behind a reverse proxy with a real domain. After the first start, open https://your-domain/setup and create the admin account with your passkey. Detailed README (reverse proxy, first admin, connecting an app): https://github.com/junkerderprovinz/Unraid-apps/blob/main/pocket-id/README.md
Pocket ID

Validate  Upstream Pocket ID  Image  Unraid  License

A plug-and-play Unraid Community Applications template for Pocket ID, the small OpenID Connect provider that signs you in with passkeys, wrapping the official pocketid/pocket-id image.

Maintained solo, in whatever spare time there is. Questions via the support thread, bugs, ideas and feature requests via GitHub issues. If it's useful to you, a coffee is always welcome.

Buy me a coffee   PayPal   Donate with crypto


Table of Contents

  1. What is this?
  2. Quick Start on Unraid
  3. Behind a reverse proxy
  4. Connecting an app
  5. Configuration
  6. Backups and the encryption key
  7. When something goes wrong
  8. How AI is used here
  9. Support this project

1. What is this?

Pocket ID is a login server for your other apps. Anything on your server that can sign in over OpenID Connect (the photo library, the dashboards, the hypervisor's web interface, the media server with an SSO plugin and plenty more) sends its users to Pocket ID, and Pocket ID asks for a passkey: the fingerprint reader on a laptop, the face unlock on a phone, a security key. There are no passwords in it at all, so there is nothing to reuse or phish.

It keeps users, groups and the list of apps that may sign in, and an audit log of every sign-in. Where the big identity suites want a database, a cache and an afternoon, this is one container with SQLite and around 20 MB of memory. It is BSD-2-Clause, written in Go and Svelte by Elias Schneider and contributors.

The template pins the image to v2, so updates follow every 2.x release but a future 3.0 does not arrive overnight. When it ships, read its release notes and change the tag yourself.

2. Quick Start on Unraid

  1. Apps and search for Pocket ID, then install.

  2. Set App URL to the domain Pocket ID will live under, for example https://id.example.com. Passkeys are bound to this domain, so settle on it before anyone signs up.

  3. Generate an Encryption Key in the Unraid terminal and paste it in:

    openssl rand -base64 32
    

    Keep a copy in your password manager. Section 6 explains why.

  4. Leave Data on /mnt/user/appdata/pocket-id and the user on 99:100.

  5. Start it, set up the reverse proxy (next section), then open https://id.example.com/setup. You create the first account there, which becomes the admin, and add its passkey right after.

Do the setup soon after the domain goes live. Until the first account exists, anyone who finds the address can create it.

Other Docker hosts

compose.yaml runs Pocket ID on any Linux server with Docker. Put it in a folder of its own, fill in every value marked required and start it with docker compose up -d. The data folder is created next to the file.

  • Synology: in Container Manager, create a project from the file (DSM 7.2 or newer).
  • Proxmox: run it in a VM or an LXC container that has Docker.

3. Behind a reverse proxy

Browsers only create passkeys over HTTPS, and only for the domain in App URL. Opening http://<tower-ip>:1411 shows the pages, but every passkey prompt fails there. So Pocket ID needs a reverse proxy with a certificate in front of it.

Nginx Proxy Manager: a proxy host for your domain, scheme http, the container's IP and port 1411, your certificate with Force SSL on. Under Advanced, larger buffers keep big OIDC responses from failing with "upstream sent too big header":

proxy_busy_buffers_size 512k;
proxy_buffers 4 512k;
proxy_buffer_size 256k;

Trust Proxy: set it to true, or better to the proxy's own address. Without it, the audit log and the rate limiter see every visitor as the proxy. If a second hop sits in front, such as a Cloudflare tunnel container, list both addresses, separated by a comma.

Cloudflare: a tunnel route or an orange-cloud DNS record works without anything special. Pocket ID can also take the sign-in location from Cloudflare's headers instead of a GeoLite database (Cloudflare Location Headers), but only switch that on when every request comes through Cloudflare. Otherwise anyone on your network could send those headers themselves.

4. Connecting an app

In Pocket ID, open OIDC Clients, add one per app and enter the app's callback URL. The app's documentation names it; it usually ends in something like /auth/callback or /oauth2/callback. Pocket ID then shows a client ID and a client secret.

In the app, choose OpenID Connect (sometimes listed as OAuth or SSO) and give it:

Field in the app Value
Issuer or discovery URL https://id.example.com or https://id.example.com/.well-known/openid-configuration
Client ID from Pocket ID
Client secret from Pocket ID
Scopes openid profile email, plus groups if the app maps roles from groups

New clients are restricted to the user groups you allow on them, so add the right group to the client or nobody gets in.

5. Configuration

Setting Default What it does
WebUI 1411 Web interface and OIDC endpoints. The reverse proxy points here.
Data /mnt/user/appdata/pocket-id SQLite database, uploaded logos, GeoLite database.
App URL https://id.example.com Public address with https://, no path. Required.
Encryption Key - Encrypts the signing keys and secrets in the database. Required, masked.
Trust Proxy false true or the proxy addresses, so the real visitor address is logged.
Database Connection String empty Empty means SQLite. postgres://USER:PASSWORD@HOST:5432/DBNAME for PostgreSQL.
MaxMind License Key empty A free GeoLite2 key adds city and country to the audit log.
PUID / PGID 99 / 100 The user the app runs as, nobody:users on Unraid.
Cloudflare Location Headers false Location from Cloudflare's headers instead of GeoLite.
Audit Log Retention Days 90 How long sign-in events are kept.
Disable UI Configuration false true makes the settings page read-only and takes settings from environment variables.
Disable Analytics false true stops the daily heartbeat (version and a random instance ID) to analytics.pocket-id.org.
Disable Version Check false true stops asking GitHub for the latest release.
Log Level info debug, info, warn or error.

Email for sign-up invitations and login codes (SMTP), the look of the login page, LDAP sync and the rest live in Pocket ID's own settings page, not in the template. The upstream documentation lists every variable if you want to set one by hand under Add another Path, Port, Variable.

6. Backups and the encryption key

Everything Pocket ID knows is in the Data folder. Back it up like any other appdata folder with the container stopped, or let the built-in export write everything into one ZIP while it keeps running:

docker exec Pocket-ID /app/pocket-id export --path /app/data/pocket-id-export.zip

The backup is only half of it. The token signing keys inside are encrypted with the Encryption Key, so a restored database without the matching key is useless, and every app would have to be connected again. Keep the key next to the backup, in your password manager.

To change the key, do not just edit the field. Let Pocket ID re-encrypt its data first, then put the new key into the template and apply it:

docker exec -it Pocket-ID /app/pocket-id encryption-key-rotate --new-key <new key>

7. When something goes wrong

Lost your only passkey. Create a one-time sign-in link from the Unraid terminal, valid for an hour, and add a new passkey once you are in:

docker exec Pocket-ID /app/pocket-id one-time-access-token <username or email>

The log says "there's already one instance of Pocket ID running". The container was killed without a clean stop, and the previous run still holds its lock for about a minute. Wait a moment and start it again. A normal stop, restart or update through the Docker tab never runs into this.

"addgroup: gid '100' in use" at the top of the log is harmless. The image tries to create its own group, finds Unraid's users group already on 100 and runs with that one.

The passkey prompt fails or never appears. Check that the browser's address bar shows exactly the domain in App URL, over HTTPS. A different subdomain, the bare IP or plain HTTP all fail.

8. How AI is used here

One knight builds this, and AI is one of the tools I work with, the same way I work with an editor or a compiler. It helps me write code and documentation and it checks my work, and that saves me a good many evenings. It does not make the decisions, though. I read and understand everything before it ships, and if something here breaks, that is on me and not on the tool.

You do not have to take my word for it. The code is open and every release note is written by hand. The issue tracker shows how problems actually get handled, including the ones I got wrong the first time. If you find something that is not right, open an issue and I will look at it.


9. Support this project

Buy me a coffee   PayPal   Donate with crypto

Pocket ID itself is Elias Schneider's and its contributors' work, BSD-2-Clause. What is maintained here is the Unraid template and this page.

Categories

Download Statistics

699,110
Total Downloads
439,185
This Month
265,537
Avg / Month

Total Downloads Over Time

Loading chart...

Related apps

Links

Details

Repository
pocketid/pocket-id:v2
Last Updated2026-10-30
First Seen2026-06-29

Runtime arguments

Web UI
http://[IP]:[PORT:1411]/
Network
bridge
Shell
sh
Privileged
false

Template configuration

WebUIPorttcp

The web interface and the OIDC endpoints. Point your reverse proxy here. Opened directly over http://tower-ip:1411 the pages load, but passkeys fail.

Target
1411
Default
1411
Value
1411
DataPathrw

The SQLite database, uploaded logos and the GeoLite database. Back this folder up together with the encryption key.

Target
/app/data
Default
/mnt/user/appdata/pocket-id
Value
/mnt/user/appdata/pocket-id
App URLVariable

The public address Pocket ID is reached at, with https:// and without a path. Passkeys are bound to this domain, so pick it before the first user signs up. Replace the example with your own domain.

Target
APP_URL
Default
https://id.example.com
Value
https://id.example.com
Encryption KeyVariable

Encrypts the token signing keys and other secrets in the database. At least 16 characters; generate one with: openssl rand -base64 32. Losing it makes the existing data unreadable. To change it later, use the built-in encryption-key-rotate command rather than editing this field.

Target
ENCRYPTION_KEY
Trust ProxyVariable

Set to true behind a reverse proxy so the audit log and rate limits see the visitor's address instead of the proxy's. Instead of true you can list the proxy addresses, separated by commas, for example 192.168.1.20.

Target
TRUST_PROXY
Default
false
Value
false
Database Connection StringVariable

Leave empty for SQLite in the Data folder, which is plenty for a home server. For PostgreSQL: postgres://USER:PASSWORD@HOST:5432/DBNAME. Create the database and the user first.

Target
DB_CONNECTION_STRING
MaxMind License KeyVariable

Optional. With a free GeoLite2 key from maxmind.com, the audit log shows the city and country of each sign-in. Without it, only the IP address is shown.

Target
MAXMIND_LICENSE_KEY
PUIDVariable

User the app runs as. 99 is nobody on Unraid, which owns the appdata share.

Default
99
Value
99
PGIDVariable

Group the app runs as. 100 is users on Unraid.

Default
100
Value
100
Cloudflare Location HeadersVariable

Take the sign-in location from the headers Cloudflare adds instead of GeoLite. Only switch it on when every request reaches Pocket ID through Cloudflare, since anyone else could set those headers themselves.

Target
CLOUDFLARE_LOCATION_HEADERS
Default
false|true
Value
false
Audit Log Retention DaysVariable

How many days the audit log keeps sign-in events.

Target
AUDIT_LOG_RETENTION_DAYS
Default
90
Value
90
Disable UI ConfigurationVariable

When true, application settings such as SMTP come from environment variables only and the settings page is read-only. Leave false to configure everything in the web interface.

Target
UI_CONFIG_DISABLED
Default
false|true
Value
false
Disable AnalyticsVariable

Pocket ID sends a daily heartbeat with its version and a random instance ID to analytics.pocket-id.org, so the developers can count installs. Set to true to switch it off.

Target
ANALYTICS_DISABLED
Default
false|true
Value
false
Disable Version CheckVariable

Set to true to stop asking GitHub for the latest release, which the admin page uses to announce updates.

Target
VERSION_CHECK_DISABLED
Default
false|true
Value
false
Log LevelVariable

How much the container log shows.

Target
LOG_LEVEL
Default
info|debug|warn|error
Value
info