jamesacklin/alex repository overview

⁠Alex - Self-Hosted Personal Library

A self-hosted personal library for your ebook collection. Drop PDFs or EPUBs into a folder and Alex takes care of the rest — extracting metadata, generating covers, and making everything readable from a clean, fast web interface.

⁠Quick Start

# 1. Create a docker-compose.yml
curl -o docker-compose.yml https://raw.githubusercontent.com/jamesacklin/alex/main/docker-compose.yml

# 2. Create .env file with a secure secret
echo "NEXTAUTH_SECRET=$(openssl rand -base64 32)" > .env

# 3. Edit docker-compose.yml to point to your books folder
# Change: - ./library:/app/data/library
# To:     - /path/to/your/books:/app/data/library

# 4. Start the container
docker compose up -d

Open http://localhost:3000⁠ and login with:

• Email: admin@localhost
• Password: admin123

⚠️ Change the password immediately after first login

⁠Features

• Zero-effort ingestion - Background watcher automatically imports PDFs and EPUBs
• In-browser readers - Full-featured PDF and EPUB readers with progress tracking, zoom, search, and navigation
• Reading progress - Automatic progress tracking with status management (not started → reading → completed)
• Multi-user support - Built-in user management with admin and user roles
• Search & filter - Find books by title, author, format, and reading status
• Collections - Organize books into custom collections
• Cover generation - Automatic cover extraction from PDFs and EPUBs

⁠Configuration

⁠Environment Variables

⁠Volumes

• /app/data - Persistent storage for database and generated covers (use a named volume)
• /app/data/library - Mount your local books folder here

⁠Ports

• 3000 - Web interface

⁠Example Docker Compose

services:
  alex:
    image: jamesacklin/alex:latest
    ports:
      - "3000:3000"
    environment:
      DATABASE_PATH: /app/data/library.db
      LIBRARY_PATH: /app/data/library
      NEXTAUTH_SECRET: ${NEXTAUTH_SECRET:?Create a .env file and set NEXTAUTH_SECRET}
      NEXTAUTH_URL: ${NEXTAUTH_URL:-http://localhost:3000}
    volumes:
      - alex-data:/app/data
      - ./library:/app/data/library  # Change to your books folder
    restart: unless-stopped

volumes:
  alex-data:

⁠Example Docker Run

docker run -d \
  --name alex \
  -p 3000:3000 \
  -e NEXTAUTH_SECRET="your-secret-here" \
  -e NEXTAUTH_URL="http://localhost:3000" \
  -v alex-data:/app/data \
  -v /path/to/your/books:/app/data/library \
  --restart unless-stopped \
  jamesacklin/alex:latest

⁠Tech Stack

• Framework: Next.js 16 with App Router & Turbopack
• Language: TypeScript
• UI: React 19, Tailwind CSS v4, shadcn/ui
• Database: SQLite with Drizzle ORM
• Authentication: NextAuth.js v5 (credential-based, JWT sessions)
• Book Rendering: PDF.js (PDFs), epub.js (EPUBs)
• Cover Generation: poppler-utils with node-canvas fallback

⁠Supported Formats

• PDF - Full support with page navigation, zoom, and search
• EPUB - Full support with table of contents and reflowable text

⁠Usage Tips

1. Adding Books: Simply drop PDF or EPUB files into your library folder. The file watcher automatically detects and imports them.
2. Collections: Organize books by creating custom collections through the web interface.
3. User Management: Admins can create additional user accounts from the /admin/users page.
4. Reading Progress: Progress is saved automatically as you read. No action needed.
5. Multi-user: Each user has independent reading progress and collections.

⁠Links

• GitHub: https://github.com/jamesacklin/alex⁠