Installation

Lector is distributed as a Docker image. The recommended way to run it is with Docker Compose.

Docker Compose

Create a docker-compose.yml file:

services:
  lector:
    image: ghcr.io/heuwels/lector:latest
    container_name: lector
    restart: unless-stopped
    ports:
      - "3400:3000"   # web UI
      - "3457:3457"   # API (the browser talks to it directly)
    volumes:
      - ./data:/app/data
    environment:
      - NODE_ENV=production
      - API_URL=http://your-server:3457

Then start it:

docker compose up -d

Lector will be available at http://your-server:3400. All data is stored in a SQLite database inside the data directory.

The UI and the API are separate. Lector's web app runs in your browser and calls its API (Hono, on port 3457) directly — there's no server-side proxy. So you must publish port 3457 alongside the UI, and set API_URL to the address your browser uses to reach the API: the same host you open Lector on, port 3457 (e.g. http://your-server:3457). Don't use 127.0.0.1/localhost here unless you only ever open Lector on the server itself — it resolves on the browser's machine, not the server. Behind a reverse proxy, set it to your HTTPS origin instead (see Reverse proxy).

Updating

# Pull the latest image
docker compose pull

# Restart with the new version
docker compose up -d

Your data is stored in a bind mount and will persist across updates. Releases are tagged — pin a version instead of latest if you prefer explicit upgrades (see Compose + env vars).

Next steps

Configuration — the full environment-variable reference
Tailscale & HTTPS — private network access and a reverse proxy
Backups — protect the data directory
Multi-user & OIDC — give each household member their own library