Container images are published to forgejo.ofkm.us/ofkm/overpass for linux/amd64 and linux/arm64. Each image bundles the overpass daemon and the opctl admin CLI and runs as a non-root user (uid 65532).

Run the control plane

docker run -d --name overpass \
  -p 8443:8443 -p 3023:3023 -p 3024:3024 -p 3025:3025 \
  -v overpass-data:/var/lib/overpass \
  forgejo.ofkm.us/ofkm/overpass:latest

Then open https://localhost:8443/setup, paste the one-time claim code from the container logs, and create the first administrator. The setup page creates the session and guides you to the next steps; opctl is only needed for recovery or scripted administration.

docker logs overpass

Warning

The data directory holds the database and the CA keys — persist it with a named volume (as above) and back it up. The server-managed config directory (settings, roles, SSO connectors, desktops made in the UI) lives at <data_dir>/overpass.d, inside the same volume, so a mounted read-only /etc/overpass.yaml needs no writable /etc. data_dir may point at another container path, but the volume must be mounted at that exact path and be writable by the configured container uid (default 65532); the non-root process cannot repair ownership of a root-owned bind mount or named volume.

Custom uid and gid

Compose creates named volumes through the Docker daemon, so a new volume starts with daemon-owned filesystem metadata; “new” does not mean owned by the application user. PUID and PGID are supported through Compose's user: setting, which defaults to the image's 65532:65532 identity:

services:
  overpass:
    user: "${PUID:-65532}:${PGID:-65532}"
    volumes:
      - overpass-data:/var/lib/overpass

Set PUID and PGID in the shell environment or the Compose .env file. A directory or volume used by data_dir must already be owned or writable by those ids. Defining PUID and PGID only under environment: does not change the process identity.

Run a node agent

The same image runs the node agent — just change the command:

docker run -d --name overpass-node \
  forgejo.ofkm.us/ofkm/overpass:latest \
  node --name web-1 --proxy gate.acme.com:3025 --token <token> --labels env=prod

Compose

services:
  overpass:
    image: forgejo.ofkm.us/ofkm/overpass:latest
    ports:
      - "8443:8443"
      # With --tls-routing, 8443 carries everything and these three are only
      # needed for pre-TLS-routing clients and nodes:
      - "3023:3023"
      - "3024:3024"
      - "3025:3025"
    volumes:
      - overpass-data:/var/lib/overpass
    # Optional fallbacks behind a reverse proxy (YAML values are primary):
    # environment:
    #   OVERPASS_PUBLIC_URL: https://gate.acme.com
    #   OVERPASS_PUBLIC_ADDR: gate.acme.com
    restart: unless-stopped

volumes:
  overpass-data:

Mount a config file at /etc/overpass.yaml to configure everything from a file (see Configuration); server and opctl read it by default.

Container images set OVERPASS_RUNTIME=container in their environment. In-place self-update and fleet update binary swaps are automatically disabled for image deployments; pull a new tag and restart the container to update.

To collect a debug trace, set logging.level: debug in the mounted /etc/overpass.yaml and restart the container, or add --debug to the command. logging.format: json emits machine-readable lines for a collector.

Local image dry run

Container images are assembled by GoReleaser from the release binaries using docker/Dockerfile:

just snapshot