Releases

What’s new

On HomeBranch Cloud, the API now reports per-account storage and book usage to the portal so admins can see quota usage.

Upgrade notes

No action is needed for self-hosted installs.

Fixes

• Auth cookies are now set on sign-up, so new users are signed in right away.

What’s new

• Audiobooks: upload MP3 (single or multi-file) and M4B audiobooks. ID3 tags supply the title, artist, tracks, year, genre and embedded cover art, and audiobook directories can be imported in one go.
• Send to Kindle: users save their Kindle email and EPUB books are emailed through an admin-configured SMTP server.
• Cover search: search for and pick a book cover. Trusted cover image redirects are now followed.
• Cloud plans (hosted service only): storage quotas now follow the account’s plan (5 GiB or 50 GiB), and free demo accounts are limited to 5 books. The STORAGE_QUOTA_BYTES setting has been removed.

Fixes

• Fixed an upload failure (HTTP 500) when the temporary file had already been moved.
• SMTP passwords are now stored encrypted.

Upgrade notes

• Send to Kindle: add the SMTP sender address to your Amazon Approved Personal Document E-mail List.
• The SMTP password is encrypted with SETTINGS_ENCRYPTION_KEY, falling back to JWT_ACCESS_SECRET. Keep the key stable, or re-enter the password if it changes. Existing plaintext passwords keep working until they are re-saved.
• Cloud operators: remove STORAGE_QUOTA_BYTES. Limits now come from the portal’s plans.

What’s new

• Audiobooks: listen to single and multi-file audiobooks with a redesigned player, and review audiobook directory groups before importing them.
• Send to Kindle: send EPUB books to your Kindle. The option only appears when the server has SMTP configured.
• Cover picker: search for and choose a cover for any book.

Upgrade notes

Requires HomeBranch API v1.8.0 or later. No other action is needed.

What’s new

• Native app OIDC authentication
• PKCE support (RFC 8252)
• Fix: no longer overrides the Passport OIDC state

What’s new

CORS_ORIGIN can now be a comma-separated list of origins. Previously a list was sent verbatim and browsers rejected it, which broke sign-in from multiple origins.

What’s new

Cloud mode (hosted service only)

This release adds an opt-in cloud mode that powers HomeBranch Cloud. Self-hosted installs are unaffected and stay free and open source. Cloud mode is off unless you enable it.

• Per-account tenant isolation for libraries and files
• Subscription entitlement checks on API requests
• Per-account storage quota
• Cloudflare R2 jurisdiction support for object storage
• OPDS access scoped to the signed-in account

Upgrade notes

No action is needed for self-hosted installs.

What’s new

A small maintenance release that tidies the R2 host configuration code and prepares the cloud mode build. There are no behavior changes for self-hosted installs.

What’s new

OPDS subscription check (cloud mode)

In cloud mode, OPDS logins now enforce the same subscription rules as the web app. Suspended, banned or unsubscribed accounts receive a 403 response, past-due accounts can still browse and download, and administrators are exempt.

Upgrade notes

Self-hosted installs are unaffected.

What’s new

Interface

• Dark mode toggle in the navigation with a saved preference
• Global drag-and-drop overlay for uploading files

Reader

• Jump back to your previous position after TOC navigation or rapid swiping
• Better EPUB resume labels with TOC-aware chapter titles
• Saved reading positions are portable across devices and URLs, using EPUB-internal paths

Cloud mode

• Runtime cloud configuration without rebuilding the image
• Sign-up and all-libraries views are hidden in cloud mode

Upgrade notes

Deploy together with HomeBranch API v1.7.x.

What’s new

On HomeBranch Cloud, accounts that are suspended, banned or unsubscribed are now signed out and returned to the login page with an explanatory message. Self-hosted installs are unaffected.

What’s new

Cloudflare R2 storage support

Books, cover images, and other files can now be stored in Cloudflare R2 in addition to local disk. The new settings are documented in .env.example and the Debian packaging environment file.

OPDS catalog repair

The OPDS catalog works correctly behind reverse proxies again:

