Configuration
HomeBranch is configured entirely through environment variables. Below is the complete
reference for all three services.
Authentication service
The authentication service manages user accounts, password hashing, and JWT token
issuance. It requires its own PostgreSQL database.
Variable DATABASE_HOST
Required Yes
Description PostgreSQL hostname (e.g. localhost or a Docker service name)
Variable DATABASE_PORT
Required Yes
Description PostgreSQL port, typically 5432
Variable DATABASE_USERNAME
Required Yes
Description PostgreSQL username
Variable DATABASE_PASSWORD
Required Yes
Description PostgreSQL password
Variable DATABASE_NAME
Required Yes
Description PostgreSQL database name, e.g. authentication
Variable JWT_ACCESS_SECRET
Required Yes
Description Secret for signing access tokens — must match the HomeBranch API
Variable JWT_REFRESH_SECRET
Required Yes
Description Secret for signing refresh tokens
Variable SESSION_SECRET
Required Yes
Description Secret used to sign sessions. Generate with openssl rand -base64 48
Variable APP_URL
Required Yes
Description The public base URL of the application (e.g. http://localhost). Used to generate OIDC redirect URLs
Variable CORS_ORIGIN
Required Yes
Description Allowed CORS origin, e.g. http://localhost or your domain
Variable PORT
Required No
Description Port to listen on. Defaults to 3000
| Variable | Required | Description |
DATABASE_HOST | Yes | PostgreSQL hostname (e.g. localhost or a Docker service name) |
DATABASE_PORT | Yes | PostgreSQL port, typically 5432 |
DATABASE_USERNAME | Yes | PostgreSQL username |
DATABASE_PASSWORD | Yes | PostgreSQL password |
DATABASE_NAME | Yes | PostgreSQL database name, e.g. authentication |
JWT_ACCESS_SECRET | Yes | Secret for signing access tokens — must match the HomeBranch API |
JWT_REFRESH_SECRET | Yes | Secret for signing refresh tokens |
SESSION_SECRET | Yes | Secret used to sign sessions. Generate with openssl rand -base64 48 |
APP_URL | Yes | The public base URL of the application (e.g. http://localhost). Used to generate OIDC redirect URLs |
CORS_ORIGIN | Yes | Allowed CORS origin, e.g. http://localhost or your domain |
PORT | No | Port to listen on. Defaults to 3000 |
Secret sharing: JWT_ACCESS_SECRET must be identical in both the
Authentication service and the HomeBranch API. Mismatched secrets will cause all API requests
to fail with 401 Unauthorized.
OIDC configuration
The following OIDC provider settings are configurable at runtime through the admin API
(PATCH /auth/config):
Field oidcIssuerUrl
Description Issuer URL from your OIDC provider (e.g. https://accounts.google.com)
Field oidcClientId
Description OAuth 2.0 client ID registered with your provider
Field oidcClientSecret
Description OAuth 2.0 client secret
Field oidcCallbackUrl
Description Redirect URI registered with your provider — typically {APP_URL}/auth/login/oidc/callback
Field oidcProviderName
Description Display name shown on the login button (e.g. Google, Authentik)
Field signupEnabled
Description Whether new users can self-register. Defaults to true
| Field | Description |
oidcIssuerUrl | Issuer URL from your OIDC provider (e.g. https://accounts.google.com) |
oidcClientId | OAuth 2.0 client ID registered with your provider |
oidcClientSecret | OAuth 2.0 client secret |
oidcCallbackUrl | Redirect URI registered with your provider — typically {APP_URL}/auth/login/oidc/callback |
oidcProviderName | Display name shown on the login button (e.g. Google, Authentik) |
signupEnabled | Whether new users can self-register. Defaults to true |
No restart required: OIDC changes take effect immediately. Use
GET /auth/config/public to check the current OIDC state without admin credentials.
HomeBranch API
The core backend handles book management, bookshelves, authors, favorites, reading position
sync, and user management. It requires its own PostgreSQL database and the same
JWT_ACCESS_SECRET as the auth service.
Variable DATABASE_HOST
Required Yes
Description PostgreSQL hostname
Variable DATABASE_PORT
Required Yes
Description PostgreSQL port, typically 5432
Variable DATABASE_USERNAME
Required Yes
Description PostgreSQL username
Variable DATABASE_PASSWORD
Required Yes
Description PostgreSQL password
Variable DATABASE_NAME
Required Yes
Description PostgreSQL database name, e.g. homebranch
Variable JWT_ACCESS_SECRET
Required Yes
Description JWT signing secret — must match the Authentication service
Variable CORS_ORIGIN
Required Yes
Description Allowed CORS origin for browser requests
Variable UPLOADS_DIRECTORY
Required Yes
Description Filesystem path where uploaded E-Book files are stored, e.g. /data/uploads
Variable AUTH_SERVICE_URL
Required No
Description Required for OPDS feed support
Variable GOOGLE_BOOKS_API_KEY
Required No
Description Optional API key to enable Google Books metadata lookups
Variable REDIS_HOST
Required Yes
Description Redis hostname (e.g. localhost or a Docker service name). Required for background job processing
Variable REDIS_PORT
Required No
Description Redis port. Defaults to 6379
Variable REDIS_PASSWORD
Required No
Description Redis password, if your Redis instance requires authentication
| Variable | Required | Description |
DATABASE_HOST | Yes | PostgreSQL hostname |
DATABASE_PORT | Yes | PostgreSQL port, typically 5432 |
DATABASE_USERNAME | Yes | PostgreSQL username |
DATABASE_PASSWORD | Yes | PostgreSQL password |
DATABASE_NAME | Yes | PostgreSQL database name, e.g. homebranch |
JWT_ACCESS_SECRET | Yes | JWT signing secret — must match the Authentication service |
CORS_ORIGIN | Yes | Allowed CORS origin for browser requests |
UPLOADS_DIRECTORY | Yes | Filesystem path where uploaded E-Book files are stored, e.g. /data/uploads |
AUTH_SERVICE_URL | No | Required for OPDS feed support |
GOOGLE_BOOKS_API_KEY | No | Optional API key to enable Google Books metadata lookups |
REDIS_HOST | Yes | Redis hostname (e.g. localhost or a Docker service name). Required for background job processing |
REDIS_PORT | No | Redis port. Defaults to 6379 |
REDIS_PASSWORD | No | Redis password, if your Redis instance requires authentication |
Database migrations
Migrations run automatically on startup. You can also run them manually:
npm run migration:run
And revert the last migration if needed:
npm run migration:revert
Web frontend (homebranch-web)
The frontend is a static React SPA served by nginx. nginx proxies /api/
and /auth/ requests to the backend containers at runtime - no backend
URLs are baked into the JavaScript bundle.
Docker / nginx environment variables
These variables are read by nginx at container startup to configure proxy targets.
They are only needed when running via Docker or the .deb package.
Variable API_BACKEND
Description Internal URL nginx proxies /api/ requests to
Example http://homebranch:3000
Variable AUTH_BACKEND
Description Internal URL nginx proxies /auth/ requests to
Example http://auth:3000
| Variable | Description | Example |
API_BACKEND | Internal URL nginx proxies /api/ requests to | http://homebranch:3000 |
AUTH_BACKEND | Internal URL nginx proxies /auth/ requests to | http://auth:3000 |
Note: These are internal network addresses - the addresses
nginx uses to reach the backend containers on the Docker network, not public URLs.
Build-time variables
Only needed when building from source. Docker and .deb deployments always
use nginx proxying, so these default to /api and /auth.
Variable VITE_API_URL
Default /api
Description Base path the browser uses for API requests
Variable VITE_AUTHENTICATION_URL
Default /auth
Description Base path the browser uses for auth requests
Variable VITE_ITEMS_PER_PAGE
Default 20
Description Number of books loaded per page in the library
| Variable | Default | Description |
VITE_API_URL | /api | Base path the browser uses for API requests |
VITE_AUTHENTICATION_URL | /auth | Base path the browser uses for auth requests |
VITE_ITEMS_PER_PAGE | 20 | Number of books loaded per page in the library |
