Configuration
Openbeehive is configured entirely through environment variables. This page is the complete reference, grouped exactly as they appear in .env.example.
You can set these variables in your shell, in a .env file alongside the binary, in your docker compose file, or through your hosting platform's secrets manager. The server reads them once at start-up, so changes take effect after a restart.
:::tip Start small
You only need a handful of these to get going. For a single-user home server, set BEEHIVE_DEPLOYMENT_PROFILE=selfhost, a BEEHIVE_SESSION_SECRET, and leave the rest at their defaults. See the Quick start to be running in minutes.
:::
How the deployment profile works
The single most important setting is BEEHIVE_DEPLOYMENT_PROFILE. It chooses sensible defaults for everything else so you don't have to spell out a full stack by hand.
| Profile | Database default | Blob storage default | Intended for |
|---|---|---|---|
selfhost | SQLite (file) | Local filesystem | A single binary, no Docker, one host |
cloud | PostgreSQL | MinIO / S3 | The hosted, multi-tenant deployment |
The profile only sets defaults. Any variable you set explicitly always wins. For example, you can run the selfhost profile but point it at PostgreSQL by setting BEEHIVE_DATABASE_DRIVER and BEEHIVE_DATABASE_DSN yourself.
The two profiles are documented in depth on their own pages: Single binary and Docker. This page focuses on the variables themselves.
Deployment profile
| Variable | Default | Description |
|---|---|---|
BEEHIVE_DEPLOYMENT_PROFILE | selfhost | Selects the preset stack: selfhost or cloud. Sets defaults for database and blob storage. |
HTTP server
| Variable | Default | Description |
|---|---|---|
BEEHIVE_ADDR | :8080 | Address and port the server listens on. Use 127.0.0.1:8080 to bind only to localhost behind a reverse proxy. |
BEEHIVE_PUBLIC_BASE_URL | http://localhost:8080 | The public URL where users reach the app. Used for QR deep links, OIDC redirects and absolute links. Set this to your real domain in production. |
BEEHIVE_PUBLIC_BASE_URL must match the address users actually visit. If it is wrong, QR labels, login redirects and shared links will point to the wrong place.
Embedded web app
The server can serve the SvelteKit PWA itself, so a single binary delivers both the API and the front end.
| Variable | Default | Description |
|---|---|---|
BEEHIVE_SERVE_WEB | true | When true, the server serves the bundled web app. Set false if you host the front end separately. |
BEEHIVE_WEB_DIR | (empty) | Path to the built web assets. Leave empty to use the assets embedded in the binary. |
CORS
Cross-origin settings matter when the web app is served from a different origin than the API.
| Variable | Default | Description |
|---|---|---|
BEEHIVE_CORS_ALLOWED_ORIGINS | * | Comma-separated list of allowed origins. Restrict this to your domain in production. |
BEEHIVE_CORS_ALLOW_CREDENTIALS | true | Whether to allow credentialed cross-origin requests (cookies, auth headers). |
A wildcard origin (*) combined with BEEHIVE_CORS_ALLOW_CREDENTIALS=true is permissive. If you serve the app from a single origin, set BEEHIVE_CORS_ALLOWED_ORIGINS to that exact origin.
Sync
| Variable | Default | Description |
|---|---|---|
BEEHIVE_NODE_ID | server | Identifier for this node in the sync protocol. Used by the Hybrid Logical Clock to label events. Keep it stable and unique per server. |
The conflict-free sync engine (HLC plus per-field last-writer-wins and add-wins OR-Sets) needs each participant to have a stable identity. Changing BEEHIVE_NODE_ID on a live server is not recommended.
Database
| Variable | Default | Description |
|---|---|---|
BEEHIVE_DATABASE_DRIVER | from profile | Database engine: postgres, mysql or sqlite. |
BEEHIVE_DATABASE_DSN | from profile | Connection string for the chosen driver (see below). |
Example DSNs by driver:
# SQLite (selfhost default) — a single file with write-ahead logging
BEEHIVE_DATABASE_DRIVER=sqlite
BEEHIVE_DATABASE_DSN="file:openbeehive.db?_pragma=journal_mode(WAL)"
# PostgreSQL (cloud default)
BEEHIVE_DATABASE_DRIVER=postgres
BEEHIVE_DATABASE_DSN="postgres://user:pass@host:5432/db?sslmode=disable"
# MySQL
BEEHIVE_DATABASE_DRIVER=mysql
BEEHIVE_DATABASE_DSN="user:pass@tcp(host:3306)/openbeehive?parseTime=true"
For driver choice, tuning and migration notes, see Databases.
Blob storage
Photos and other attachments are stored as blobs, either on the local filesystem or in an S3-compatible object store.
| Variable | Default | Description |
|---|---|---|
BEEHIVE_BLOB_BACKEND | from profile | Storage backend: fs (local filesystem) or minio (MinIO / S3). |
BEEHIVE_BLOB_DIR | ./data/blobs | Directory for blobs when BEEHIVE_BLOB_BACKEND=fs. |
BEEHIVE_MINIO_ENDPOINT | (empty) | Host and port of the MinIO / S3 endpoint. |
BEEHIVE_MINIO_ACCESS_KEY | (empty) | Access key for the object store. |
BEEHIVE_MINIO_SECRET_KEY | (empty) | Secret key for the object store. |
BEEHIVE_MINIO_BUCKET | (empty) | Bucket name where blobs are stored. |
BEEHIVE_MINIO_USE_SSL | (empty) | Set true to connect to the endpoint over HTTPS. |
The MINIO_* variables are only used when BEEHIVE_BLOB_BACKEND=minio. For full guidance, see Storage.
Session and authentication
| Variable | Default | Description |
|---|---|---|
BEEHIVE_SESSION_SECRET | (empty) | Secret used to sign session cookies. Generate one with openssl rand -base64 32. Required in production. |
BEEHIVE_SESSION_TTL | 720h | How long a session lasts before re-authentication is required (e.g. 720h is 30 days). |
Always set a strong, unique BEEHIVE_SESSION_SECRET and keep it private. If it leaks or changes, all existing sessions are invalidated.
Email, password & onboarding
Built-in accounts for multi-user instances without an external identity provider. The first account created on a fresh instance becomes the admin. See Authentication.
| Variable | Default | Description |
|---|---|---|
BEEHIVE_PASSWORD_AUTH | on for cloud, off for selfhost | Enable email/password sign-up and sign-in. |
BEEHIVE_REGISTRATION | true | Open self-registration. Set to false for an invite-only instance: beyond the first-run admin, accounts can only be created via invite links, and the sign-in screen shows an invite-only notice. |
BEEHIVE_EMAIL_VERIFICATION | false | Require email confirmation before a new account can sign in. |
BEEHIVE_SMTP_HOST | (empty) | SMTP server for verification/invite emails. If empty, links are written to the log instead. |
BEEHIVE_SMTP_PORT | 587 | SMTP port. |
BEEHIVE_SMTP_USER | (empty) | SMTP username. |
BEEHIVE_SMTP_PASS | (empty) | SMTP password. |
BEEHIVE_SMTP_FROM | Openbeehive <no-reply@openbeehive.org> | From address for outgoing mail. |
Demo tenant
Installs a showcase demo account and tenant. Off by default — see Demo mode.
| Variable | Default | Description |
|---|---|---|
BEEHIVE_DEMO | false | Install a demo account + tenant (15 hives across 4 apiaries, reset hourly). Implies BEEHIVE_PASSWORD_AUTH=true. |
BEEHIVE_DEMO_EMAIL | demo@app.openbeehive.org | Demo account email. |
BEEHIVE_DEMO_PASSWORD | demo | Demo account password. |
WebAuthn / passkeys
Optional passwordless authentication using passkeys.
| Variable | Default | Description |
|---|---|---|
BEEHIVE_WEBAUTHN_ENABLED | false | Enables WebAuthn / passkey login. |
BEEHIVE_WEBAUTHN_RP_ID | (empty) | Relying Party ID, normally your bare domain (e.g. openbeehive.org). |
BEEHIVE_WEBAUTHN_RP_ORIGINS | (empty) | Allowed origins for WebAuthn ceremonies, e.g. your full app URL. |
BEEHIVE_WEBAUTHN_RP_DISPLAY_NAME | (empty) | Human-readable name shown to users during registration. |
OIDC providers
Sign-in through external identity providers via OpenID Connect. Multiple providers can be enabled at once.
| Variable | Default | Description |
|---|---|---|
BEEHIVE_OIDC_PROVIDERS | (empty) | Comma-separated list of enabled providers, e.g. google,keycloak. |
BEEHIVE_OIDC_REDIRECT_URL | (empty) | The callback URL providers redirect to after login. |
Each provider then has its own variables. For example:
# Google
BEEHIVE_OIDC_GOOGLE_ISSUER=https://accounts.google.com
BEEHIVE_OIDC_GOOGLE_CLIENT_ID=...
BEEHIVE_OIDC_GOOGLE_CLIENT_SECRET=...
BEEHIVE_OIDC_GOOGLE_SCOPES=openid,email,profile
# Keycloak
BEEHIVE_OIDC_KEYCLOAK_ISSUER=https://id.example.com/realms/beekeepers
BEEHIVE_OIDC_KEYCLOAK_CLIENT_ID=...
BEEHIVE_OIDC_KEYCLOAK_CLIENT_SECRET=...
:::tip Single-user, no login
For a personal self-hosted instance you can skip login entirely. Leave BEEHIVE_OIDC_PROVIDERS empty and set BEEHIVE_WEBAUTHN_ENABLED=false. The app then runs in single-user mode with no sign-in step.
:::
For provider set-up walkthroughs, redirect URLs and security advice, see Authentication.
A minimal selfhost example
BEEHIVE_DEPLOYMENT_PROFILE=selfhost
BEEHIVE_ADDR=:8080
BEEHIVE_PUBLIC_BASE_URL=https://hive.example.com
BEEHIVE_SESSION_SECRET=replace-with-openssl-rand-base64-32
# Database and blob storage use selfhost defaults (SQLite + local files)
# No OIDC, no WebAuthn — single-user mode
That is all a single beekeeper needs. Add a reverse proxy in front for HTTPS and you are ready to keep records.