SuwayomiProcessor

Automated manga chapter processor that monitors an output folder from manga downloaders (like Suwayomi/Tachiyomi), converts chapter folders to CBZ archives, and organizes them for comic book readers.

Features

• 🔄 Automated Processing: Configurable cron schedule (default: daily at 2:00 AM)
• 📚 CBZ Conversion: Converts chapter folders with images to CBZ archives
• 🏷️ Metadata Extraction: Reads translator info from XML and cleans filenames
• 📝 Smart Tracking: Logs processed chapters to avoid duplicate work
• 🐳 Docker-First: Binhex-compliant container with PUID/PGID support
• 🔒 Read-Only: Never modifies source files, only reads
• ⚡ Zero Dependencies: Uses only Python standard library

Quick Start

Using Docker Compose (Recommended)

1. Create docker-compose.yml:

version: '3.8'

services:
  SuwayomiProcessor:
    image: suwayomiprocessor:latest
    container_name: SuwayomiProcessor
    restart: unless-stopped
    volumes:
      - ./app-config:/config              # Config and logs
      - ./app-data:/data                  # Source manga chapters (input)
      - ./app-media:/media                # Processed CBZ files (output)
    environment:
      - PUID=99                           # Unraid/Binhex default (nobody)
      - PGID=100                          # Unraid/Binhex default (users)
      - UMASK=000                         # Unraid/Binhex default (full permissions)
      - TZ=America/New_York               # Your timezone
      - CRON_SCHEDULE=0 2 * * *           # Daily at 2:00 AM
      - RUN_ONCE=false                    # Set true for one-time run

2. Build and start:

docker build -t suwayomiprocessor .
docker-compose up -d

3. Check logs:

docker logs SuwayomiProcessor
docker exec SuwayomiProcessor cat /config/logs/cron.log

Using Docker Run

docker build -t suwayomiprocessor .

docker run -d \
  --name SuwayomiProcessor \
  -v $(pwd)/app-config:/config \
  -v $(pwd)/app-data:/data \
  -v $(pwd)/app-media:/media \
  -e PUID=99 \
  -e PGID=100 \
  -e UMASK=000 \
  -e TZ=America/New_York \
  -e CRON_SCHEDULE="0 2 * * *" \
  -e RUN_ONCE=false \
  suwayomiprocessor

Directory Structure

Expected Source Structure

Tachiyomi/Suwayomi outputs to this structure:

/data/                            # Input volume mount
└── manga/                        # Root manga folder
    ├── MangaDex/                 # Source name (excluded from output)
    │   ├── One Piece/            # Manga series name
    │   │   ├── Chapter 1/
    │   │   │   ├── 001.jpg
    │   │   │   ├── 002.jpg
    │   │   │   └── ComicInfo.xml # Optional metadata
    │   │   └── Chapter 2/
    │   │       └── ...
    │   └── Naruto/
    │       └── ...
    └── MangaPlus/                # Another source
        └── My Hero Academia/
            └── ...

Generated Output Structure

Source names are excluded, only manga series names are used:

/media/                           # Output volume mount
├── One Piece/
│   ├── one_piece-Chapter_1.cbz
│   └── one_piece-Chapter_2.cbz
├── Naruto/
│   └── naruto-Chapter_1.cbz
└── My Hero Academia/
    └── my_hero_academia-Chapter_1.cbz

Configuration

Environment Variables

Binhex Standard (Required)

• PUID - User ID for file ownership (default: 99 Unraid/Binhex standard)
• PGID - Group ID for file ownership (default: 100 Unraid/Binhex standard)
• UMASK - File permission mask (default: 000 Unraid/Binhex standard for full permissions)
• TZ - Timezone (default: UTC) - Example: America/New_York

Application Settings

• LOG_DIR - Log directory (default: /config/logs)
• CONFIG_FILE - Config file path (default: /config/settings.json)
• CRON_SCHEDULE - Cron expression (default: 0 2 * * * = daily at 2:00 AM)
• RUN_ONCE - Run once and exit (default: false)

Note: Source and output directories are defined by volume mounts (/data for input, /media for output) and cannot be changed via environment variables.

Cron Schedule Examples

