MangaShelf

A modern, self-hosted manga downloader and reader

Features • Installation • Quick Start • Configuration • Documentation • Contributing

Why MangaShelf?

Problem	MangaShelf Solution
🐳 Complex Docker setups with multiple containers	Single binary - just download and run
📦 External dependencies (PostgreSQL, Redis)	Self-contained - embedded SQLite database
💻 CLI-only tools intimidate casual users	Beautiful web UI - accessible from any device
📖 Need separate apps to read downloaded manga	Built-in reader - download and read in one place
🔧 Difficult configuration and setup	Zero config - works out of the box

Features

📚 Library Management

Beautiful grid view of your manga collection
Automatic cover art fetching
Track reading progress across devices
Smart organization by series, status, and tags

🔍 Multi-Source Search

Search across multiple manga sources simultaneously
Preview manga details before adding to library
Language preference filtering
Duplicate detection

⬇️ Powerful Downloader

Concurrent downloads with configurable workers
Automatic retry with exponential backoff
Resume interrupted downloads
Export to CBZ, PDF, or raw images

📖 Built-in Reader

Multiple reading modes (single page, double spread, vertical scroll)
Right-to-left and left-to-right support
Keyboard shortcuts and touch gestures
Auto-save reading position
Night mode and customizable themes

🔄 Automatic Updates

Scheduled chapter checking
Per-manga update intervals
New chapter notifications
Background downloading

🔌 Extensible

Built-in sources (MangaDex, MangaSee, Manganato)
Lua scripting for custom sources
REST API for integrations
OPDS feed for e-reader apps

Installation

Quick Install (Linux/macOS)

curl -sSL https://mangashelf.dev/install.sh | sh

Download Binary

Download the latest release for your platform from the Releases page:

