Setup Guide

Get Dust running on your server in minutes

🚀 Quick Install (Recommended)

The easiest way to get started with Dust on Ubuntu/Debian systems.

Interactive Installation

Lets you configure directories and port during setup:

curl -fsSL https://raw.githubusercontent.com/dust-books/dust-server/main/scripts/install.sh -o /tmp/install-dust.sh
sudo bash /tmp/install-dust.sh

Quick Install with Defaults

Uses default settings (directories: /media/books:/media/comics, port: 4001):

curl -fsSL https://raw.githubusercontent.com/dust-books/dust-server/main/scripts/install.sh | sudo bash
What this does:
  • Downloads the latest Dust release
  • Installs runtime dependencies (musl)
  • Installs to /opt/dust
  • Sets up systemd service for automatic startup
  • Configures environment variables
  • Generates secure JWT secret

🐳 Docker Setup

Run Dust in a container for easy deployment and isolation.

Step 1: Create Environment File

cat > .env << EOF
JWT_SECRET=$(openssl rand -base64 32)
dirs=/app/books
PORT=4001
DATABASE_URL=file:/app/data/dust.db
EOF

Step 2: Create docker-compose.yml

version: '3.8'
services:
  dust-server:
    image: dustbooks/dust-server:latest
    container_name: dust
    ports:
      - "4001:4001"
    volumes:
      - ./books:/app/books:ro
      - dust-data:/app/data
    env_file:
      - .env
    restart: unless-stopped

volumes:
  dust-data:

Step 3: Start the Server

docker compose up -d
Note: Make sure to create a ./books directory and add your eBooks/comics before starting.

🔧 Build from Source

For developers or those who want full control.

Prerequisites

  • Zig compiler (latest stable version)
  • Git

Build Steps

# Clone the repository
git clone https://github.com/dust-books/dust-server.git
cd dust-server

# Build the server
zig build -Doptimize=ReleaseSafe

# Set required environment variables
export JWT_SECRET=$(openssl rand -base64 32)
export DUST_DIRS="/path/to/books:/another/path"

# Run the server
./zig-out/bin/dust-server

⚙️ Configuration

Customize Dust with environment variables.

Variable Required Default Description
JWT_SECRET Yes - Secret key for JWT authentication
DUST_DIRS No - Colon-separated directories to scan
PORT No 4001 Server port
DATABASE_URL No file:./dust.db SQLite database path
SCAN_INTERVAL_MINUTES No 5 Directory scan frequency
CLEANUP_INTERVAL_MINUTES No 60 Archive cleanup frequency
GOOGLE_BOOKS_API_KEY No - Google Books API key for metadata

Example .env File

JWT_SECRET=your-secure-random-string
DUST_DIRS=/media/books:/media/comics
PORT=4001
SCAN_INTERVAL_MINUTES=10
CLEANUP_INTERVAL_MINUTES=120
GOOGLE_BOOKS_API_KEY=optional-api-key

📂 Organizing Your Library

Dust works best when your files are organized in a specific structure:

For eBooks

/media/books/
├── Author Name/
│   ├── Book Title/
│   │   ├── book.epub
│   │   └── cover.jpg (optional)
│   └── Another Book/
│       ├── 9781234567890.epub  (ISBN-based filename)
│       └── cover.jpg
└── Another Author/
    └── Their Book/
        └── book.pdf

For Comics

/media/comics/
├── Publisher Name/
│   ├── Series Name/
│   │   ├── 001/
│   │   │   ├── issue-001.cbz
│   │   │   └── cover.jpg (optional)
│   │   └── 002/
│   │       └── issue-002.cbz
└── Another Publisher/
    └── Another Series/
        └── 001/
            └── comic.cbr
Pro Tip: Name your eBook files with their ISBN (e.g., 9781234567890.epub) to enable automatic metadata fetching from OpenLibrary and Google Books!

✅ Verify Installation

After installation, verify Dust is running:

# Check health endpoint
curl http://localhost:4001/health

# Expected response:
# {"status":"ok","version":"1.0.0","service":"dust-server"}

If using systemd (Ubuntu install):

# Check service status
sudo systemctl status dust

# View logs
sudo journalctl -u dust -f

🎉 Next Steps

  • Open http://your-server:4001 in your browser
  • Create your first user account via the web interface or API
  • Add books to your configured directories
  • Wait for automatic scanning or trigger a manual scan
  • Start reading!

🔍 Troubleshooting

Server won't start

  • Ensure JWT_SECRET is set
  • Check port 4001 is not already in use
  • Verify file permissions on directories

Books not appearing

  • Check DUST_DIRS is configured correctly
  • Ensure files follow the expected directory structure
  • Wait for the scan interval (default: 5 minutes)
  • Check logs for scanning activity

Metadata not loading

  • Verify filename is a valid ISBN (10 or 13 digits)
  • Check internet connectivity for API access
  • Consider adding a GOOGLE_BOOKS_API_KEY for better results

Need Help?

Join the community or report issues on GitHub.

Community Discussions Report an Issue