Documentation

The fastest way to get running is Docker Compose. Clone the repository and start:

git clone https://github.com/73gon/openpanel.git
cd openpanel

Open docker-compose.yml and update the volume mount to point to the folder where your manga/comic CBZ files live. For example, if your files are at /home/user/manga, replace the placeholder path with that.

docker compose up -d

Open http://localhost:3001 in your browser. You'll be prompted to create an admin account — after that, add your library path and OpenPanel will scan, generate thumbnails, and be ready instantly.

Organize your CBZ files in folders. Each top-level subfolder becomes a series. CBZ files placed directly in the root become standalone books.

In this example, the root folder is your library path — the one you mount in Docker (e.g. /libraries/manga) or set via the admin panel. Inside it:

• One Piece/ becomes a series with chapters detected from filenames
• Naruto/ shows nested volumes — OpenPanel supports any depth of nesting and auto-detects chapter boundaries
• Standalone Book.cbz appears as its own single-volume series

Renaming or reorganizing folders triggers an automatic re-scan (file system watcher). You can also trigger a manual scan from the admin panel.

Build the Docker image and run it directly:

docker build -t openpanel .

Start a container. Replace /path/to/manga with the absolute path to your manga/comic folder on the host machine. The :ro flag mounts it read-only — OpenPanel never modifies your files.

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

openpanel-data is a named Docker volume for the SQLite database and thumbnail cache. Your data persists across container restarts.

The repository includes a ready-to-use docker-compose.yml. Update the volume paths to match your system:

services:
  openpanel:
    build: .
    ports:
      - "3001:3001"
    volumes:
      - openpanel-data:/data
      - /home/user/manga:/libraries/manga:ro
      - /home/user/comics:/libraries/comics:ro
    restart: unless-stopped

volumes:
  openpanel-data:

The paths before the colon (e.g. /home/user/manga) are your host paths. The paths after the colon (e.g. /libraries/manga) are what OpenPanel sees inside the container — these are the paths you'll enter in the admin panel.

docker compose up -d

The repo includes a Caddyfile for automatic HTTPS via Let's Encrypt. Three steps:

1. Open Caddyfile and replace openpanel.example.com with your actual domain
2. In docker-compose.yml, uncomment the caddy service block
3. Run docker compose up -d — Caddy obtains a TLS certificate automatically

Caddy also handles automatic certificate renewal. No manual SSL configuration required.

Build and run natively without Docker. You'll need Rust 1.75+ and Node.js 20+ (or Bun).

Build the frontend

cd ui
npm install
npm run build

This outputs the compiled frontend to ui/dist/. The backend serves these files automatically.

Build the backend

cd server
cargo build --release

Run

Set environment variables for the data directory and port, then start the server:

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

OPENPANEL_DATA_DIR is where the SQLite database and thumbnail cache are stored. Create this directory beforehand and ensure the running user has write permissions.

systemd service (auto-start on boot)

Create a service file so OpenPanel starts automatically:

[Unit]
Description=OpenPanel manga reader
After=network.target

[Service]
Type=simple
User=openpanel
WorkingDirectory=/opt/openpanel/server
ExecStart=/opt/openpanel/server/target/release/openpanel-server
Environment=OPENPANEL_PORT=3001
Environment=OPENPANEL_DATA_DIR=/var/lib/openpanel
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable --now openpanel

Option 1: Docker Desktop

Install Docker Desktop for Windows, then clone and start:

git clone https://github.com/73gon/openpanel.git
cd openpanel

Edit docker-compose.yml and use Windows-style paths for your volumes. In the example below, replace C:/Users/you/manga with the actual folder where your CBZ files are stored:

services:
  openpanel:
    build: .
    ports:
      - "3001:3001"
    volumes:
      - openpanel-data:/data
      - C:/Users/you/manga:/libraries/manga:ro
    restart: unless-stopped

volumes:
  openpanel-data:

docker compose up -d

Option 2: Build from Source

You'll need Rust 1.75+ (via rustup), Node.js 20+ (or Bun), and the Visual Studio C++ Build Tools.

Build the frontend

cd ui
npm install
npm run build

Build the backend

cd server
cargo build --release

Run

Set environment variables and start the server:

$env:OPENPANEL_DATA_DIR="C:\ProgramData\openpanel"
$env:OPENPANEL_PORT="3001"
.\target\release\openpanel-server.exe

C:\ProgramData\openpanel is a good location for the data directory on Windows. Ensure it exists before starting.

Windows Service (auto-start on boot)

Use NSSM to register OpenPanel as a Windows service:

winget install nssm

Register and configure the service:

nssm install OpenPanel "C:\openpanel\server\target\release\openpanel-server.exe"
nssm set OpenPanel AppDirectory "C:\openpanel\server"
nssm set OpenPanel AppEnvironmentExtra OPENPANEL_PORT=3001 OPENPANEL_DATA_DIR=C:\ProgramData\openpanel

Start the service:

nssm start OpenPanel

Manage with nssm stop OpenPanel, nssm restart OpenPanel, or through the Windows Services panel (services.msc).

Configure via environment variables or a .env file placed in the server/ directory:

Example .env

Place this file in server/.env. The server loads it automatically on start:

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

1. Open the app in your browser. You'll see a Create Admin Account form. Enter a username and password — this becomes the admin user.
2. After logging in, click the shield icon in the sidebar to open the admin panel.
3. In Libraries, click Add Library and enter the path to your manga folder. If using Docker, enter the container path (e.g. /libraries/manga), not the host path.
4. Click Scan Now. OpenPanel indexes every CBZ file, generates thumbnails, and detects chapters.
5. Go back to Home — your series are ready to read.

Docker

docker compose pull
docker compose up -d

