Deploying Pocket ID on Dokploy: Complete Tutorial

Core Features#

• Completely Passwordless: Uses Passkey technology (WebAuthn), eliminating traditional password security vulnerabilities
• OIDC Standard Support: Compatible with all OIDC-supporting applications like Immich, Nextcloud, Grafana, etc.
• Self-Hosting Friendly: Lightweight design, uses SQLite or PostgreSQL for data storage
• Hardware Key Support: Supports FIDO2 hardware security keys like YubiKey
• Simple and Efficient: More lightweight and easier to configure than enterprise solutions like Keycloak or Authelia

Technology Stack#

• Backend: Go (high performance, low resource usage)
• Frontend: Svelte + TypeScript
• Database: SQLite (default) or PostgreSQL

Prerequisites#

• A server with Dokploy installed
• A domain name (for HTTPS access, Passkey must be used in HTTPS environments)
• At least 512MB available memory

Creating a Compose Service#

1. Log in to the Dokploy management panel
2. Select the corresponding project (or create a new one)
3. Click “Create Service” → Select “Template”
4. Search for and select the Pocket ID template

Docker Compose Configuration#

:::caution Important: Version Issue Dokploy’s default template may use the v1 version, which is outdated. You must modify the image to ghcr.io/pocket-id/pocket-id:v2, otherwise you may encounter compatibility issues and missing features. :::

Paste the following content in the Compose configuration:

1
services:
2
  pocket-id:
3
    image: ghcr.io/pocket-id/pocket-id:v2  #also just this here to modify，because template not updated is v1 version
4
    restart: unless-stopped
5
    environment:
6
      - APP_URL
7
      - TRUST_PROXY
8
      - ENCRYPTION_KEY
9
    volumes:
10
      - pocket-id-data:/app/data
11
    healthcheck:
12
      test: [ "CMD", "/app/pocket-id", "healthcheck" ]
13
      interval: 1m30s
14
      timeout: 5s
15
      retries: 2
16
      start_period: 10s
17

18
volumes:
19
  pocket-id-data:

APP_URL#

The full access address of the application, must use HTTPS.

1
APP_URL=https://pocketid.your.domain

Examples:

• Using a custom domain: https://pocketid.example.com
• Using Dokploy’s auto-generated domain: https://berohost-pocketid-0da961-5-175-220-72.traefik.me

TIP

If using Dokploy’s auto-generated domain, you can view the complete URL in the Domains tab.

ENCRYPTION_KEY#

The key used to encrypt sensitive data. Set it to CHANGEME on first deployment, and the system will automatically generate it.

1
ENCRYPTION_KEY=CHANGEME

To manually generate a key (optional), use the following command:

1
openssl rand -base64 32

TRUST_PROXY#

Enable reverse proxy support. Dokploy uses Traefik as the reverse proxy by default, so this needs to be set to true.

1
TRUST_PROXY=true

Starting the Service#

1. On the Compose service page, click the “Deploy” button
2. Wait for image pulling and container startup
3. Check the “Logs” tab to confirm the service has started normally

Accessing the Setup Page#

After the service starts, visit:

1
https://pocketid.your.domain/setup

Creating an Administrator Account#

1. Username: Enter the administrator username (email format recommended, e.g., admin@example.com)
2. Display Name: Display name
3. Create Passkey: Click and follow browser prompts to create a Passkey

:::note Passkey Creation Methods

• Desktop Browser: Can choose to use system password manager (like Windows Hello, macOS Touch ID) or hardware key
• Mobile Device: Can use biometric authentication (fingerprint/face recognition)
• Cross-Device: Use 1Password, Bitwarden, and other password managers to sync Passkeys :::

After completion, you will be automatically logged into the admin panel.

Adding Additional Passkeys#

Visit https://pocketid.your.domain/settings/account

Click the “Add Passkey” button below.

It’s generally recommended to add one more as a backup.

Assigning User Groups#

Creating an OIDC Client in Pocket ID#

1. Log in to the Pocket ID admin panel
2. Go to the “Clients” page
3. Click “Create Client”

Fill in the following information:

1
Client Name: Linkding
2
Redirect URIs: https://linkding.your.domain/oidc/callback/

