Volumes, PUID and PGID
Maki uses two mounts: /config for its own state and /library for your manga.
/config
Section titled “/config”Everything Maki needs to run:
- the SQLite database
config.json, which holds the port and settings, including API keysdataprotection-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 (setMAKI_EMBED_MMAP=0if 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
Section titled “/library”/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.
A drop folder
Section titled “A drop folder”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.
PUID and PGID
Section titled “PUID and PGID”The container starts as root only long enough to prepare /config, then runs Maki as PUID:PGID:
- It creates
/configif it is missing. - It changes the owner of each file and folder in
/configthat is not alreadyPUID:PGID. - It starts Maki as
PUID:PGIDwithHOMEset 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:
ls -ln /path/to/manga-libraryThe third column is the user ID (PUID) and the fourth is the group ID (PGID).
Fixing permission errors
Section titled “Fixing permission errors”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:
docker exec maki ls -ln /libraryDownloads 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:
sudo chown -R 1000:1000 /path/to/manga-libraryThe 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.