Alex
Browse docs

Getting Started

Choose an Alex installation and index your first books

What is Alex?

Alex is a self-hosted personal library for reading PDFs and EPUBs. Point it at a local folder or an S3-compatible bucket and it will index supported files, extract metadata, generate covers, and make them available in its browser readers.

Alex has no hosted book catalog, recommendation feed, or subscription. You operate the app and choose where the source files live.

Choose an installation

  • Desktop app — The quickest personal setup. Current release automation publishes a signed/notarized Apple silicon macOS build and Linux packages.
  • Docker — Best for an always-on home server, NAS, or VPS. Multi-architecture images are published for amd64 and arm64.
  • Standalone Node.js — Best for contributors or operators who want to run the Next.js and Rust processes directly.

See Installation for complete steps.

Choose storage

Alex runs one ingestion mode at a time:

  • Local folder — Recursively watches a folder for PDF and EPUB additions, changes, and removals.
  • S3-compatible bucket — Polls AWS S3, Cloudflare R2, MinIO, or another compatible endpoint and compares keys/ETags.

In S3 mode, book files remain in the bucket. Alex stores indexed metadata, its SQLite database, and generated/extracted cover JPEGs locally.

First library

  1. Install Alex using the installation guide.
  2. Select a local folder or enter S3 credentials.
  3. Add .pdf and .epub files to that source.
  4. Wait for the initial scan to finish; the library updates as files are indexed.
  5. Open a book. Alex saves your page or EPUB location and adds in-progress books to Now Reading.

Main features

  • Automatic ingestion — Recursive local watching or scheduled S3 polling, SHA-256 deduplication, metadata extraction, and JPEG covers
  • PDF reading — Continuous vertical pages, direct page jumps, 50–200% zoom, fit-to-width, and document-wide text search
  • EPUB reading — Continuous single-column text, table of contents, chapter controls, four font sizes, and automatic app light/dark theming
  • Per-user progress — Independent PDF page or EPUB CFI/percentage state and a Now Reading shelf
  • Collections — Personal groupings with private/shared filters and per-collection Now Reading
  • Tokenized sharing — Revocable public collection links with scoped browser readers
  • Multiple accounts — Admin/user roles, independent progress, and independently owned collections
  • Optional desktop relay — An outbound WebSocket tunnel for public HTTPS access without port forwarding; remote private pages still require Alex login

Continue