Codakey
Play
← Back to booklore

How to Deploy & Use booklore

BookLore Deployment & Usage Guide

1. Prerequisites

Required Software:

  • Docker (version 20.10.0+) and Docker Compose (v2.0.0+) for containerized deployment
  • Java 17+ if building/running from source
  • MariaDB 11.4.5 (included in Docker setup) or compatible MySQL database

Optional Accounts/API Keys:

  • ComicVine API key (for comic metadata enrichment) - Get from comicvine.gamespot.com/api
  • Amazon/Google Books/Open Library access (no API keys required for basic metadata fetching)
  • OIDC provider (like Google, GitHub, Auth0) for external authentication

Storage:

  • Minimum 2GB disk space for application + database
  • Additional space for your book library (size depends on collection)
  • For network storage (NFS/SMB), ensure proper mount permissions

2. Installation

Docker Installation (Recommended)

  1. Create project directory:

    mkdir booklore && cd booklore

  2. Create environment file (.env):

    # Application
APP_USER_ID=1000
APP_GROUP_ID=1000
TZ=Etc/UTC

# Database
DATABASE_URL=jdbc:mariadb://mariadb:3306/booklore
DB_USER=booklore
DB_PASSWORD=ChangeMe_BookLoreApp_2025!

# Storage: LOCAL (default) or NETWORK (for NFS/SMB, disables file reorganization)
DISK_TYPE=LOCAL

# MariaDB
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=ChangeMe_MariaDBRoot_2025!
MYSQL_DATABASE=booklore

  3. Create docker-compose.yml:

    services:
  booklore:
    image: booklore/booklore:latest
    # Alternative: ghcr.io/booklore-app/booklore:latest
    container_name: booklore
    environment:
      - USER_ID=${APP_USER_ID}
      - GROUP_ID=${APP_GROUP_ID}
      - TZ=${TZ}
      - DATABASE_URL=${DATABASE_URL}
      - DATABASE_USERNAME=${DB_USER}
      - DATABASE_PASSWORD=${DB_PASSWORD}
    depends_on:
      mariadb:
        condition: service_healthy
    ports:
      - "6060:6060"
    volumes:
      - ./data:/app/data
      - ./books:/books
      - ./bookdrop:/bookdrop
    healthcheck:
      test: wget -q -O - http://localhost:6060/api/v1/healthcheck
      interval: 60s
      retries: 5
      start_period: 60s
      timeout: 10s
    restart: unless-stopped

  mariadb:
    image: lscr.io/linuxserver/mariadb:11.4.5
    container_name: mariadb
    environment:
      - PUID=${DB_USER_ID}
      - PGID=${DB_GROUP_ID}
      - TZ=${TZ}
      - MYSQL_ROOT_PASSWORD=${MYSQL_ROOT_PASSWORD}
      - MYSQL_DATABASE=${MYSQL_DATABASE}
      - MYSQL_USER=${DB_USER}
      - MYSQL_PASSWORD=${DB_PASSWORD}
    volumes:
      - ./mariadb/config:/config
    restart: unless-stopped
    healthcheck:
      test: [ "CMD", "mariadb-admin", "ping", "-h", "localhost" ]
      interval: 5s
      timeout: 5s
      retries: 10

Source Installation (Development)

  1. Clone the repository:

    git clone https://github.com/booklore-app/booklore.git
cd booklore

  2. Set up MariaDB locally:

    # Install MariaDB (Ubuntu/Debian)
sudo apt-get install mariadb-server

# Create database and user
sudo mysql -u root -p

    CREATE DATABASE booklore CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'booklore'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON booklore.* TO 'booklore'@'localhost';
FLUSH PRIVILEGES;

  3. Build the project:

    # Using Maven (assuming standard Java project structure)
./mvnw clean package -DskipTests

# Or with Gradle
./gradlew build -x test

3. Configuration

Environment Variables

Essential Variables:

# Database Configuration
DATABASE_URL=jdbc:mariadb://localhost:3306/booklore
DATABASE_USERNAME=booklore
DATABASE_PASSWORD=your_secure_password

# Application Settings
TZ=America/New_York  # Your timezone
DISK_TYPE=LOCAL  # or NETWORK for shared storage
BOOKLORE_DATA_DIR=/path/to/data
BOOKLORE_BOOKS_DIR=/path/to/books
BOOKLORE_BOOKDROP_DIR=/path/to/bookdrop

Optional API Keys:

# ComicVine API (for comic metadata)
COMICVINE_API_KEY=your_api_key_here

# OIDC Configuration (for external auth)
OIDC_ISSUER_URI=https://your-oidc-provider.com
OIDC_CLIENT_ID=your_client_id
OIDC_CLIENT_SECRET=your_client_secret

