Installation

Before you start

Pocket ID requires a secure context, meaning it must be served over HTTPS. This is necessary because Pocket ID uses the WebAuthn API.

You can use a reverse proxy like Caddy or NGINX to serve Pocket ID over HTTPS. Alternatively, you can use a service like Cloudflare to provide HTTPS for your domain.

Installation Methods

Installation with Docker (recommended)

1. Download the docker-compose.yml and .env file:

   curl -o docker-compose.yml https://raw.githubusercontent.com/pocket-id/pocket-id/main/docker-compose.yml curl -o .env https://raw.githubusercontent.com/pocket-id/pocket-id/main/.env.example

2. Edit the .env file so that it fits your needs. See the environment variables section for more information.

3. Run docker compose up -d

Create an admin account on https://<your-app-url>/setup.

Stand-alone Installation

1. Download the latest binary from the releases page.

   Make sure to download the correct version for your operating system. The binary names follow this pattern:

   • pocket-id-<operating-system>-<architecture>
   • Example: pocket-id-linux-amd64

   You can use curl to download the binary directly. For example, for Linux on AMD64 architecture:

   curl -L -o pocket-id-linux-amd64 https://github.com/pocket-id/pocket-id/releases/latest/download/pocket-id-linux-amd64

2. Rename the binary and make it executable:

   mv pocket-id-<operating-system>-<architecture> pocket-id chmod +x pocket-id

3. Download the .env file:

   curl -o .env https://raw.githubusercontent.com/pocket-id/pocket-id/main/.env.example

4. Edit the .env file so that it fits your needs. See the environment variables section for more information.

5. Run the binary:

   ./pocket-id

Create an admin account on https://<your-app-url>/setup.

Offline usage

If you are running Pocket ID in an air-gapped environment or without reliable internet access, you can disable external requests by setting the following environment variables:

• VERSION_CHECK_DISABLED=true: Disables the automatic version check against GitHub.
• ANALYTICS_DISABLED=true: Disables the daily heartbeat request to the analytics server.

Community Installation Methods

[!IMPORTANT] These installation methods are not officially supported, and services may not work as expected.

Podman + Quadlet

For rootless Podman, add the following Quadlet file at ~/.config/containers/systemd/pocket-id.container. For rootful Podman, move it into /etc/containers/systemd/ instead. Also change the WantedBy value default.target to multi-user.target. Go through the environment variables and adjust the values as needed.

Proxmox

Run the helper script as root in your Proxmox shell.

Configuration Paths

• /opt/pocket-id/backend/.env
• /opt/pocket-id/frontend/.env

Unraid

Pocket ID is available as a template on the Community Apps store.

Kubernetes Helm Chart

• A Helm chart maintained by @matslarson is available here.
• A Helm chart maintained by anza-labs here.

NixOS

A pocket-id module is available in NixOS Unstable. It can be enabled by adding the following to your configuration.nix:

For further configuration of the module, see the available settings.

Homebrew

Installation from Source

It's not recommended to install Pocket ID from source unless you know what you're doing. The following instructions are provided for advanced users who want to customize or contribute to the project.

Required tools:

• Node.js >= 22
• Go >= 1.26
• Git

1. Run the following commands:

   # Clone the repo git clone https://github.com/pocket-id/pocket-id cd pocket-id # Checkout latest version git fetch --tags && git checkout $(git describe --tags `git rev-list --tags --max-count=1`) # Build the frontend pnpm --filter pocket-id-frontend install pnpm --filter pocket-id-frontend build # Build the backend cd ../backend/cmd go build -o ../../pocket-id # Create the .env file cd ../../ cp .env.example .env

2. Edit the .env file so that it fits your needs. See the environment variables section for more information.

3. Run the binary:

Create an admin account on https://<your-app-url>/setup.