Pocket ID

Simple OpenID Connect and OAuth 2.0 provider that lets users sign in to your applications with passkeys.

Port	1411
Registry	ghcr.io/daemonless/pocket-id
Source	https://github.com/pocket-id/pocket-id
Website	https://pocket-id.org/

Version Tags

Tag	Description	Best For
latest	Official upstream Pocket ID FreeBSD binary (tracks latest release).	Most users — recommended.
pkg	FreeBSD Quarterly. Uses stable, tested packages.	Production stability.
pkg-latest	FreeBSD Latest. Rolling package updates.	Staying current.

Prerequisites

Before deploying, ensure your host environment is ready. See the Quick Start Guide for host setup instructions.

Deployment

Podman Compose

services:
  pocket-id:
    image: "ghcr.io/daemonless/pocket-id:latest"
    container_name: pocket-id
    environment:
      - PUID=1000  # User ID for the application process
      - PGID=1000  # Group ID for the application process
      - TZ=UTC  # Timezone for the container
      - APP_URL=http://localhost:1411  # Public URL of Pocket ID as reached by the browser (passkeys bind to this origin)
      - TRUST_PROXY=false  # Trust X-Forwarded-* headers when running behind a reverse proxy
      # - ENCRYPTION_KEY=  # Key used to encrypt stored secrets (`openssl rand -base64 32`); generated into /config/.env on first start if unset
      # - DB_CONNECTION_STRING=  # Database connection string (defaults to SQLite at data/pocket-id.db under /config, or postgres://user:pass@host:5432/dbname)
      # - MAXMIND_LICENSE_KEY=  # MaxMind license key for automatic GeoLite2 City IP geolocation database downloads
      # - ANALYTICS_DISABLED=  # Disable outbound usage heartbeat to Pocket ID (defaults to true in this image)
    volumes:
      - "/containers/pocket-id:/config"
    ports:
      - "1411:1411"
    # always (not unless-stopped) so FreeBSD's podman rc.d auto-starts it at boot
    restart: always

Save as compose.yaml, then run podman-compose up -d.

AppJail Director

.env:

# .env

DIRECTOR_PROJECT=pocket-id
PUID=1000
PGID=1000
TZ=UTC
APP_URL=http://localhost:1411
TRUST_PROXY=false

appjail-director.yml:

# appjail-director.yml

options:
  - virtualnet: ':<random> default'
  - nat:
services:
  pocket-id:
    name: pocket_id
    options:
      - container: 'args:--pull'
      - expose: '1411:1411 proto:tcp'
    oci:
      user: root
      environment:
        - PUID: !ENV '${PUID}'
        - PGID: !ENV '${PGID}'
        - TZ: !ENV '${TZ}'
        - APP_URL: !ENV '${APP_URL}'
        - TRUST_PROXY: !ENV '${TRUST_PROXY}'
    volumes:
      - pocket-id: /config
volumes:
  pocket-id:
    device: '/containers/pocket-id'

Makejail:

# Makejail

ARG tag=latest

OPTION container=boot
OPTION overwrite=force
OPTION from=ghcr.io/daemonless/pocket-id:${tag}

Save the files above, then run appjail-director up.

Warning

Exposing ports in AppJail means that your service can be reached from remote hosts. If that is not your intention, do not expose the ports and communicate with the service using the jail's IPv4 address or hostname assigned by the virtual network.

To avoid exposing ports, just remove the expose option in your appjail-director.yml or from your command-line arguments.

Bastille

Warning

Bastille's OCI support is experimental. It requires buildah and shares the host network stack (inherit). Mount volumes with --volume HOST JAIL; without it, image-declared volumes are stored under ${bastille_volumesdir}/${jail}.

services:
  pocket-id:
    name: pocket-id
    image: "ghcr.io/daemonless/pocket-id:latest"
    network:
      - mode: host
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=UTC
      - APP_URL=http://localhost:1411
      - TRUST_PROXY=false
    volumes:
      - "/containers/pocket-id:/config"

Save as bastille-compose.yml, then run bastille up. Open http://<server>:1411 from another machine (the server's own browser can't use a published port).

Parameters

Environment Variables

Variable	Default	Description
PUID	1000	User ID for the application process
PGID	1000	Group ID for the application process
TZ	UTC	Timezone for the container
APP_URL	http://localhost:1411	Public URL of Pocket ID as reached by the browser (passkeys bind to this origin)
TRUST_PROXY	false	Trust X-Forwarded-* headers when running behind a reverse proxy
ENCRYPTION_KEY	<ENCRYPTION_KEY>	Key used to encrypt stored secrets (openssl rand -base64 32); generated into /config/.env on first start if unset
DB_CONNECTION_STRING	``	Database connection string (defaults to SQLite at data/pocket-id.db under /config, or postgres://user:pass@host:5432/dbname)
MAXMIND_LICENSE_KEY	<MAXMIND_LICENSE_KEY>	MaxMind license key for automatic GeoLite2 City IP geolocation database downloads
ANALYTICS_DISABLED	``	Disable outbound usage heartbeat to Pocket ID (defaults to true in this image)

Volumes

Path	Description
/config	Persistent configuration (/config/.env) and application data (/config/data)

Ports

Port	Protocol	Description
1411	TCP	Web UI and OIDC provider

First start and setup

Set APP_URL to the exact URL browsers use to reach Pocket ID (for example https://auth.example.com), because WebAuthn passkeys are bound to that domain and require HTTPS outside localhost. When running behind a reverse proxy, set TRUST_PROXY=true.

Open <APP_URL>/setup on first boot to create the initial administrator account and register your passkey.

Encryption key, data, and CLI recovery

If neither ENCRYPTION_KEY nor ENCRYPTION_KEY_FILE is set in the environment or /config/.env on first start, the launcher generates a 32-byte key (openssl rand -base64 32) and stores it in /config/.env (mode 0600). Back up /config: losing ENCRYPTION_KEY makes encrypted fields in the database unreadable.

By default Pocket ID uses an embedded SQLite database at /config/data/pocket-id.db and stores uploads in /config/data/uploads. To use PostgreSQL instead, set DB_CONNECTION_STRING to a postgres://user:password@host:5432/pocket_id URL.

Pocket ID CLI subcommands (such as account recovery when a passkey is lost) run in /config as bsd via podman exec:

podman exec pocket-id pocket-id one-time-access-token <username-or-email>

Pocket ID also binds an internal actor listener on port 1414 for multi-node clustering; single-instance deployments do not need to publish it.

Architectures: amd64, aarch64 User: bsd (UID/GID via PUID/PGID, defaults to 1000:1000) Base: FreeBSD 15.1

---

Need help? Join our Discord community.