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 two 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/password login which does not require any configuration. To extend it with SSO, configure one or more OIDC providers. Currently, only the Authentik provider is supported. -base-url is required when OIDC is enabled. It is used as the redirect URI sent to the identity provider.

Env var format

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

<NAME> becomes the provider name. Repeat the variable for multiple providers. Flags take precedence over env vars. For authentik, the env var would look like this: OIDC_AUTHENTIK_PROVIDER.

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.