Dust

Dust is a media server focused around ebooks and comics. Think Plex, but for people who like to read (and more importantly, collect digital books and comics!).

Quick Start

Installation on Ubuntu/Debian (Recommended):

Interactive mode (lets you configure directories and port):

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

Or quick install with defaults:

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

This will automatically:

• Download the latest release
• Install runtime dependencies (musl)
• Install to /opt/dust
• Set up systemd service
• Configure environment variables

SQLite is bundled with the binary. Interactive mode lets you customize media directories and port during setup. Non-interactive uses defaults (/media/books:/media/comics, port 4001) which you can change later in /opt/dust/.env.

Building from source:

# 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

Environment Variables

Variable	Required	Default	Description
JWT_SECRET	Yes	-	Secret key for JWT authentication
DUST_DIRS	No	-	Colon-separated directories to scan for books
PORT	No	4001	Server port
DATABASE_URL	No	file:./dust.db	Database file path
SCAN_INTERVAL_MINUTES	No	5	How often to scan for new books (in minutes)
CLEANUP_INTERVAL_MINUTES	No	60	How often to cleanup old books (in minutes)
GOOGLE_BOOKS_API_KEY	No	-	Google Books API key for metadata

Web Interface:

The official Dust web client is now bundled with the server and automatically served at http://localhost:4001/. No separate client installation needed!

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

---

Folder Structure

Assuming you have a drive labled "M" and you want that drive to be indexed by Dust, you should structure your media like so:

M:
| > comics
| | > Marvel (this is a publisher)
| | | > Iron Man (this is a comic series)
| | | | > 44 (this is the series number)
| | | | | > iron_man_44.pdf (whatever the name of the file is)
| | | | | > iron_man_44_cover.jpg (the cover image for this comic)
| > books
| | > Henry James (this is an author)
| | | > The Portrait of a Lady (this is a book)
| | | | > portrait.epub (whatever the name of the file is)
| | | | > portrait_cover.jpg (the cover image for this book)
| | > Jeff Szuhay (this is an author)
| | | > Learn C Programming (this is a book)
| | | | > 9781789349917.epub (ISBN-based filename for metadata fetching)
| | | | > learn_c_cover.jpg (the cover image for this book)

Automatic cover handling

Dust now records the exact cover art that lives next to each book/comic. During scans we look for common filenames such as cover.jpg, folder.png, or anything ending in _cover.{jpg,png,jpeg,webp} that sits beside the media file and store that filesystem path on the book record. If no local cover exists but a metadata provider (e.g. OpenLibrary) returns a cover URL for the ISBN, Dust will download the image into the same directory (as cover.<ext>) and link it automatically.

ISBN-Based Metadata Fetching

When organizing books, you can optionally use ISBN or ISBN-13 as the filename to enable automatic metadata fetching from external sources. If the filename is a valid ISBN/ISBN-13, Dust will automatically retrieve book metadata including title, author, publication date, and other details.

Examples:

• 9781789349917.epub - Will fetch metadata for "Learn C Programming" by Jeff Szuhay
• 978-0-123456-78-9.pdf - ISBN with hyphens (also supported)
• regular_filename.epub - Will still be processed but without automatic metadata fetching