Issued

Your personal comic library server

Host your digital comics (CBZ/CBR files) on your home server and read them on any device. Issued automatically organizes your collection and makes it available through mobile apps like Panels, Chunky, or a built-in web reader.

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️ ATTENTION!! ⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

During a campaign affecting HUNDREDS of repositories on github, Issued has been hacked. If you have installed the repository by cloning the repo and using directly the python files between March 8–14, please delete it immediately and clean your machine because the repository had a malicious code able to run unwanted code using nodejs. This has been solved on the repo and I'm still investigating HOW they hacked the repo without hacking my account. I'm terribly sorry about this and I will do my best to prevent this in the future. You can read more in here

⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️ ATTENTION!! ⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️⚠️

What You Get

• 📚 Keep your folder structure – No need to reorganize your comics
• 🔄 Automatic updates – New comics are detected and added automatically
• 🖼️ Thumbnail previews – See cover images before opening
• 📱 Read anywhere – Use your favorite comic reader app (Panels, Chunky, etc.)
• 🌐 Web reader – Read in your browser without installing anything (on mobile too!)
• ⚡ Easy setup – One command to get started

Collection view

Web and Mobile reader

Edit metadata (uses ComicInfo.xml if available)

Continue reading and Last Added

Before You Start

Docker users: skip this section — the Docker image includes everything you need.

For CBR files only (skip if you only have CBZ):

Install unrar on your computer:

• macOS: brew install rar
• Linux: sudo apt install rar
• Windows: Download from rarlab.com

Note: CBZ files work without any extra software. CBR files need unrar to extract.

Installation

Option 1: Docker (Recommended)

Best for: Running on a home server or NAS. Everything is pre-configured, including unrar.

Step 1: Create a docker-compose.yml file anywhere on your server:

services:
  issued:
    image: ghcr.io/metalogico/issued:latest
    restart: unless-stopped
    ports:
      - "8181:8181"
    volumes:
      - ./data:/app/data
      - /path/to/your/comics:/comics:ro   # ← Change this path

Change /path/to/your/comics to your comics folder:

- /home/user/Comics:/comics:ro     # Linux
- /Users/john/Comics:/comics:ro    # macOS
- C:/Comics:/comics:ro             # Windows

Step 2: Start the server

docker compose up -d

Done! Your comics are now available at:

• 📱 Mobile apps: http://YOUR-SERVER-IP:8181/opds/
• 🌐 Web reader: http://YOUR-SERVER-IP:8181/reader/

Replace YOUR-SERVER-IP with your computer's IP address (e.g., 192.168.1.100)

Alternative: docker run

docker run -d --name issued \
  --restart unless-stopped \
  -p 8181:8181 \
  -v /path/to/your/comics:/comics:ro \
  -v issued_data:/app/data \
  ghcr.io/metalogico/issued:latest

Alternative: docker create (create now, start later)

docker create \
  --name=issued \
  --user 1000:1000 \
  -p 8181:8181 \
  --mount type=bind,source=/path/to/your/comics,target=/comics,readonly \
  --mount type=bind,source=/path/to/data,target=/app/data \
  --restart unless-stopped \
  ghcr.io/metalogico/issued:latest

Then start it:

docker start issued

The image is also available on Docker Hub as metalogico/issued.

---

Option 2: Standalone Executable

Best for: Quick setup on your personal computer.

Step 1: Download for your system

Get the latest release from GitHub Releases:

• macOS: issued-macos
• Linux: issued-linux
• Windows: issued.exe

Step 2: Make it executable (macOS/Linux only)

chmod +x issued

# macOS only: If blocked by security
xattr -d com.apple.quarantine issued

Step 3: Initialize your library

# Replace with your actual comics folder path
./issued init --library /path/to/your/comics

Examples:

./issued init --library ~/Comics              # macOS/Linux
./issued init --library C:\Users\You\Comics   # Windows

Step 4: Scan your comics

./issued scan

This will:

