Releases

What’s new

Multi-format book support

Books can now carry more than one file format at a time. Matching uploads can be linked under a single logical book, with each format retaining its own filename, hash, and extracted metadata.

PDF support

The API now accepts both EPUB and PDF uploads. Format-aware download and reading endpoints can resolve the correct file for a given book, while the uploads and book records stay grouped under the same title.

Legacy library migration

This release backfills missing primary format rows for books uploaded before the multi-format model was introduced. Older libraries upgrade cleanly and previously uploaded books continue opening after the release.

Upgrade notes

No manual migration steps are required. Database migrations still run automatically on startup, and this release includes the legacy book backfill needed for older libraries. Deploy HomeBranch Web v1.5.0 alongside this API release for the matching format-aware UI.

What’s new

EPUB TOC navigation fix

This patch fixes EPUB table-of-contents navigation by normalizing relative TOC paths and preserving fragment identifiers when the API generates publication manifests. TOC entries now resolve to the same reading-order resources the reader expects, so chapter links open correctly again.

Regression coverage

The release also adds focused manifest coverage for relative TOC entries to prevent the same EPUB navigation regression from slipping back in.

Upgrade notes

No manual migration steps are required. Deploy HomeBranch Web v1.5.1 alongside this API patch so the EPUB reader click handling and manifest generation stay aligned.

What’s new

Multi-format reading

Books can now expose more than one readable format in the UI. The book details page lets readers switch between available formats, and the read flow supports EPUB and PDF from the same logical book.

Format management

Book detail actions now include linked-format management so admins can review attached files, unlink a format, or split a format back into its own book when cleanup is needed.

Reader and upload updates

The web app now includes the format-aware flows required for the current API release, including PDF upload support, richer book actions, and updated book detail behavior around attached files.

Upgrade notes

No breaking changes. Pull the latest Docker image or rebuild from source. Multi-format support requires HomeBranch API v1.4.0 — deploy both services together so the reader, upload flow, and book detail page stay in sync with the API’s format model.

Debian package upgrades preserve /etc/nginx/conf.d/homebranch.conf, so review that file when you upgrade the web frontend. The /api/ proxy should forward X-Forwarded-Proto and X-Forwarded-Prefix /api, and the SSE endpoints should keep buffering disabled. For larger PDF uploads, set client_max_body_size 200m. The Getting Started guide includes an example homebranch.conf you can copy or download.

What’s new

EPUB TOC click handling

This patch repairs the EPUB reader’s table-of-contents drawer so TOC button clicks navigate with the original publication links instead of synthetic placeholder identifiers. Reader chapter navigation now reaches the intended section again.

Upgrade notes

No breaking changes. Pull the latest Docker image or rebuild from source. Deploy HomeBranch API v1.4.1 alongside this web patch so EPUB TOC navigation uses the matching frontend click handling and manifest URLs.

What’s new

Book deduplication

Admins can now scan the library for duplicate EPUB files and resolve each pair directly from the API. A background scan job inspects the library and records duplicate candidates. Each duplicate can then be resolved with one of three actions:

• Merge — keep the original, delete the duplicate and its file
• Replace — promote the duplicate as the canonical copy, delete the original
• Keep both — mark the pair as resolved without deleting either book

New endpoints (admin only):

Method	Path	Description
GET	/api/books/duplicates	List unresolved duplicates (paginated)
POST	/api/books/duplicates/scan	Enqueue a duplicate scan job (returns 202)
POST	/api/books/duplicates/:id/resolve	Resolve a duplicate pair

EPUB file naming convention

EPUB files previously stored under auto-generated UUID filenames are now renamed to Author - Title.epub when the library scanner runs. Newly uploaded files are also stored under this convention going forward.

File drop detection

The library scanner now detects EPUB files dropped directly into the uploads directory without going through the upload API. Dropped files are processed through the same metadata extraction and enrichment pipeline as uploaded books, and are subject to the same three-way bidirectional metadata sync.

Infrastructure

Redis now required

Redis is required for background job processing (BullMQ). Add a Redis service to your deployment and set the following environment variables on the HomeBranch API:

Variable	Default	Description
REDIS_HOST	localhost	Redis hostname
REDIS_PORT	6379	Redis port
REDIS_PASSWORD	(none)	Redis password (optional)

