Gearberg Docs

Getting Started

Prerequisites

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

docker --version

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 ghcr.io/bit8bytes/gearberg serve

Now, the server is running and you can access the web interface at http://localhost:8080. You can stop the server by pressing Ctrl + C in the terminal.

The previous code does not persist data across restarts, so any changes you make will be lost when the container is stopped or removed. To avoid this, mount a named volume so data persists across restarts: 

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

Gearberg is up and running and ready to use for testing. For actual deployment, see Docker Compose.

Configuration

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.

To check your configuration without starting the server, run: 

docker run -p 8080:8080 ghcr.io/bit8bytes/gearberg check

Flags

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

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

Env vars

Use environment variables for secrets because flags appear in process listings and shell history:

docker run -p 8080:8080 \
  -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

See All Flags & Env Vars for the complete reference.

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.

Deployment

The recommended way to run Gearberg in production is via the official Docker image using Docker Compose.

Docker Compose

Then create compose.yaml, replacing the highlighted line with your domain:

compose.yaml

services:
  gearberg:
    image: ghcr.io/bit8bytes/gearberg
    command:
      - serve
      - -base-url=https://gearberg.example.com
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - gearberg-data:/data
volumes:
  gearberg-data:

Start Gearberg in the background:

docker compose up -d

Add a reverse proxy for HTTPS

For production, place a reverse proxy in front of Gearberg to terminate TLS. Popular options include Caddy (automatic HTTPS with zero config), Traefik (Docker-native with Let's Encrypt), and nginx (battle-tested, manual cert management). Point whichever you choose at localhost:8080.

Reference

All Flags & Env Vars

Flag Env var Default Description
-base-url — http://localhost:8080 Public base URL
-db-dsn DB_DSN file:/data/gearberg.db Database DSN
-storage-dsn STORAGE_DSN file:///data/uploads Storage backend DSN
-port — 8080 Port to listen on
-log-level — error debug, info, warn, error
TLS:Cert and key required when -tls-mode=local
-tls-mode — off off or local
-tls-cert-path — — TLS certificate
-tls-key-path TLS_KEY_PATH — TLS key
Limits
-max-orgs — 1 Maximum number of orgs
-max-categories — 25 Equipment categories per org
-max-manufacturers — 100 Manufacturers per org
-max-locations — 100 Locations per org
-max-storage-bytes — 1073741824 (1 GiB) Storage per org
OIDC: Requires -base-url
-oidc-provider OIDC_<NAME>_PROVIDER — OIDC provider (repeatable)
SMTP:Requires -base-url; omit -smtp-host to disable
-smtp-host — — SMTP hostname
-smtp-port — 587 SMTP port
-smtp-username — — SMTP username
-smtp-password SMTP_PASSWORD — SMTP password
-smtp-from — — From address