Platform	Architecture	Download
Linux	x86_64	mangashelf-linux-amd64
Linux	ARM64	mangashelf-linux-arm64
Linux	ARMv7	[mangashelf-linux-armv7](https://github. com/username/mangashelf/releases/latest/download/mangashelf-linux-armv7)
macOS	x86_64	mangashelf-darwin-amd64
macOS	Apple Silicon	mangashelf-darwin-arm64
Windows	x86_64	mangashelf-windows-amd64.exe

Docker

docker run -d \
  --name mangashelf \
  -p 8080:8080 \
  -v ./data:/data \
  ghcr.io/username/mangashelf:latest

Or with Docker Compose:

# docker-compose.yml
version: '3'
services:
  mangashelf:
    image: ghcr.io/username/mangashelf:latest
    container_name: mangashelf
    ports:
      - "8080:8080"
    volumes:
      - ./data:/data
    environment:
      - TZ=America/New_York
    restart: unless-stopped

docker compose up -d

Package Managers

Homebrew (macOS/Linux)

brew install username/tap/mangashelf

Arch Linux (AUR)

yay -S mangashelf-bin

Scoop (Windows)

scoop bucket add extras
scoop install mangashelf

Nix

nix-env -iA nixpkgs.mangashelf

Build from Source

# Clone the repository
git clone https://github.com/username/mangashelf.git
cd mangashelf

# Build (requires Go 1.21+ and Node.js 18+)
make build

# Or install directly
make install

Quick Start

1. Start the Server

# Using the binary
./mangashelf

# Or specify a custom data directory
./mangashelf --data /path/to/manga

2. Open the Web UI

Navigate to http://localhost:8080 in your browser.

3. Add Your First Manga

Click the + Add button in the top right
Search for a manga (e.g., "One Piece")
Select the manga and choose a source
Click Add to Library
Select chapters to download

4. Start Reading!

Click on any downloaded chapter to open the built-in reader.

Configuration

MangaShelf works out of the box with sensible defaults. Configuration is optional.

Configuration File

On first run, a default configuration file is created at:

Linux/macOS: ~/.config/mangashelf/config.yaml
Windows: %APPDATA%\mangashelf\config.yaml

# config.yaml
server:
  host: "0.0.0.0"
  port: 8080

library:
  path: "./data/manga"

downloader:
  workers: 3
  format: "cbz"  # cbz, pdf, raw

updates:
  enabled: true
  interval: "0 */6 * * *"  # Every 6 hours

notifications:
  enabled: false

See [Configuration Reference](docs/configuration. md) for all options.

Environment Variables

All settings can be overridden with environment variables:

export MANGASHELF_SERVER_PORT=9000
export MANGASHELF_LIBRARY_PATH=/mnt/manga
export MANGASHELF_DOWNLOADER_WORKERS=5

Command Line Options

./mangashelf --help

Usage:
  mangashelf [command]

Commands:
  serve       Start the web server (default)
  version     Print version information
  migrate     Run database migrations
  export      Export library to JSON
  import      Import library from backup

Flags:
  -c, --config string   Path to config file
  -d, --data string     Path to data directory (default "./data")
  -p, --port int        Server port (default 8080)
  -v, --verbose         Enable verbose logging
  -h, --help            Help for mangashelf

Documentation

📖 Full Documentation

Getting Started Guide
Configuration Reference
Supported Sources
[Custom Scrapers (Lua)](docs/custom-scrapers. md)
API Reference
Deployment Guide
Troubleshooting
FAQ

Screenshots

📱 Mobile View

📖 Reader Modes

🔍 Search

⚙️ Settings

Comparison

Feature	MangaShelf	Kaizoku	Mangal	Tachiyomi
Web UI	✅	✅	❌	❌
Built-in Reader	✅	❌	❌	✅
Single Binary	✅	❌	✅	❌
No External DB	✅	❌	✅	✅
Self-Hosted	✅	✅	✅	❌
Desktop/Mobile	✅	✅	❌	📱 only
Auto Updates	✅	✅	❌	✅
Notifications	✅	✅	❌	✅
Custom Sources	✅	✅	✅	✅
ARM Support	✅	⚠️	✅	✅

Integrations

Media Servers

MangaShelf organizes downloads in a format compatible with popular media servers:

Komga - Full compatibility with ComicInfo.xml metadata
Kavita - Automatic library detection
[Calibre](https://calibre-ebook. com/) - Import via folder monitoring

Tracking Services

Anilist - Sync reading progress, fetch metadata
[MyAnimeList](https://myanimelist. net/) - (Coming soon)

Notifications

MangaShelf supports 80+ notification services via Apprise:

Discord
Telegram
Slack
Email
Pushover
And many more...

E-Readers

Access your library from e-reader apps using the built-in OPDS feed:

http://your-server:8080/opds

Compatible apps: Librera, Moon+ Reader, Panels, Chunky, and more.

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/username/mangashelf.git
cd mangashelf

# Install dependencies
make deps

# Run in development mode (hot reload)
make dev

# Run tests
make test

# Build for all platforms
make build-all

Project Structure

mangashelf/
├── cmd/mangashelf/     # Application entry point
├── internal/           # Private application code
│   ├── api/            # HTTP handlers and routing
│   ├── database/       # Database schema and queries
│   ├── downloader/     # Download engine
│   ├── library/        # Library management
│   ├── reader/         # Reader service
│   └── scraper/        # Source providers
├── web/                # Frontend (Svelte)
├── docs/               # Documentation
└── scripts/            # Build and utility scripts

Roadmap

v1.0 (Current Development)

v1.1

Anilist integration
OPDS feed
Lua custom scrapers
Import from Tachiyomi backup

v1.2

Multi-user support
PWA / Offline mode
Reading statistics
Collections and tags

Future

MyAnimeList integration
Manga recommendations
Social features (sharing, comments)
Plugin system

See the [Project Board](https://github. com/username/mangashelf/projects/1) for detailed progress.

Support

💬 Discord - Chat with the community
🐛 [Issues](https://github. com/username/mangashelf/issues) - Report bugs or request features
💡 [Discussions](https://github. com/username/mangashelf/discussions) - Ask questions and share ideas
📖 Wiki - Community documentation

Acknowledgments

MangaShelf stands on the shoulders of giants:

[mangal](https://github. com/metafates/mangal) - Inspiration for the scraper architecture
Kaizoku - Inspiration for the web UI approach
Tachiyomi - Inspiration for the reading experience
[gopher-lua](https://github. com/yuin/gopher-lua) - Lua VM for custom scrapers
Bubble Tea - (Reserved for potential TUI)

License

MangaShelf is open-source software licensed under the MIT License.

_{If you find MangaShelf useful, please consider giving it a ⭐ on GitHub!}

Name		Name	Last commit message	Last commit date
.idea		.idea
cmd/mangashelf		cmd/mangashelf
docs		docs
internal		internal
AGENTS.md		AGENTS.md
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
sqlc.yaml		sqlc.yaml

Latest commit

History

Folders and files

Repository files navigation