:::tip Tips

• Callback URL can also be left empty; it will be auto-filled on first login
• Optionally upload a Logo icon for display on the login page :::

After creation, copy and save the following credential information:

• Client ID: e.g., abc123def456
• Client Secret: e.g., secret_xyz789

Configuring OIDC in Linkding#

Assuming you’re deploying Linkding with Docker Compose, add the following to the service’s environment variables (.env file or Dokploy’s Environment tab):

1
# Enable OIDC login
2
LD_ENABLE_OIDC=True
3

4
# Pocket ID client credentials
5
OIDC_RP_CLIENT_ID=<Client ID copied from Pocket ID>
6
OIDC_RP_CLIENT_SECRET=<Client Secret copied from Pocket ID>
7

8
# OIDC endpoint configuration
9
OIDC_OP_AUTHORIZATION_ENDPOINT=https://pocketid.your.domain/authorize
10
OIDC_OP_TOKEN_ENDPOINT=https://pocketid.your.domain/api/oidc/token
11
OIDC_OP_USER_ENDPOINT=https://pocketid.your.domain/api/oidc/userinfo
12
OIDC_OP_JWKS_ENDPOINT=https://pocketid.your.domain/.well-known/jwks.json
13

14
# PKCE support (adjust based on actual needs, default is True)
15
OIDC_USE_PKCE=False
16

17
# SSL certificate verification (set to False for self-signed certificates)
18
OIDC_VERIFY_SSL=True
19

20
# Optional: Custom username field (defaults to email)
21
# OIDC_USERNAME_CLAIM=preferred_username

Complete Parameter Description:

Redeploying Linkding#

After saving the environment variables, click “Redeploy” in Dokploy to redeploy the Linkding service.

After deployment completes, visit the Linkding login page and you will see the “Sign in with OIDC” button.

General Integration Instructions#

For other OIDC-supporting applications, you typically need the following information:

1
Issuer / Discovery URL: https://pocketid.your.domain
2
Authorization Endpoint: https://pocketid.your.domain/authorize
3
Token Endpoint: https://pocketid.your.domain/api/oidc/token
4
UserInfo Endpoint: https://pocketid.your.domain/api/oidc/userinfo
5
JWKS Endpoint: https://pocketid.your.domain/.well-known/jwks.json
6
Client ID: Obtained from Pocket ID
7
Client Secret: Obtained from Pocket ID
8
Scopes: openid profile email

:::note Endpoint Information Most OIDC applications support automatic discovery configuration, requiring only the Issuer URL (https://pocketid.your.domain). If manual configuration is needed, use the complete endpoint paths above. :::

:::tip Common Application Integration

• Immich: Supports OIDC, configuration path at Settings → OAuth
• Grafana: In the [auth.generic_oauth] section of the config file
• Nextcloud: Install the “OpenID Connect user backend” plugin
• Portainer: Business Edition supports OIDC :::

Data Persistence#

All Pocket ID data is saved in the pocket-id-data volume, including:

• SQLite database (users, clients, Passkey information)
• Configuration files
• Session data

Backup Methods#

Using Dokploy’s Built-in Backup

1. Go to the service’s “Backups” tab
2. Configure backup destination (e.g., S3, local path)
3. Set backup schedule (daily backup recommended)

:::warning Security Tips

• Backup files contain encryption keys and user authentication information; keep them secure
• Regularly test the backup recovery process to ensure data availability
• If using PostgreSQL, backup the database separately :::

1. Enforce HTTPS#

Ensure APP_URL uses HTTPS; Passkey cannot be used in non-HTTPS environments.

2. Restrict Admin Panel Access#

If only specific IPs need to access the admin panel, you can configure an IP whitelist in Traefik.

Q: What if Passkey creation fails?#

A: Check the following:

1. Confirm the access address uses HTTPS
2. Does the browser support WebAuthn (Chrome 67+, Firefox 60+, Safari 14+)
3. Check the browser console for error messages

Q: What if I forget the administrator account?#

A: If you cannot log in, you can reset through the database:

See details at https://pocket-id.org/docs/troubleshooting/account-recovery

CAUTION

It’s recommended to configure multiple Passkeys for the administrator account to avoid single points of failure.