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 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 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 |
JWT_ACCESS_SECRET | Yes | Secret for signing access tokens — must match the HomeBranch API |
JWT_REFRESH_SECRET | Yes | Secret for signing refresh tokens |
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.
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 EPUB files are stored, e.g. /data/uploads
| 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 EPUB files are stored, e.g. /data/uploads |
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 |