Getting Started - BookShelf Documentation

Installation Methods

BookShelf can be installed in several ways:

Docker

Easiest setup with minimal dependencies. Recommended for most users.

Docker Compose

Full control over configuration with persistent volumes.

Manual

For development or custom deployments on bare metal.

Quick Start with Docker

The fastest way to get BookShelf running:

bash

docker run -d \
  --name bookshelf \
  -p 3000:3000 \
  -v bookshelf-data:/data \
  -v bookshelf-covers:/app/static/covers \
  -v bookshelf-ebooks:/app/static/ebooks \
  -e SESSION_SECRET=$(openssl rand -hex 32) \
  -e ORIGIN=http://localhost:3000 \
  ghcr.io/iamernie/bookshelf:latest

That's it!

Open http://localhost:3000 in your browser.

Docker Compose Setup

For a more permanent installation with easier management:

1. Create Project Directory

bash

mkdir bookshelf && cd bookshelf

2. Create docker-compose.yml

docker-compose.yml

version: '3.8'

services:
  bookshelf:
    image: ghcr.io/iamernie/bookshelf:latest
    container_name: bookshelf
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - SESSION_SECRET=${SESSION_SECRET}
      - ORIGIN=${ORIGIN:-http://localhost:3000}
      - PORT=3000
      - DATABASE_PATH=/data/bookshelf.sqlite
      - PUID=${PUID:-1000}
      - PGID=${PGID:-1000}
    volumes:
      - ./data:/data
      - ./covers:/app/static/covers
      - ./ebooks:/app/static/ebooks
      - ./logs:/logs
      - ./bookdrop:/app/bookdrop

3. Create Environment File

bash

cat > .env << EOF
SESSION_SECRET=$(openssl rand -hex 32)
ORIGIN=http://localhost:3000
PUID=$(id -u)
PGID=$(id -g)
EOF

4. Start BookShelf

bash

docker compose up -d

5. View Logs

bash

docker compose logs -f

First Time Setup

When you first access BookShelf, you'll be greeted with a setup wizard:

Create Admin Account

Enter your desired username
Set a strong password
Provide your email address

Configure Basic Settings

Set your library name
Choose your preferred date format
Select default language

Start Adding Books!

You're ready to build your library.

Environment Variables

Configure BookShelf with these environment variables:

Variable	Required	Default	Description
`SESSION_SECRET`	Yes	-	Random string for session encryption
`ORIGIN`	Yes	http://localhost:3000	Your server's public URL
`PORT`	No	3000	Server port
`DATABASE_PATH`	No	/data/bookshelf.sqlite	SQLite database location
`PUID / PGID`	No	1000	User/group ID for file permissions
`OPENAI_API_KEY`	No	-	OpenAI API key for AI recommendations
`LOG_LEVEL`	No	info	Logging level (debug, info, warn, error)

Finding Your UID/GID

bash

id -u  # Shows your UID
id -g  # Shows your GID

Volume Mappings

BookShelf uses these directories:

Container Path	Purpose	Host Path
`/data`	SQLite database	./data
`/logs`	Application logs	./logs
`/app/static/covers`	Book cover images	./covers
`/app/static/ebooks`	Uploaded ebook files	./ebooks
`/app/bookdrop`	Auto-import folder	./bookdrop

Reverse Proxy Setup

Nginx

nginx.conf

server {
    listen 80;
    server_name books.example.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Important

Update ORIGIN in your .env to match your domain: ORIGIN=https://books.example.com

Traefik

docker-compose.yml labels

labels:
  - "traefik.enable=true"
  - "traefik.http.routers.bookshelf.rule=Host(`books.example.com`)"
  - "traefik.http.routers.bookshelf.entrypoints=websecure"
  - "traefik.http.routers.bookshelf.tls.certresolver=letsencrypt"
  - "traefik.http.services.bookshelf.loadbalancer.server.port=3000"

Manual Installation

For local development or custom deployments:

Prerequisites

Node.js 18+ and npm
Git

Steps

bash

# 1. Clone repository
git clone https://github.com/iamernie/BookShelf.git
cd BookShelf

# 2. Install dependencies
npm install

# 3. Create environment file
cp .env.example .env
# Edit .env with your settings

# 4. Build the application
npm run build

# 5. Start the server
npm start

For development with hot-reload:

bash

npm run dev

Access at http://localhost:5173 (Vite dev server)

Updating BookShelf

Docker

bash

docker pull ghcr.io/iamernie/bookshelf:latest
docker stop bookshelf
docker rm bookshelf
# Run your docker run command again

Docker Compose

bash

docker compose pull
docker compose up -d

Data Safety

Your data is preserved in volumes, so updates are safe!

Troubleshooting

Check if container is running:

docker ps

Check logs:

docker logs bookshelf

Make sure PUID/PGID match your user:

id -u && id -g

Update your .env file and restart.

If you see database errors after an update:

# Backup first!
cp data/bookshelf.sqlite data/bookshelf.sqlite.backup

# Then restart - migrations run automatically
docker compose restart

Next Steps

Now that BookShelf is running:

Add your first books Explore the ebook reader Set up reading goals Check the FAQ