Getting Started

HomeBranch is a self-hosted EPUB library made up of three services. This guide walks you through deploying the full stack using Docker Compose - the quickest and recommended path to get everything running.

Prerequisites

• A server or machine running Linux (or any OS with Docker support)
• Docker and Docker Compose installed
• Ports 80 (and optionally 443) open on your firewall

Services overview

HomeBranch requires three services to run:

Both the Auth service and the API each need their own PostgreSQL database. The frontend is a static SPA - nginx handles proxying /api/ and /auth/ requests at runtime.

Step 1 - Generate secrets

The Auth service and API share a JWT_ACCESS_SECRET. Generate strong random values before deploying:

openssl rand -base64 48

Run this twice to get two different secrets - one for JWT_ACCESS_SECRET and one for JWT_REFRESH_SECRET. Keep both values - you'll need them in the next step.

Step 2 - Create your Compose file

Create a docker-compose.yml file and replace the placeholder values (changeme, your-access-secret-here, etc.) with your generated secrets and strong database passwords.

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: homebranch
      POSTGRES_PASSWORD: changeme         # change this
      POSTGRES_DB: homebranch
    volumes:
      - pgdata:/var/lib/postgresql/data
    restart: unless-stopped

  auth-db:
    image: postgres:16
    environment:
      POSTGRES_USER: auth
      POSTGRES_PASSWORD: changeme         # change this
      POSTGRES_DB: authentication
    volumes:
      - authdata:/var/lib/postgresql/data
    restart: unless-stopped

  auth:
    image: ghcr.io/oghamark/authentication:latest
    depends_on:
      - auth-db
    environment:
      DATABASE_HOST: auth-db
      DATABASE_PORT: 5432
      DATABASE_USERNAME: auth
      DATABASE_PASSWORD: changeme         # match auth-db above
      JWT_ACCESS_SECRET: your-access-secret-here     # generate below
      JWT_REFRESH_SECRET: your-refresh-secret-here   # generate below
      CORS_ORIGIN: http://localhost
      PORT: 3000
    restart: unless-stopped

  homebranch:
    image: ghcr.io/oghamark/homebranch:latest
    depends_on:
      - db
      - auth
    environment:
      DATABASE_HOST: db
      DATABASE_PORT: 5432
      DATABASE_USERNAME: homebranch
      DATABASE_PASSWORD: changeme         # match db above
      DATABASE_NAME: homebranch
      JWT_ACCESS_SECRET: your-access-secret-here     # must match auth above
      CORS_ORIGIN: http://localhost
      UPLOADS_DIRECTORY: /data/uploads
    volumes:
      - uploads:/data/uploads
    restart: unless-stopped

  homebranch-web:
    image: ghcr.io/oghamark/homebranch-web:latest
    ports:
      - "80:80"
    depends_on:
      - homebranch
      - auth
    environment:
      API_BACKEND: http://homebranch:3000
      AUTH_BACKEND: http://auth:3000
    restart: unless-stopped

volumes:
  pgdata:
  authdata:
  uploads:

Step 3 - Start the stack

Pull all images and start the services in the background:

docker compose up -d

Check that all five containers are running:

docker compose ps

On the first start, both the Auth service and the API will run database migrations automatically. Wait a few seconds for the databases to initialize.

Step 4 - Create your first user

Open http://localhost (or your server's IP/domain) in a browser. You'll be redirected to the login page.

The first account you register will be automatically assigned the admin role, giving full access to user management and all library features.

Debian / Ubuntu packages

Pre-built .deb packages are available from each service's GitHub Releases page. Install them in the following order:

# Download the latest .deb packages from GitHub Releases
# https://github.com/Oghamark/Authentication/releases/latest
# https://github.com/Oghamark/homebranch/releases/latest
# https://github.com/Oghamark/homebranch-web/releases/latest

sudo dpkg -i authentication_*.deb
sudo dpkg -i homebranch_*.deb

sudo apt install nginx
sudo dpkg -i homebranch-web_*.deb

After installing each package, edit its configuration file to set the required environment variables:

• Authentication: /etc/default/authentication
• HomeBranch API: /etc/default/homebranch
• Web frontend nginx config: /etc/nginx/conf.d/homebranch.conf

Configuration files are preserved across package upgrades, so your edits won't be overwritten. Restart each service after editing:

sudo systemctl restart authentication homebranch
sudo systemctl reload nginx

Build from source

Requires Node.js 20+ and PostgreSQL for both the Auth service and the API.

# Clone all three repositories
git clone https://github.com/Oghamark/Authentication
git clone https://github.com/Oghamark/Homebranch
git clone https://github.com/Oghamark/homebranch-web

# Build the auth service
cd Authentication
npm install
npm run build

# Build the API
cd ../Homebranch
npm install
npm run build

# Build the web frontend
cd ../homebranch-web
npm install
npm run build
# Output is in build/client/

See the Configuration reference for all required environment variables for each service.

Next steps

• Configuration - full environment variable reference for all three services
• API Reference - REST API documentation for the HomeBranch backend