Linux (native)

Pull the latest code, rebuild both frontend and backend, then restart:

git pull
cd ui && npm ci && npm run build && cd ..
cd server && cargo build --release && cd ..
sudo systemctl restart openpanel

Windows (native)

git pull
cd ui; npm ci; npm run build; cd ..
cd server; cargo build --release; cd ..
nssm restart OpenPanel

In-app update

Admin users can check for updates and trigger an update from the admin panel. The server downloads the latest release, replaces the binary, and restarts automatically.

Mobile (iOS / Android)

1. Open your OpenPanel URL in Safari (iOS) or Chrome (Android)
2. Tap Share (iOS) or the three-dot menu (Android)
3. Select Add to Home Screen

Desktop (Chrome / Edge)

1. Open your OpenPanel URL
2. Click the install icon in the address bar

What you get

• Offline shell — the UI loads instantly even on slow connections
• API caching — series lists cached with Network-First (5-minute expiry)
• Page caching — pages you've read are cached locally (up to 500, 7-day expiry)
• Auto-updates — the service worker updates automatically on new deployments

When using OpenPanel as an installed PWA, you can download chapters and volumes for offline reading. Downloads are stored locally in your browser using IndexedDB.

How it works

• PWA only — download buttons appear only when the app is installed (Add to Home Screen). Browser users are prompted to install first.
• Per-page storage — each page is fetched and stored as a blob in IndexedDB, along with metadata (title, page count, size).
• Persistent storage — on the first download, the app requests navigator.storage.persist() to protect your downloads from browser eviction.
• Downloads tab — a dedicated Downloads tab in the mobile navigation lets you manage all downloaded content and see storage usage.

Downloading

1. Open a series detail page on mobile
2. Tap the download icon on any chapter/volume, or use Download All in the section header
3. Progress is shown per-item during download
4. Downloaded items show a green checkmark

Managing downloads

• Go to the Downloads tab (mobile nav) to see all downloaded content
• Delete individual downloads or clear all at once
• Storage usage is displayed at the bottom of the downloads page

All routes are under /api/. Auth routes are public; most others require a Bearer token in the Authorization header.

OpenPanel has three main components:

• Backend — Rust + Axum 0.8 + SQLite (sqlx). Serves API and static frontend.
• Frontend — React 19 + TypeScript + Vite 7 + TanStack Router + Zustand + Tailwind v4.
• CBZ reading — ZIP central directory parsed once, cached in LRU. Pages served by seek — no extraction.
• Auth — Bcrypt passwords, 1-year server-side sessions, Bearer tokens.
• Metadata — AniList integration cached in SQLite.

Docker

Stop and remove the containers, then optionally delete the data volume:

docker compose down

This stops the containers but keeps your data volume. To also delete the database and thumbnails:

docker compose down -v

To remove the Docker image as well:

docker rmi openpanel

Linux (native)

Stop and disable the service, then remove the files:

sudo systemctl stop openpanel
sudo systemctl disable openpanel
sudo rm /etc/systemd/system/openpanel.service
sudo systemctl daemon-reload

Delete the application and data directories:

sudo rm -rf /opt/openpanel
sudo rm -rf /var/lib/openpanel

Windows (native)

If running as a service via NSSM:

nssm stop OpenPanel
nssm remove OpenPanel confirm

Then delete the application and data folders:

Remove-Item -Recurse -Force C:\openpanel
Remove-Item -Recurse -Force C:\ProgramData\openpanel

Your manga/comic files are never modified — only the database and thumbnail cache in the data directory are removed.

If you've forgotten the admin password, you have several options depending on your access level.

Option 1: Admin resets another user's password

If an admin account is accessible, go to Admin → Profiles and click the lock icon next to the user. Enter a new password (minimum 4 characters). The user's existing sessions are invalidated immediately.

Option 2: Users change their own password

Any logged-in user can change their password from the Profile page. Enter your current password, then set a new one.

Option 3: Delete and re-create the admin user

Stop the server, then delete the admin user from the database. On next startup with no users, the app will show the "Create Admin Account" screen again.

sqlite3 data/openpanel.db "DELETE FROM profiles WHERE role = 'admin';"

Restart the server and create a new admin account in the browser.

Option 4: Generate a new bcrypt hash

If you want to keep the admin user's progress and bookmarks, generate a new bcrypt password hash and update the record:

htpasswd -nbBC 12 "" "newpassword" | tr -d ':\n' | sed 's/$2y/$2b/'

Then update the database with the generated hash:

sqlite3 data/openpanel.db "UPDATE profiles SET password_hash = '<paste_hash>' WHERE username = 'admin';"

Restart the server for changes to take effect.

OpenPanel provides multiple ways to manage passwords depending on your role.

Changing your own password

Navigate to your Profile page (bottom nav on mobile, sidebar on desktop). Enter your current password and set a new one. Minimum password length is 4 characters.

Resetting another user's password (Admin)

1. Go to Admin → Profiles
2. Click the lock icon next to the user
3. Enter a new password (minimum 4 characters)
4. Click Reset Password

The user's existing sessions are invalidated immediately. They will need to log in again with the new password. All password changes are logged in the admin audit log.

If you already have nginx, Traefik, or another reverse proxy, you can route traffic to OpenPanel's port. Here's an example nginx config:

server {
    listen 443 ssl http2;
    server_name openpanel.example.com;

    ssl_certificate     /etc/letsencrypt/live/openpanel.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/openpanel.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        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;
    }
}

Replace openpanel.example.com with your domain. If using WebSocket features in the future, add the Upgrade headers as well.

Set OPENPANEL_PUBLIC_URL in your environment to the public URL (e.g. https://openpanel.example.com) so CORS works correctly.