Prerequisites

These steps require Docker. Open a terminal and verify it is installed by running:

docker --version

You should see something like this:

Docker version 27.4.0, build bde2b89

If Docker is not installed, you will see something like "docker: command not found". In that case, install Docker first and come back here.

Quick Start

Start the server:

docker run -p 8080:8080 -v gearberg-data:/data ghcr.io/bit8bytes/gearberg serve

You should see something like this:

Gearberg is running now. Open http://localhost:8080

Open http://localhost:8080 in your browser. If this is your first time, go to http://localhost:8080/signup to create an account. When you are done, switch back to the terminal and press Ctrl + C to stop the server.

Quick Start showed you how to run Gearberg temporarily. To keep it running in the background, choose one of these approaches:

1. Docker: A single command to get started quickly.
2. Docker Compose: Recommended for production; declarative, version-controlled, and easy to extend.
3. Raspberry Pi: Run Gearberg on a low-cost, always-on device in your local network.

Docker

Run Gearberg in the background with the --detach flag:

docker run -d --restart unless-stopped -p 8080:8080 -v gearberg-data:/data ghcr.io/bit8bytes/gearberg serve

Docker Compose

Docker Compose is a tool for defining and running multi-container Docker applications using a single YAML configuration file. You declare your services, networks, and volumes in that file, then start everything with docker compose up.

A YAML file is a plain-text configuration file that's easy for humans to read and write. It uses indentation and simple key-value pairs (like name: Gearberg) to organize settings. No special symbols or code required.

Create compose.yaml:

compose.yaml

services:

  gearberg:

    image: ghcr.io/bit8bytes/gearberg

    command:

      - serve

    restart: unless-stopped

    ports:

      - "8080:8080"

    volumes:

      - gearberg-data:/data

volumes:

  gearberg-data:

In the same folder, run the following command to start the server:

docker compose up -d

To stop the server, run:

docker compose down

Raspberry Pi

A Raspberry Pi running Raspberry Pi OS is a great way to host Gearberg on a low-cost, always-on device in your local network. The setup uses the same compose.yaml as above.

SSH into your Raspberry Pi and run the official Docker install script:

curl -fsSL https://get.docker.com | sh

Then add your user to the docker group so you can run Docker without sudo:

sudo usermod -aG docker $USER

Log out and back in for the change to take effect. Then create the compose.yaml file on your Raspberry Pi (see the Docker Compose section above for the contents) and run:

docker compose up -d

Gearberg is now running and will restart automatically whenever the Pi reboots. Open a browser on any device in your local network and go to http://<raspberry-pi-ip>:8080.

Overview

Gearberg is configured via command-line flags and environment variables. Flags take precedence over env vars. All configuration errors are reported on startup and the server will not start with invalid or missing required values. See All Flags & Env Vars for the complete reference.

The examples below show how to configure Gearberg when starting it. Any change requires a restart with the updated command.

Flags

Use flags for non-sensitive settings (e.g. log-level):

docker run -p 8080:8080 ghcr.io/bit8bytes/gearberg serve -log-level=info

You can configure multiple flags (e.g. log-level and port) by separating them with spaces:

docker run -p 9090:9090 ghcr.io/bit8bytes/gearberg serve -log-level=error -port=9090

Env vars

Use environment variables for secrets (e.g. SMTP password):

docker run -p 8080:8080 -e SMTP_PASSWORD=secret ghcr.io/bit8bytes/gearberg serve

Avoid using secrets as flags because flags appear in process listings and shell history.

OIDC

By default, Gearberg uses email and password login, which requires no configuration. To add Single Sign-On (SSO), configure one or more OpenID Connect (OIDC) providers. Currently, only the Authentik provider is supported.

Setup checklist

1. In your OIDC provider, create an OAuth2/OIDC application and note the issuer URL, client ID, and client secret.
2. Set the callback URL in your OIDC provider to <base-url>/auth/oidc/<name>/callback, where <base-url> matches the -base-url flag and <name> is the provider name you choose e.g. authentik.
3. Start Gearberg with -base-url and the OIDC provider configured via env var (see below).

Quick start (flag, local testing only)

The -oidc-provider flag is the fastest way to get OIDC running locally. Add -log-level warn to surface OIDC warnings and errors in the server log.

docker run -p 9000:9000 \

  -v gearberg-data:/data \

  ghcr.io/bit8bytes/gearberg serve \

  -base-url http://localhost:9000 \

  -log-level warn \

  -oidc-provider authentik,issuer=https://authentik.example.com/application/o/gearberg/,client-id=YOUR_CLIENT_ID,client-secret=YOUR_CLIENT_SECRET

Flags appear in process listings and shell history. Do not use this approach in production.

Production (env var)

Use the OIDC_<NAME>_PROVIDER env var in production, where <NAME> is the provider name.

OIDC_<NAME>_PROVIDER=<name>,issuer=<URL>,client-id=<ID>,client-secret=<SECRET>

docker run -p 9000:9000 \

  -v gearberg-data:/data \

  -e OIDC_AUTHENTIK_PROVIDER=authentik,issuer=https://authentik.example.com/application/o/gearberg/,client-id=YOUR_CLIENT_ID,client-secret=YOUR_CLIENT_SECRET \

  ghcr.io/bit8bytes/gearberg serve \

  -base-url http://localhost:9000

Repeat the env var for multiple providers.

require-email-verified

By default, Gearberg only allows login if the provider has verified the user's email address. If your provider does not set email_verified: true in the ID token, you can disable this check by appending require-email-verified=false to the provider string. We recommend doing this only in local development. In production it allows anyone with an account in your OIDC provider to log in, regardless of whether their email was verified.

OIDC_<NAME>_PROVIDER=<name>,issuer=<URL>,client-id=<ID>,client-secret=<SECRET>,require-email-verified=false

SMTP

Gearberg uses SMTP to send transactional emails such as password reset links and invitations. SMTP is optional. When -smtp-host is omitted, emails are silently discarded and no mail is sent. -base-url is required when SMTP is enabled. It is used to build the links inside emails.

Pass the password via the SMTP_PASSWORD env var and not the flag.

Docker run example

docker run -p 8080:8080 \

  -v gearberg-data:/data \

  -e SMTP_PASSWORD=secret \

  ghcr.io/bit8bytes/gearberg serve \

  -base-url https://gearberg.example.com \

  -smtp-host smtp.example.com \

  -smtp-username gearberg@example.com \

  -smtp-from gearberg@example.com

-smtp-port defaults to 587.