Skip to main content

Configuration

Hive-Pal is configured entirely through environment variables on the app container. This page is the complete reference.

Required​

VariableDescription
DATABASE_URLPostgreSQL connection string, e.g. postgres://postgres:postgres@postgres:5432/beekeeper
BETTER_AUTH_SECRETSecret used to sign Better Auth sessions/cookies. Use 32+ random chars: openssl rand -base64 32
BETTER_AUTH_URLPublic base URL where the app and /api/auth/* are served, e.g. https://hive.example.com
FRONTEND_URLPublic URL of the app. Used in email links and as a trusted auth origin
ADMIN_EMAILInitial admin account email (seeded on startup)
ADMIN_PASSWORDInitial admin password (plaintext; hashed on first run)
Single-container deployments

Because the app serves the frontend and API from the same origin, you do not need to set VITE_API_URL or API_URL for the standard single-container deployment. Those are only relevant for split frontend/backend or local development setups.

Authentication​

Hive-Pal authenticates with Better Auth. Beyond the required BETTER_AUTH_SECRET and BETTER_AUTH_URL:

VariableDescriptionDefault
PASSKEY_RP_IDWebAuthn relying-party ID for passkeys. Set to your domain in productionlocalhost
COOKIE_DOMAINSet when frontend and backend share a parent domain across subdomains (e.g. .example.com)—
ALLOWED_ORIGINSComma-separated list of allowed CORS origins—
JWT_SECRETSigns short-lived tokens for iCal calendar feeds, HiveScale proxy requests, and local-storage download URLs (see note below). Generate with openssl rand -base64 32—
JWT_SECRET is not for login

JWT_SECRET is not used for user authentication (that's Better Auth). It only signs short-lived tokens for iCal calendar feeds, HiveScale proxy requests, and local-storage download URLs. Set it only if you use those features.

Single sign-on (OIDC / Authentik)​

Hive-Pal can sign users in through any OpenID Connect provider. It has been designed with Authentik in mind. SSO is enabled as soon as the issuer (or discovery URL), client ID and client secret are set.

VariableDescriptionDefault
OIDC_ISSUERIssuer URL of the provider. Authentik: https://auth.example.com/application/o/<app-slug>/—
OIDC_DISCOVERY_URLFull discovery URL; overrides the one derived from OIDC_ISSUER<OIDC_ISSUER>/.well-known/openid-configuration
OIDC_CLIENT_IDClient ID of the OAuth2/OpenID provider—
OIDC_CLIENT_SECRETClient secret of the OAuth2/OpenID provider—
OIDC_PROVIDER_IDInternal provider ID, used in the redirect URIauthentik
OIDC_SCOPESRequested scopes (space- or comma-separated)openid profile email
OIDC_BUTTON_LABELText of the login buttonSign in with SSO
OIDC_ALLOW_SIGNUPCreate a Hive-Pal account on the first SSO login when no account with that email exists. With false, only existing users can sign in via SSOtrue
DISABLE_LOCAL_LOGINDisable password, magic-link and passkey sign-in as well as email sign-up, so that only SSO remains. Ignored while SSO is not configuredfalse

How users are matched: accounts are matched by email address (case-insensitive). The provider's email claim is trusted even when it doesn't send email_verified=true, so make sure users can't change their own email address in Authentik.

When SSO is linked implicitly to an existing account whose email was never verified (typically an account registered with a password), the password, passkeys and sessions of that account are removed. This prevents someone from pre-registering an account with another person's email and keeping access after that person's first SSO login. The owner keeps all data and can still set a password again via "Forgot password". Accounts with a verified email (older accounts, magic-link users), and accounts linked by their owner from Settings → Linked accounts, keep their password. Google and Facebook sign-in (see below) follow the same rules.

Users created through SSO, Google or Facebook are asked once to accept the privacy policy after their first login.

Authentik setup​

  1. In Authentik, go to Applications → Providers and create an OAuth2/OpenID Provider:

    • Client type: Confidential
    • Redirect URIs (strict): <BETTER_AUTH_URL>/api/auth/callback/authentik, e.g. https://hive.example.com/api/auth/callback/authentik. If you changed OIDC_PROVIDER_ID, use that value instead of authentik.
    • Scopes: keep the default openid, email and profile mappings.
  2. Create an Application that uses this provider and note its slug. Bind users or groups to it to control who may sign in.

  3. Configure Hive-Pal:

    OIDC_ISSUER=https://auth.example.com/application/o/<app-slug>/
    OIDC_CLIENT_ID=<client id>
    OIDC_CLIENT_SECRET=<client secret>
    OIDC_BUTTON_LABEL="Sign in with Authentik"
    # OIDC_ALLOW_SIGNUP=false # only allow existing Hive-Pal users
    # DISABLE_LOCAL_LOGIN=true # SSO only
  4. Restart Hive-Pal. The login page now shows the SSO button.

tip

Keep local login enabled until you have confirmed that SSO works. Users with ADMIN_EMAIL get the admin role no matter how they sign in.

Google and Facebook sign-in​

Each provider is enabled as soon as its client ID and secret are set. The login and registration pages then show a Continue with Google / Continue with Facebook button, and users can link or unlink these accounts under Settings → Linked accounts. Both can be used alongside password login and OIDC SSO.

VariableDescriptionDefault
GOOGLE_CLIENT_IDOAuth client ID from the Google Cloud console—
GOOGLE_CLIENT_SECRETOAuth client secret—
FACEBOOK_CLIENT_IDFacebook app ID—
FACEBOOK_CLIENT_SECRETFacebook app secret—

Redirect URIs to register with the provider:

  • Google: <BETTER_AUTH_URL>/api/auth/callback/google
  • Facebook: <BETTER_AUTH_URL>/api/auth/callback/facebook

Accounts are matched by email address, as with OIDC. Google sign-in only links to an existing account when Google reports the address as verified. Facebook sends only confirmed addresses but never says so, so Hive-Pal trusts the email Facebook returns. Users whose Facebook account has no email address can't sign in with it.

Google setup​

  1. In the Google Cloud console, configure the OAuth consent screen (scopes openid, email, profile).
  2. Create an OAuth client ID of type Web application and add the redirect URI above under Authorized redirect URIs.
  3. Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET and restart Hive-Pal.

Facebook setup​

  1. In Meta for Developers, create an app with the Authenticate and request data from users with Facebook Login use case, and add the email permission.
  2. Under Facebook Login → Settings, add the redirect URI above to Valid OAuth Redirect URIs.
  3. Copy the App ID and App secret from App settings → Basic into FACEBOOK_CLIENT_ID and FACEBOOK_CLIENT_SECRET and restart Hive-Pal. The app must be switched to Live mode before people outside your developer team can sign in.
  4. Before going Live, Facebook asks for a Privacy Policy URL and a User data deletion URL under App settings → Basic. Use <FRONTEND_URL>/privacy-policy and choose Data deletion instructions URL with <FRONTEND_URL>/data-deletion. Both pages name the hivepal.app operator and contact address, so self-hosted instances should point Facebook at their own pages instead.

AI assistants (MCP)​

Hive-Pal serves an MCP endpoint at <BETTER_AUTH_URL>/api/mcp and acts as the OAuth server MCP clients sign in through (see Connecting AI assistants).

VariableDescriptionDefault
MCP_ENABLEDSet to false to turn off the MCP endpoint and the OAuth providertrue

MCP requires BETTER_AUTH_URL to be https:// (plain http:// works only on localhost), so it is switched off automatically on deployments served over plain http. If a reverse proxy sits in front of Hive-Pal, it must also forward /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server and /.well-known/openid-configuration to the backend.

Email​

Email powers magic-link sign-in and password-reset messages. Hive-Pal supports Resend or SMTP and auto-selects based on what's configured. Without email, password and passkey login still work, but magic links and password resets do not.

VariableDescription
MAIL_PROVIDERForce a provider: resend, smtp, or none. Auto-selects if unset
FROM_EMAILSender address for outgoing mail
RESEND_API_KEYAPI key for the Resend provider
SMTP_HOSTSMTP server hostname
SMTP_PORTSMTP server port (e.g. 587 or 465)
SMTP_USERSMTP username
SMTP_PASSSMTP password (for Gmail, use an App Password)
SMTP_SECUREtrue for port 465 (SSL), false for 587 (TLS)
SMTP_REJECT_UNAUTHORIZEDReject invalid TLS certs. Default true; set false for self-signed certs

File Storage​

Hive-Pal stores uploaded audio recordings and photos in either the local filesystem or S3-compatible object storage. Choose with STORAGE_TYPE.

VariableDescriptionDefault
STORAGE_TYPElocal or s3s3
STORAGE_LOCAL_PATHDirectory for local storage. In Docker this is backed by the uploads volume/data/uploads
AUDIO_MAX_FILE_SIZEMax request size for audio uploads, in bytes52428800 (50 MB)
INSPECTION_AUDIO_MAX_FILE_SIZEMax size of a single inspection recording, in bytes. A recording must fit under both limits, so with the defaults the effective limit is 10 MB10485760 (10 MB)
BACKEND_PUBLIC_URLPublic URL of the app, used to build absolute download links for locally stored files. Needed when something outside the container downloads files, such as a pull-mode AI worker—

Local storage​

The simplest option — no external services. Mount a volume at /data/uploads:

STORAGE_TYPE=local
STORAGE_LOCAL_PATH=/data/uploads

Download URLs are signed, time-limited paths (HMAC-SHA256 with JWT_SECRET), so they behave like S3 pre-signed URLs.

S3-compatible storage​

Use AWS S3, MinIO, or any S3-compatible service:

STORAGE_TYPE=s3
S3_ENDPOINT=https://s3.us-east-1.amazonaws.com # or your MinIO endpoint
S3_REGION=us-east-1
S3_BUCKET=hivepal-uploads
S3_ACCESS_KEY_ID=your_key
S3_SECRET_ACCESS_KEY=your_secret

HiveScale Integration​

Hive-Pal can proxy live data from a separate HiveScale backend.

VariableDescription
HIVESCALE_API_BASE_URLBase URL of the HiveScale backend
HIVESCALE_SERVICE_API_KEYShared service key used by Hive-Pal to call HiveScale
JWT_SECRETSigns the per-user tokens Hive-Pal forwards to HiveScale

The HIVESCALE_SERVICE_API_KEY value must match HIVEPAL_SERVICE_API_KEY on the HiveScale backend, and JWT_SECRET must match HiveScale's HIVEPAL_JWT_SECRET so it can verify the forwarded user tokens. HiveScale remains the source of truth for measurements, device roles, off-grid telemetry, and calibration; Hive-Pal only proxies authenticated user requests. See the HiveScale guide.

AI (Voice Inspections & Assistant)​

Voice inspections (transcribing recordings and drafting inspection fields from them) and the Apiary Assistant need a separate AI service: the ghcr.io/martinhrvn/hivepal-ai image, built from apps/ai-app. The setup steps are in Docker Setup → Enabling Voice Inspections. This section lists the variables on the app container.

VariableDescriptionDefault
AI_ENABLEDSet to true to turn on AI analysis and the Assistant. Otherwise both return "AI is disabled"—
AI_PROCESSING_MODEHow audio jobs reach the AI service: push (the app calls the AI service over HTTP), pull (a worker polls the app for jobs) or auto (pull, but the app pushes any job no worker has claimed after AI_PULL_FALLBACK_MINUTES)push
AI_SERVICE_BASE_URLURL of the AI service, used by push mode and the Assistanthttp://hivepal-ai:8008
AI_API_KEYShared secret sent as a Bearer token to the AI service. Must match AI_API_KEY on the AI service. In push mode, jobs stay pending until it is set—
AI_REQUEST_TIMEOUT_MSTimeout for calls to the AI service, in milliseconds300000 (5 min)
AI_PULL_FALLBACK_MINUTESIn auto mode, how long a job waits for a worker before the app pushes it10
WORKER_JOB_LEASE_MSHow long a pull worker holds a claimed job before it is requeued. Raise it if long recordings take longer than this to transcribe300000 (5 min)
OLLAMA_MODELModel the Assistant asks the AI service to use. If unset, the AI service uses its own default—
Pull mode and local storage

A pull worker downloads recordings from the app. With STORAGE_TYPE=local, set BACKEND_PUBLIC_URL to a URL the worker can reach, and set JWT_SECRET, which signs the download links. Otherwise the worker receives a relative link it cannot download. With S3 the worker gets a pre-signed S3 URL instead.

Error Tracking (Optional)​

Configure Sentry to monitor errors in production.

VariableDescription
SENTRY_DSNBackend Sentry DSN
SENTRY_ENVIRONMENTBackend environment label (e.g. production)
VITE_SENTRY_DSNFrontend Sentry DSN
VITE_SENTRY_ENVIRONMENTFrontend environment label

Other​

VariableDescriptionDefault
NODE_ENVRuntime modeproduction

Best Practices​

  • Never commit secrets to version control — use an .env file or your orchestrator's secret store.
  • Generate BETTER_AUTH_SECRET with openssl rand -base64 32 and keep it stable; changing it invalidates existing sessions.
  • Set BETTER_AUTH_URL, FRONTEND_URL, and PASSKEY_RP_ID to your real public domain before going live. BETTER_AUTH_URL also determines the SSO redirect URI.
  • Configure email so users can reset passwords and use magic links.