Skip to content

Volumes, PUID and PGID

Maki uses two mounts: /config for its own state and /library for your manga.

Everything Maki needs to run:

  • the SQLite database
  • config.json, which holds the port and settings, including API keys
  • dataprotection-keys, which sign session cookies. Anyone with this folder can sign in as any user, so keep it private. Backups leave it out.
  • logs
  • covers and the page cache
  • the local MangaBaka database, the embedding index and the precomputed recommendation data
  • the search model under models, including a memory-mapped copy of about 110 MB written on the first search by meaning (set MAKI_EMBED_MMAP=0 if your filesystem has trouble with memory-mapped files)
  • backups, under backups

Backups skip the MangaBaka database, embeddings, models, covers and cache, so they stay small. They include your settings in plain text, so treat a backup, config.json and a copy of the database like passwords. See Backup and restore.

Keep /config on a folder only Maki uses. On every start the container changes the owner of anything in it that is not already PUID:PGID, so a shared folder can end up with a new owner.

/library is where Maki downloads chapters and where your existing series live. You add it as a library folder in the setup guide. See First-run setup.

Maki does not change the ownership of /library. The PUID/PGID user has to be able to write there already.

The drop folder under Settings → Library can be any folder Maki can see. If yours sits outside /library, mount it as a third volume, such as /downloads/manga:/drop, and enter /drop in the setting. Maki moves or copies files out of it, so the PUID/PGID user needs write access there too.

The container starts as root only long enough to prepare /config, then runs Maki as PUID:PGID:

  1. It creates /config if it is missing.
  2. It changes the owner of each file and folder in /config that is not already PUID:PGID.
  3. It starts Maki as PUID:PGID with HOME set to /config.

Use numeric IDs, since the entrypoint passes them straight to gosu and does not look up names. They default to 1000.

Set them to the owner of your library folder. On a Linux host, find it with:

Terminal window
ls -ln /path/to/manga-library

The third column is the user ID (PUID) and the fourth is the group ID (PGID).

The setup guide says “Maki can’t reach this folder”. The folder is missing or the mount failed. Check the path on the host, then check the mount in the container:

Terminal window
docker exec maki ls -ln /library

Downloads fail, or Maki cannot write a chapter. The container user cannot write to the library folder. Change PUID and PGID to match the folder’s owner, or give your PUID:PGID user write access:

Terminal window
sudo chown -R 1000:1000 /path/to/manga-library

The container exits right away with a chown error. /config holds files owned by another user, and its mount rejects ownership changes, as a read-only mount or some filesystems do. Maki stops on that error. Mount a writable folder, or change the owner of those files to PUID:PGID. A read-only /config whose files already belong to PUID:PGID starts, then fails on the first write.

On Unraid, the template uses 99 and 100 for PUID and PGID. See Unraid paths and appdata.