• Feed links and cover image links respect X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Prefix.
• OPDS auth URLs honor proxy subpaths.
• OPDS Basic Auth responses now include a realm.

Scan queue polling removed

Scan queue polling was redundant with directory watching and upload events, and it could add unnecessary costs when using R2 storage. It has been removed.

Other fixes and internals

• Book content paths are now treated as a string array.
• Added logging to the OPDS module.
• Added an EPUB archive cache service.
• Updated devcontainer and docker-compose configuration.

Upgrade notes

1. To use R2 storage, add the new storage settings from .env.example to your environment. Local storage keeps working without changes.
2. If you serve OPDS behind a reverse proxy, make sure it forwards X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Prefix (when using a subpath).

Full changelog: v1.5.0…v1.6.0

What’s new

LDAP authentication

Authentication now supports LDAP sign-in alongside local email/password login and OIDC. Admins can configure LDAP from Settings → Single Sign-On by providing the server URL, bind DN, bind password, and base DN, plus optional user/admin group mapping and custom attribute fields.

Provider-aware users

User records now track which authentication provider created them. This lets the HomeBranch admin UI show whether an account is local, OIDC-backed, or LDAP-backed, and keeps future account-management flows provider-aware.

Improvements

• Fixed the production/Debian migration startup path so packaged deployments run pending migrations correctly before booting
• Expanded auth configuration storage with the extra LDAP group and field-mapping columns needed by the new admin settings UI

Upgrade notes

1. No new required environment variables were added for this release. LDAP is configured at runtime through the admin settings UI.
2. This upgrade adds two auth configuration migrations, and both run automatically on startup.
3. Upgrade the service fully before enabling LDAP so the base LDAP columns and the follow-up field/group mapping columns are both present.
4. Deploy HomeBranch Web v1.6.0 alongside this release if you want the LDAP settings UI and provider badges in the frontend.

What’s new

Direct API responses

Successful REST endpoints now return their resource or pagination payloads directly instead of wrapping them in { success, value }. This aligns the API with the current web client contract and removes the extra response-unwrapping layer in homebranch-web.

EPUB table-of-contents parsing repair

The publication manifest generator now parses nested EPUB3 navigation documents and EPUB2 NCX tables of contents correctly. TOC children are preserved again, and older EPUBs that still rely on NCX navigation can populate the reader drawer instead of showing an incomplete or empty hierarchy.

Module and test alignment

The backend has been reorganized around the current NestJS module boundaries, and the library sync test suite now uses portable paths so the release behaves consistently across local and packaged environments. This release also adds focused TOC regression coverage so nested EPUB3 and EPUB2 navigation parsing stay protected.

Breaking changes

Custom clients that deserialize the old { success, value } envelope must be updated to read the response body directly. Error handling still follows normal HTTP status codes.

Upgrade notes

1. Deploy HomeBranch Web v1.6.0 alongside this API release. The frontend now expects the direct-response contract from this version onward.
2. No manual database changes are required beyond the normal startup migration run.

What’s new

Library display controls

The library, favorites, currently reading, and shelf views now share the newer display-mode controls. Readers can switch between the available layouts more consistently, and those preferences carry across the library-related routes.

LDAP-aware settings and user management

The admin settings UI now exposes LDAP configuration fields, and user management surfaces provider information so LDAP-backed accounts are easier to identify after sign-in.

Reader, mobile, and PWA fixes

This release also rolls up the recent reader and shell fixes, including:

• EPUB chapter-transition stability improvements
• repaired TOC fallback extraction from backend publication manifests
• more reliable mobile navigation action rendering
• SPA navigation fixes for installed PWA sessions

Upgrade notes

1. Deploy HomeBranch API v1.5.0 with this release. The frontend now expects the API’s direct JSON response shape and updated pagination contract.
2. LDAP settings in the admin UI require Authentication v1.3.0 or later.
3. Debian package upgrades still preserve /etc/nginx/conf.d/homebranch.conf, so review that file during upgrades if you maintain custom proxy settings.

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.

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

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

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.