Installation

The fastest way to start using Alex is to download the desktop app. For always-on server deployments, Docker and standalone Node.js options are also available.

Alex supports two storage modes:

• Local mode - Watch a filesystem library folder
• S3 mode - Poll an S3-compatible bucket (Cloudflare R2, AWS S3, MinIO)

---

Desktop app

The recommended way to run Alex. Install it and go—no configuration files, no server setup.

macOS (Homebrew)

brew tap jamesacklin/alex
brew install --cask alex

Other platforms

Download the latest release from GitHub Releases.

First run

1. Launch the app (embedded server on localhost:3210).
2. Choose storage mode in app settings:
   • Local Folder
   • S3 / R2 Bucket
3. Add books and start reading.

The desktop app does not include auto-update support at this time.

Public access via relay

The desktop app can optionally connect to the Alex relay service for public access without port forwarding. When enabled, your library is accessible at a public URL through a reverse WebSocket tunnel. Authentication works transparently behind the relay.

---

Docker

Recommended for always-on home servers or a VPS.

Prerequisites

• Docker and Docker Compose

Quick start (local mode)

docker run -d \
  --name alex \
  -p 3000:3000 \
  -v alex-data:/app/data \
  -v /path/to/your/books:/app/data/library \
  -e NEXTAUTH_SECRET=your-secret-here \
  jamesacklin/alex:latest

Docker Compose (local mode)

services:
  alex:
    image: jamesacklin/alex:latest
    container_name: alex
    ports:
      - "3000:3000"
    volumes:
      - alex-data:/app/data
      - /path/to/your/books:/app/data/library
    environment:
      - DATABASE_PATH=/app/data/library.db
      - LIBRARY_PATH=/app/data/library
      - NEXTAUTH_SECRET=your-secret-here
      - NEXTAUTH_URL=http://localhost:3000
    restart: unless-stopped

volumes:
  alex-data:

Docker Compose (S3 mode)

services:
  alex:
    image: jamesacklin/alex:latest
    ports:
      - "3000:3000"
    volumes:
      - alex-data:/app/data
    environment:
      - DATABASE_PATH=/app/data/library.db
      - COVERS_PATH=/app/data/covers
      - NEXTAUTH_SECRET=your-secret-here
      - NEXTAUTH_URL=http://localhost:3000
      - S3_BUCKET=my-books
      - S3_ACCESS_KEY_ID=your-access-key
      - S3_SECRET_ACCESS_KEY=your-secret-key
      - S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
      - S3_REGION=auto
      - S3_PREFIX=books/
      - S3_POLL_INTERVAL=60
    restart: unless-stopped

volumes:
  alex-data:

Environment variables

First run

1. Open http://your-server:3000.
2. Sign in with seeded credentials (if present) or complete setup to create the initial admin account.
3. Add books:
   • Local mode: drop files into your mounted library folder.
   • S3 mode: upload files to your configured bucket/prefix.

---

Node.js (standalone)

Run Alex directly if you prefer not to use Docker or desktop.

Prerequisites

• Node.js 22+
• pnpm (recommended)
• Rust stable toolchain (rustup toolchain install stable)

The Rust watcher-rs binary powers ingestion and database access.

Setup

git clone https://github.com/jamesacklin/alex.git
cd alex
pnpm install
pnpm db:push
pnpm db:seed

Environment

Create a .env file in the project root:

NEXTAUTH_SECRET=your-secret-here
NEXTAUTH_URL=http://localhost:3000
DATABASE_PATH=./data/library.db
LIBRARY_PATH=./data/library
COVERS_PATH=./data/covers
# Optional S3 mode:
# S3_BUCKET=my-books
# S3_ACCESS_KEY_ID=...
# S3_SECRET_ACCESS_KEY=...
# S3_ENDPOINT=https://<account-id>.r2.cloudflarestorage.com
# S3_REGION=auto
# S3_PREFIX=books/
# S3_POLL_INTERVAL=60

Running

# Start the watcher (auto-selects local vs S3 mode)
pnpm watcher

# Start the Next.js server (in another terminal)
pnpm dev

For production:

pnpm build
node .next/standalone/server.js

What's next

After install, continue with Library Management.