Install on Unraid

There are two ways to run MangaPixer on Unraid:

• The Unraid template (deploy/unraid/mangapixer.xml): install it from the Docker tab like any other Unraid app. This is the simplest route.
• The Unraid Compose file (deploy/compose.unraid.yaml): for people who manage their containers with Compose.

Both use the same image and the same layout, which differs from the canonical Docker setup like this:

The hardening is the same everywhere: read-only container filesystem, a tmpfs for /tmp, no-new-privileges, and bounded container logs.

Install from the template

MangaPixer is not listed in Community Applications yet. Until it is, add the template by hand. From the Unraid terminal, download it into your user templates folder:

wget -O /boot/config/plugins/dockerMan/templates-user/my-MangaPixer.xml \
  https://raw.githubusercontent.com/dixit92/mangapixer/main/deploy/unraid/mangapixer.xml

Then:

1. Open the Unraid Docker tab.
2. Click Add Container.
3. In the Template dropdown, choose MangaPixer.
4. Fill in:
   • PUID and PGID: Check your Unraid user's ID with ls -ln /mnt/user/appdata. Defaults are 99 (nobody) and 100 (users).
   • Media: set the host path to your comics or manga share (for example /mnt/user/Manga); it is mounted read-only at /media/manga. For another share, select Add another Path and use a sibling container path such as /media/comics, also read-only. Never mount one share inside another (for example one at /media and another at /media/comics): Docker would have to create a folder inside your first share.
5. Click Apply.
6. The container starts. Once it is running, visit http://<unraid-ip>:6266 and create the first admin on the welcome screen. Then register your libraries with root paths such as /media/manga, as in step 6 of the Docker guide.

The template runs the latest image, so it follows each release. To upgrade, use Unraid's update action for the container on the Docker tab (apply update when Unraid reports one, or Force update). Database upgrades take a safety snapshot first, as described in Install with Docker.

Once MangaPixer is listed in Community Applications, you will be able to install it from the Apps tab without the download step.

Install with Compose

This route needs docker compose on the Unraid host (usually from a Compose plugin).

Step 1: get the Compose file and choose a version

Copy deploy/compose.unraid.yaml from the repository to a folder on the server, for example /mnt/user/appdata/MangaPixer-compose/, or clone the repository there. The file pulls ghcr.io/dixit92/mangapixer:<version> when the container starts, so nothing needs to be built or copied by hand.

Set MANGAPIXER_VERSION to the release you want (see the Releases page). If it is unset, the file falls back to latest, which moves with every release.

export MANGAPIXER_VERSION=1.22.1

To run an unreleased build instead, clone the repository on the server and add deploy/compose.build.yaml to the -f list in step 4; Compose then builds the image from the clone. pwsh ./scripts/Package-Release.ps1 on another machine still produces a loadable .tar if you prefer to build elsewhere and docker load it.

Step 2: set PUID and PGID

The container starts as root, sets the owner of /config and its data, cache and scratch subfolders to PUID:PGID on every start, and then runs the server as that user. Set these two variables to the user and group that should own the appdata folder on the host. Check the numbers with:

ls -ln /mnt/user/appdata

Many Unraid systems use 99 (nobody) and 100 (users) for shares. If you leave the variables unset, the defaults are 1000/1000.

Step 3: add your media shares

The media lines in compose.unraid.yaml are commented-out examples. Rather than editing the tracked file, put your real paths in an override file next to it, compose.unraid.override.yaml:

services:
  mangapixer:
    environment:
      PUID: "99"
      PGID: "100"
    volumes:
      - /mnt/user/Manga:/media/manga:ro
      - /mnt/user/Comics:/media/comics:ro

• Always add :ro so each share is read-only inside the container. The server never writes into your media, and the read-only mount makes the operating system enforce that too.
• Mount shares under /media, where the library Browse… picker starts.
• Compose merges the override only when you pass it with -f (next step). Compose does not pick this file name up on its own.

You do not need a media-root variable for the mounts to work. You pick each library's folder in the web UI, and the picker's starting folder is controlled by MangaPixer__Storage__MediaRoot (default /media).

Step 4: start the container

From the folder that holds both files:

docker compose -f compose.unraid.yaml -f compose.unraid.override.yaml up -d

(From a repository clone, use deploy/compose.unraid.yaml and deploy/compose.unraid.override.yaml; the repository's .gitignore excludes the override file.)

Check it:

curl http://localhost:6266/health

It answers Healthy. If port 6266 is already taken, change the left-hand number of the port mapping. The server always listens on 8080 inside the container.

Step 5: first-run setup and libraries

Open http://<unraid-ip>:6266. There is no default account. Create the first admin on the Welcome to MangaPixer screen, then register and scan your libraries. Use root paths like /media/manga. The steps are the same as steps 5 and 6 of the Docker guide.

Port 6266 is published on every interface, but the server itself only speaks plain HTTP. If you plan to reach it from outside your LAN, put it behind a reverse proxy with HTTPS, and consider binding the port to a specific address.

What ends up in appdata

/mnt/user/appdata/MangaPixer/
├── data/
│   ├── mangapixer.db          database (plus -wal / -shm files while running)
│   ├── keys/                 sign-in cookie keys (owner-only permissions)
│   ├── logs/                 daily log files, 7 kept
│   ├── backups/              rotating-*, pre-migration-*, pre-restore-* snapshots
│   └── thumbnails/           cover thumbnails
├── cache/                    page image cache (1 GiB budget, disposable)
└── scratch/                  temporary work folders (disposable)

Your normal appdata backup covers all of it. The data/backups/rotating-*.db files are consistent snapshots taken by the server, so they are safe to restore from even if your appdata backup ran while the container was up. See Backup and restore.

To keep the rotating snapshots off the cache pool, for example on an archive share on the array, add a path mapping such as /mnt/user/archive/mangapixer-backups to /backups (read/write, owned by your PUID:PGID), then choose Custom folder /backups in Administration > Backup settings. If the share is not available, backups pause and the admin page shows Backup location unavailable; they never fall back to appdata. The pre-migration and pre-restore snapshots stay in data/backups.

If you want the page cache off the array, mount another path and point MangaPixer__Storage__CacheRoot at it (see Configuration).

Upgrading a Compose install

Set MANGAPIXER_VERSION to the new version, run the same command with pull instead of up -d, then up -d again. Compose recreates the container with the new image, and /config is kept. Database schema upgrades take a pre-migration-*.db snapshot first, as described in Install with Docker.