See the Configuration reference and Getting Started guide for an updated Docker Compose example.

Upgrade notes

No breaking changes to the REST API. Database migrations run automatically on startup. Update your deployment to include a Redis service before upgrading — the API will fail to start if Redis is unreachable.

What’s new

Book deduplication UI

The Library Management page now includes a deduplication section. Admins can trigger a duplicate scan and review the results — each duplicate pair is listed with both book titles and their metadata. Selecting a resolution action (merge, replace, or keep both) submits the decision immediately.

Requires HomeBranch API v1.3.0 or later.

Live job streaming

The job history panel now streams progress in real time via Server-Sent Events. Running jobs update their status and progress without requiring a manual refresh. The nginx configuration has been updated to correctly proxy the SSE endpoints (/api/jobs/stream and /api/library/events) without buffering.

Bug fixes

• Button styling: Fixed inconsistent button appearance across several pages
• Upload state: Fixed an issue where previously selected files remained shown in the upload dialog after a successful upload

Upgrade notes

No breaking changes. Pull the latest Docker image or rebuild from source. Book deduplication requires HomeBranch API v1.3.0 — deploy both services together.

Bug fixes

Favorites attribution

Fixed a bug where a user favoriting a book uploaded by another user would incorrectly associate the favorite with the uploader’s account rather than the user who performed the action.

Upgrade notes

No breaking changes. Database migrations run automatically on startup — no manual steps required.

What’s new

PostgreSQL-backed session store

Sessions are now persisted in PostgreSQL using connect-pg-simple. A background job automatically purges stale sessions, preventing unbounded table growth over time.

Breaking change: SESSION_SECRET is now a required environment variable. The service will refuse to start without it. Generate a value with openssl rand -base64 48 and add it to your deployment before upgrading.

OpenID Connect (OIDC) SSO

Single sign-on via OpenID Connect is now fully supported. Once configured, a provider sign-in button appears on the login screen alongside the existing email/password form. OIDC configuration is managed through the admin config API — no service restart is required after changing settings.

New endpoints:

Method	Path	Auth	Description
GET	/oidc/enabled	Public	Returns whether OIDC is configured
GET	/login/oidc	Public	Initiates the OIDC authorization flow (redirects to provider)
GET	/login/oidc/callback	Public	Handles the provider redirect callback and issues tokens
GET	/config	Admin	Retrieve the full authentication configuration including OIDC settings
GET	/config/public	Public	Retrieve sanitized config (oidcEnabled, oidcProviderName, signupEnabled)
PATCH	/config	Admin	Update authentication configuration including OIDC credentials

Improvements

• Refactored authentication strategies to use the Passport strategy pattern, making it straightforward to add additional providers in future releases
• Improved error logging for OIDC authentication exceptions to aid debugging of provider misconfiguration

Breaking changes

SESSION_SECRET is now required. The service will not start without it.

Upgrade notes

1. Generate a session secret: openssl rand -base64 48
2. Add SESSION_SECRET to your environment (add APP_URL for OIDC redirect URL generation)
3. The session table is created automatically on first startup
4. See the updated Getting Started guide for a revised docker-compose.yml

What’s new

OpenID Connect single sign-on

Users can now sign in via an OpenID Connect provider when OIDC is configured in the Authentication service. The login page automatically displays a provider sign-in button when OIDC is enabled — no page changes are required after configuration.

OIDC admin configuration UI

Admins can configure the OIDC provider — issuer URL, client ID, client secret, callback URL, and provider display name — directly from the admin settings page without restarting any services.

Requires Authentication v1.2.0 or later.

Bug fixes

• Favorites attribution: Fixed display of favorite status when viewing books from another user’s library — the UI now correctly reflects the signed-in user’s own favorites
• Bookshelf search field: Fixed an issue where the search input did not render correctly inside the manage bookshelf button
• Mobile drawer search: Fixed an issue where the search input retained its value after closing the mobile drawer
• Mobile menu z-index: Fixed a layering conflict that caused dropdown menus to render behind the mobile navigation drawer

Upgrade notes

No breaking changes. Pull the latest Docker image or rebuild from source. OIDC login requires Authentication v1.2.0 — deploy both services together.