0 2 * * *       # Daily at 2am (default)
*/30 * * * *    # Every 30 minutes
0 * * * *       # Every hour
0 */6 * * *     # Every 6 hours
0 0 * * *       # Daily at midnight
0 2 * * *       # Daily at 2am

Optional JSON Configuration

Create /config/settings.json for advanced configuration:

{
    "SourceDirectory": "/data",
    "OutputDirectory": "/media",
    "LogDirectory": "/config/logs",
    "CronSchedule": "0 2 * * *",
    "AllowedImageExtensions": [".jpg", ".jpeg", ".png", ".gif", ".webp", ".bmp", ".tiff"]
}

Usage Examples

One-Time Processing

Run processor once without cron:

docker run --rm \
  -v $(pwd)/app-config:/config \
  -v $(pwd)/app-data:/data \
  -v $(pwd)/app-media:/media \
  -e PUID=99 \
  -e PGID=100 \
  -e UMASK=000 \
  -e RUN_ONCE=true \
  suwayomiprocessor

Custom Schedule

Change to run every 6 hours instead of daily:

docker-compose up -d
# Edit docker-compose.yml: CRON_SCHEDULE=0 */6 * * *
docker-compose restart

Debugging

Access container shell:

docker exec -it SuwayomiProcessor sh

View cron jobs:

docker exec SuwayomiProcessor crontab -l

View processing log:

docker exec SuwayomiProcessor cat /config/logs/processed_log.json

Monitoring

Log Files

• Container logs: docker logs SuwayomiProcessor
• Cron output: /config/logs/cron.log (in container)
• Process history: /config/logs/processed_log.json (in container)

Health Checks

# View container status
docker ps | grep SuwayomiProcessor

# View recent processing output
docker exec SuwayomiProcessor tail -50 /config/logs/cron.log

# Check how many chapters have been processed
docker exec SuwayomiProcessor cat /config/logs/processed_log.json | jq '.  | length'

Troubleshooting

Permission Issues

Problem: Can't write to /config or /data

Solution: Set PUID/PGID to match your user

# Find your IDs
id -u  # Your PUID
id -g  # Your PGID

# Update docker-compose.yml with these values

No Files Being Processed

Problem: Processor runs but doesn't create CBZ files

Solutions:

1. Check source directory: docker exec SuwayomiProcessor ls -la /data
2. Verify directory structure matches expected format
3. Check permissions: docker exec SuwayomiProcessor ls -la /config/logs
4. Review logs: docker exec SuwayomiProcessor cat /config/logs/cron.log

Cron Not Running

Problem: Processing doesn't run on schedule

Solutions:

1. Check cron is installed: docker exec SuwayomiProcessor crontab -l
2. Verify RUN_ONCE is false
3. Check cron log for errors: /config/logs/cron.log

Already Processed Files Being Skipped

Problem: Updated chapters aren't being reprocessed

Solution: This is expected behavior - processor uses modification times. To force reprocessing:

# Delete the processed log
docker exec SuwayomiProcessor rm /config/logs/processed_log.json

# Or delete specific series from the log
docker exec SuwayomiProcessor vi /config/logs/processed_log.json

Documentation

• Architecture - System design and technical decisions
• CLAUDE.md - Claude Code configuration
• Development Setup - Developer guide
• Project Structure - Structure reference
• Quick Reference - Quick command reference

Development

Local Development

# Clone repository
git clone https://github.com/Mprice12337/SuwayomiProcessor
cd SuwayomiProcessor

# Run directly with Python
python src/Main.py

# Build Docker image
docker build -t suwayomiprocessor .

# Run tests (manual testing currently)
docker-compose up -d
docker logs SuwayomiProcessor

Project Structure

SuwayomiProcessor/
├── src/                        # Source code
│   ├── Processors/             # Processing logic
│   ├── Utils/                  # Utilities
│   └── Main.py                # Entry point
├── config/                     # Configuration
├── docs/                       # Documentation
├── Dockerfile                  # Container definition
└── docker-compose.yml          # Compose configuration

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

MIT License - See LICENSE file for details

Credits

• Built for use with Suwayomi
• Compatible with Tachiyomi manga downloaders
• Follows Binhex Docker standards

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Version: 2.0.0 Last Updated: 2025-11-05