• Find all CBZ/CBR files
• Create thumbnails
• Build the library database

Step 5: Start the server

./issued serve

Done! Your comics are now available at:

• 📱 Mobile apps: http://YOUR-COMPUTER-IP:8181/opds/
• 🌐 Web reader: http://YOUR-COMPUTER-IP:8181/reader/

Tip: Keep the terminal window open while the server runs. New comics will be detected automatically.

---

Using Your Comic Library

On Mobile Apps

Popular apps that work with Issued:

• Panels (iOS) - Best overall experience
• Chunky Reader (iOS) - Great for iPad
• KyBook (iOS) - Feature-rich
• Moon+ Reader (Android) - Highly customizable
• And many oders with opds support (please let me know what you use and I'll add it here)

How to connect:

1. Open your comic reader app
2. Add a new OPDS catalog
3. Enter: http://YOUR-IP:8181/opds/
4. Browse and download comics!

Finding your IP:

• macOS/Linux: Run ifconfig or ip addr
• Windows: Run ipconfig
• Look for something like 192.168.1.100

In Your Browser

Just open: http://localhost:8181/reader/

Optional: Add password protection by editing config.ini:

[reader]
user = yourname
password = yourpassword

Common Tasks

Add new comics

Just copy them to your comics folder! If the server is running, they'll be detected automatically.

Or manually scan:

./issued scan

Rescan everything

./issued scan --force

Check library stats

./issued stats

Regenerate all thumbnails

./issued thumbnails --regenerate

Change settings

Edit config.ini in the same folder as the executable:

• Change port: [server] → port = 8080
• Add password: [reader] → user = name, password = pass
• Adjust thumbnails: [thumbnails] → width, height, quality

Advanced Configuration

Edit config.ini for more options:

[library]
path = /path/to/comics    # Your comics folder
name = My Comics          # Library name shown in apps

[server]
host = 0.0.0.0           # Listen on all network interfaces
port = 8181              # Change if port is already in use

[thumbnails]
width = 300              # Thumbnail width in pixels
height = 450             # Thumbnail height in pixels
quality = 85             # JPEG quality (1-100)
format = jpeg            # jpeg or webp

[monitoring]
enabled = true           # Auto-detect new comics
debounce_seconds = 2     # Wait time before processing changes

[reader]
user =                   # Leave empty for no password
password =               # Leave empty for no password

Troubleshooting

Comics not showing up

1. Check the scan worked:

   ./issued stats

   Should show your comic count.

2. Try a forced rescan:

   ./issued scan --force

Can't connect from mobile app

1. Use your computer's IP address, not localhost

   • Find it: ifconfig (Mac/Linux) or ipconfig (Windows)
   • Example: http://192.168.1.100:8181/opds/

2. Check firewall:

   • Make sure port 8181 is allowed
   • macOS: System Settings → Network → Firewall
   • Windows: Windows Defender Firewall → Allow an app

3. Make sure both devices are on the same network

   • Computer and phone/tablet must be on the same WiFi

CBR files won't open

Install unrar:

• macOS: brew install unrar
• Linux: sudo apt install unrar
• Windows: Download from rarlab.com

Then restart the server.

macOS says "cannot be opened"

xattr -d com.apple.quarantine issued

Port 8181 already in use

Edit config.ini and change the port:

[server]
port = 8080

Then use http://YOUR-IP:8080/opds/ instead.

Server stops when I close the terminal

Docker: It runs in the background automatically.

Executable: Run in the background:

# macOS/Linux
nohup ./issued serve &

# Or use screen/tmux
screen -S issued
./issued serve
# Press Ctrl+A then D to detach

Why is it Violet / Purple?

This project uses the violet accent color just because my baby daughter is called Violet <3

---

Getting Help

If you're stuck:

1. Check the Issues page
2. Open a new issue with:
   • Your OS (macOS/Linux/Windows)
   • How you installed (Docker/executable)
   • What you tried
   • Error messages (if any)

---

License

MIT. See LICENSE for details.