File Structure Configuration

Create the necessary directories:

mkdir -p data books bookdrop mariadb/config

Directory Permissions:

# Ensure proper permissions for Docker
chown -R 1000:1000 data books bookdrop

Application Settings

After first run, configure via web UI:

  1. Access http://localhost:6060
  2. Create admin account
  3. Configure metadata providers in Settings → Metadata
  4. Set up BookDrop folder monitoring
  5. Configure OPDS feed settings for external readers

4. Build & Run

Production Build (Docker)

# Pull latest image
docker pull booklore/booklore:latest

# Start services
docker compose up -d

# View logs
docker compose logs -f booklore

Development Build (From Source)

# Build with Maven
./mvnw clean install

# Run with Spring Boot
java -jar booklore-api/target/*.jar \
  --spring.datasource.url=jdbc:mariadb://localhost:3306/booklore \
  --spring.datasource.username=booklore \
  --spring.datasource.password=your_password

# Or with Gradle
./gradlew bootRun --args='--spring.profiles.active=dev'

Testing the Application

# Check health endpoint
curl http://localhost:6060/api/v1/healthcheck

# Verify database connection
docker compose exec mariadb mysql -u booklore -p booklore

5. Deployment

Docker-Based Platforms

  • Docker Swarm: Use docker stack deploy with compose file
  • Kubernetes: Convert docker-compose.yml to Kubernetes manifests
  • Portainer: Deploy via web UI with stack configuration

Cloud Platforms

  • AWS: ECS/EKS with RDS for MariaDB
  • Google Cloud: Cloud Run + Cloud SQL
  • Azure: Container Instances + Azure Database for MySQL
  • DigitalOcean: App Platform or Droplet with Docker

Reverse Proxy Setup (Nginx)

server {
    listen 80;
    server_name booklore.yourdomain.com;
    
    location / {
        proxy_pass http://localhost:6060;
        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;
    }
    
    # For WebSocket support (reader annotations)
    location /ws {
        proxy_pass http://localhost:6060/ws;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

SSL Configuration

# Using Let's Encrypt with Certbot
certbot --nginx -d booklore.yourdomain.com

# Or with Docker (using nginx-proxy)
docker run -d \
  --name nginx-proxy \
  -p 80:80 -p 443:443 \
  -v /etc/nginx/certs \
  -v /etc/nginx/vhost.d \
  -v /usr/share/nginx/html \
  -v /var/run/docker.sock:/tmp/docker.sock:ro \
  jwilder/nginx-proxy

6. Troubleshooting

Common Issues

1. Database Connection Errors:

# Check MariaDB logs
docker compose logs mariadb

# Test database connectivity
docker compose exec mariadb mysql -u booklore -p

# Verify database exists
SHOW DATABASES;

2. Permission Issues:

# Fix directory permissions
sudo chown -R 1000:1000 ./data ./books ./bookdrop

# Check container user
docker compose exec booklore id

3. Metadata Fetching Fails:

  • Check network connectivity from container
  • Verify no firewall blocking external APIs
  • Check ComicVine API key if configured
  • Review application logs: docker compose logs booklore

4. File Import Issues:

# Check BookDrop folder
ls -la ./bookdrop

# Verify supported formats: EPUB, PDF, CBZ, CBR
# Check file permissions
stat ./bookdrop/your-book.epub

5. Health Check Fails:

# Manual health check
curl -v http://localhost:6060/api/v1/healthcheck

# Check application startup
docker compose logs booklore --tail=50

Logs and Debugging

View Application Logs:

# Follow logs
docker compose logs -f booklore

# View specific service logs
docker compose logs booklore --tail=100

# Check database logs
docker compose logs mariadb

Debug Java Application:

# Enable debug logging
docker compose exec booklore sh -c 'echo "logging.level.org.booklore=DEBUG" >> /app/application.properties'

# Restart with debug
docker compose restart booklore

Database Maintenance:

# Backup database
docker compose exec mariadb mysqldump -u booklore -p booklore > backup_$(date +%Y%m%d).sql

# Restore database
docker compose exec -T mariadb mysql -u booklore -p booklore < backup.sql

Performance Issues

High Memory Usage:

  • Increase container memory limits in docker-compose.yml
  • Adjust Java heap size: JAVA_OPTS=-Xmx2g -Xms512m
  • Monitor with: docker stats booklore

Slow Metadata Fetching:

  • Configure metadata provider timeouts in settings
  • Limit concurrent metadata fetches
  • Consider using local metadata cache

Storage Optimization:

  • Use DISK_TYPE=NETWORK for shared storage (disables file reorganization)
  • Regularly clean up temporary files
  • Monitor disk space in BookDrop folder
← Project overviewView alternatives to booklore →