OpenPanel

A self-hosted manga and comic book reader -- like Jellyfin, but for CBZ files.

OpenPanel scans your comic/manga library (CBZ, CBR and CB7) and your light novels (EPUB), indexes pages from ZIP archives without extracting them, generates thumbnails, and serves a responsive web reader with continuous-scroll and single-page modes, RTL/LTR support, reading progress tracking, bookmarks, collections, and multi-user support.

---

Features

• Zero extraction -- pages are streamed directly from CBZ (ZIP) archives
• RAR and 7z too -- CBR and CB7 books (or any book that is really a RAR or 7z, whatever its extension) are listed when scanned and unpacked once, the first time they're read, into a cache that keeps the books read most recently
• Light novels -- EPUB books are read as text, in pages or one long scroll, with your choice of font, size, line spacing, margins and paper colours; the contents, bookmarks, progress and the next volume work as they do for comics, and a downloaded novel reads offline
• Automatic scanning -- on startup, and whenever the library folders change: OpenPanel looks every few minutes (5 by default) and scans only when something changed; new, changed, moved and removed files are picked up, and reading progress follows a replaced or moved file
• Thumbnail generation -- WebP thumbnails for books and series
• Reading modes -- continuous scroll, single or two pages, LTR or RTL, fit-width/fit-height/original; the screen stays on while reading, and the end of a book offers the next one
• Reading progress -- tracked per-user, server-side continue-reading, shown on every poster
• Bookmarks -- bookmark pages with optional notes, accessible from a slide-out panel
• Collections -- organize series into custom collections
• Stories in parts -- a folder holding a folder per part of a story (JoJo's Bizarre Adventure/Part 1 …/, Part 2 …/) becomes a story group: one poster in the library that opens to its parts in order, or every part on its own, as each reader likes; a series shows which part it is, and the end of a part leads on to the next
• Multi-user -- username/password authentication; the first user becomes admin and adds the others
• Devices -- everyone sees where they're signed in and can sign a device out
• Admin overview -- what needs attention (unreadable files, errors, failed sign-ins, updates, backups, doubtful metadata), the last scan, and who is reading what
• Admin panel -- libraries, users (roles, devices, sign-out everywhere), scheduled scans and backups with retention and download, updates with their changes, searchable logs with who did what
• Safe updates -- the server updates itself from a release, installing only archives signed with the project's release key; it backs up the database first, and goes back to the previous version on its own if the new one fails to start
• AniList integration -- automatic metadata, covers, and descriptions from AniList, matched by title, with a review list for missing or doubtful matches
• PWA -- installable on mobile and desktop with offline caching
• Security headers -- X-Content-Type-Options, X-Frame-Options, Referrer-Policy
• Responsive -- works on desktop, tablet, and mobile
• Keyboard shortcuts -- arrows and space to turn pages, Home/End, [ ] for the previous or next book, B to bookmark, F for full screen, Esc, and ? for the list
• Docker ready -- single multi-stage Docker image

---

Quick Start

Prerequisites

• Rust 1.75+ (for the backend)
• Node.js 20+ (for the frontend build)
• CBZ files organized in folders

Library Structure

Organize your files like this:

/path/to/manga/
+-- One Piece/
|   +-- Chapter 001.cbz
|   +-- Chapter 002.cbz
|   +-- ...
+-- Naruto/
|   +-- Vol 01.cbz
|   +-- ...
+-- Standalone Book.cbz

Each subfolder becomes a series. Books directly in the root become standalone books. CBZ, CBR and CB7 files are read as pages, EPUB files as text. PDF files are listed by name only, without their pages.

Local Development

1. Clone the repository:

   git clone https://github.com/youruser/openpanel.git
   cd openpanel
   

2. Install frontend dependencies:

   cd ui
   npm install
   

3. Start the backend:

   cd server
   cargo run
   

   The server starts on http://localhost:3001.

4. Start the frontend dev server:

   cd ui
   npm run dev
   

   The dev server starts on http://localhost:3000 and proxies /api calls to :3001.

5. Open the app: Go to http://localhost:3000

6. First-time setup:

   • You will be prompted to create an admin account (username + password)
   • Add a library in the Admin panel (shield icon in the sidebar)
   • Click Scan Now to index your library
   • Go back Home to see your series

---

Configuration

The backend is configured through environment variables (or a .env file in the server/ directory):

Variable	Default	Description
OPENPANEL_PORT	3001	Server port
OPENPANEL_BIND	0.0.0.0	Address to listen on; 127.0.0.1 keeps the server to this machine (behind a reverse proxy)
OPENPANEL_DATA_DIR	./data	Where the SQLite database and thumbnails are stored
DATABASE_URL	sqlite://<DATA_DIR>/openpanel.db	SQLite database URL
OPENPANEL_LIBRARY_ROOTS	(empty)	Comma-separated folders added as libraries on startup, named after the folder (optional, libraries can also be added via admin UI)
OPENPANEL_DEV_MODE	false	Enables CORS for localhost:5173
OPENPANEL_LOG_LEVEL	info	Tracing log level (debug, info, warn, error)
OPENPANEL_ZIP_CACHE_SIZE	200	Number of ZIP indexes to keep in the LRU cache
OPENPANEL_UNPACK_CACHE_MB	4096	Room for RAR and 7z books unpacked for reading (in <DATA_DIR>/unpacked); least recently read go first
OPENPANEL_PUBLIC_URL	http://localhost:3001	Public URL (used for CORS in production)
OPENPANEL_SCAN_ON_STARTUP	true	Scan libraries when the server starts; false overrides the setting in Administration

Example .env:

OPENPANEL_PORT=3001
OPENPANEL_DATA_DIR=./data
OPENPANEL_DEV_MODE=true
OPENPANEL_LIBRARY_ROOTS=/home/user/manga,/home/user/comics
OPENPANEL_LOG_LEVEL=info

---

Docker Deployment

Build and Run with Docker Compose

1. Edit docker-compose.yml -- update the volume mounts to point to your library folders:

   volumes:
     - openpanel-data:/data
     - /your/manga/folder:/libraries/manga:ro
     - /your/comics/folder:/libraries/comics:ro
   

2. Start the stack:

   docker compose up -d
   

3. Access the app: http://your-server:3001

4. Add libraries via Admin:

   • Go to Admin and enter the container paths (e.g., /libraries/manga)

With HTTPS (Caddy)

1. Edit Caddyfile -- replace openpanel.example.com with your domain
2. In docker-compose.yml, uncomment the caddy service

3. docker compose up -d
   

4. Caddy will automatically get an HTTPS certificate via Let's Encrypt

Build Docker Image Only

docker build -t openpanel .
docker run -d \
  -p 3001:3001 \
  -v openpanel-data:/data \
  -v /path/to/manga:/libraries/manga:ro \
  --name openpanel \
  openpanel

---

Production Build (No Docker)

1. Build the frontend:

   cd ui
   npm ci
   npm run build
   

   This outputs static files to ui/dist/.

2. Build the backend:

   cd server
   cargo build --release
   

3. Run:

   cd server
   OPENPANEL_DATA_DIR=/var/lib/openpanel OPENPANEL_PORT=3001 ./target/release/openpanel-server
   

   The server serves the frontend from ui/dist/ automatically.

---

Architecture

+-------------+       +--------------+       +--------------+
|  React SPA  |------>|  Axum (Rust) |------>|   SQLite DB  |
|  (Vite PWA) |  API  |  REST API    |       |  (WAL mode)  |
+-------------+       +------+-------+       +--------------+
                             |
                     +-------v-------+
                     |  CBZ Files    |
                     |  (ZIP on disk)|
                     +---------------+

• Backend: Rust + Axum 0.8 + SQLite (via sqlx). Serves both the API and static frontend files.
• Frontend: React 19 + TypeScript + Vite 7, TanStack Router, Zustand, Tailwind v4, and the zon/ui design system (@zonsh/ui, on Base UI) — see Design system.
• CBZ reading: ZIP central directory is parsed once and cached in an LRU cache. Individual pages are read by seeking to the entry offset -- no full extraction.
• Auth model: Username/password authentication with bcrypt. First registered user is admin. Sessions stored server-side with 1-year expiry. Bearer token in Authorization header.
• Metadata: Cover images and series info fetched from AniList and cached server-side in SQLite.
• PWA: Service worker for offline shell caching, runtime caching for API responses and page images.

Design system (zon/ui)

The interface is built with @zonsh/ui: its components, its material (layered primary, raised secondary, recessed fields, hairline structure), the Licht typefaces and lucide icons. Follow its brand guide (zon.sh/ui/brand.md) when changing the UI: monochrome surfaces with colour only for meaning, Licht for headings, Licht Sans for reading, Licht Mono for labels and numbers.

• The package comes from npm (@zonsh/ui). To move to a newer zon/ui, run npm install @zonsh/ui@latest in ui/ and check its changelog for breaking changes.
• The typefaces are never bundled or hotlinked: the browser asks this server for /licht/fonts/*.woff2, and the server fetches them from www.zon.sh (in development, Vite's zonFonts() proxy does the same). The server therefore needs outbound HTTPS to www.zon.sh; without it the UI falls back to system fonts.
• Local development proxies /api to http://localhost:3001; set OPENPANEL_API_TARGET to use another server.

---

API Reference

All API routes are under /api/. Auth routes are public; most others require a Bearer token.

Full documentation: docs/API.md · OpenAPI spec: docs/openapi.yaml (also served at /api/openapi.yaml)

Method	Path	Description
GET	/api/health	Health check
POST	/api/auth/register	Register a new user
POST	/api/auth/login	Login (returns token)
POST	/api/auth/logout	Logout (invalidates token)
GET	/api/auth/me	Current user info
GET	/api/auth/status	Setup status (needs first user?)
GET	/api/libraries	List all libraries
GET	/api/libraries/:id/series	List series in a library (paginated)
GET	/api/series	List all series (sort, genre, status)
GET	/api/series/:id/books	List books in a series
GET	/api/series/:id/chapters	List detected chapters in a series
GET	/api/series/:id/metadata	Get/set/clear AniList metadata
GET	/api/genres	List all available genres
GET	/api/books/:id	Book details
GET	/api/books/:id/pages/:num	Stream a page image
GET	/api/books/:id/thumbnail	Book thumbnail (WebP)
GET	/api/series/:id/thumbnail	Series thumbnail (WebP)
GET/PUT	/api/progress	Get/update reading progress
GET	/api/progress/batch	Batch get progress for multiple books
GET	/api/continue-reading	Continue reading list (server-side)
GET/POST	/api/bookmarks	List/create bookmarks

---

PWA (Progressive Web App)

OpenPanel is a full PWA — you can install it as an app on any device:

Installing on Mobile (iOS / Android)

1. Open your OpenPanel URL in the browser (Safari on iOS, Chrome on Android)
2. Tap the Share button (iOS) or the three-dot menu (Android)
3. Select Add to Home Screen
4. The app will launch in standalone mode — no browser chrome, feels like a native app

Installing on Desktop (Chrome / Edge)

1. Open your OpenPanel URL
2. Click the install icon in the address bar (or go to ⋮ → "Install OpenPanel")
3. The app opens in its own window

What You Get

• Offline shell — the app shell (HTML/CSS/JS) is cached by the service worker, so the UI loads instantly even on slow connections
• API caching — series lists and metadata are cached with a Network-First strategy (5-minute expiry), so browsing your library works even briefly offline
• Page image caching — manga pages you've read are cached locally (Cache-First, up to 500 pages, 7-day expiry), so re-reading is instant
• Auto-updates — the service worker updates automatically when a new version is deployed

---

License

MIT