Repository navigation
Installation
🏠 Home › Installation
Run CHUB in Docker from ghcr.io/chodeus/chub. This page also holds the PUID/PGID reference for every install method. Other paths: Unraid · Bare metal.
- Linux host with Docker 24+ (or Docker Desktop on macOS/Windows).
- A host folder for config, database, and logs (grows to 50–200 MB).
- Optionally, the folders that hold your posters, media, and Kometa assets.
| Tag | What you get |
|---|---|
latest |
Core CHUB, kept minimal (~210 MB compressed). |
full |
latest plus the extension tools: the CL2K poster maker and the poster self-heal module (~345 MB). |
vX.Y.Z / vX.Y.Z-full
|
The same two images pinned to a release. |
You can switch between latest and full either way; your config folder works with both.
Save this as compose.yaml in a folder such as /opt/stacks/chub/ (a fuller copy ships as deploy/docker/compose.yaml):
services:
chub:
image: ghcr.io/chodeus/chub:latest
container_name: chub
restart: unless-stopped
ports:
- "8000:8000"
environment:
PUID: "1000" # Unraid: 99
PGID: "1000" # Unraid: 100
TZ: "America/Los_Angeles"
volumes:
- /srv/apps/chub/config:/config
- /srv/apps/chub/posters:/posters
- /srv/media:/media
- /srv/kometa/assets:/kometa
- /etc/localtime:/etc/localtime:ro
security_opt:
- no-new-privileges:true
tmpfs:
- /tmp-
Replace the four host paths with yours. The image has a built-in health check on
/api/health. -
Set
PUID/PGIDto the user that owns those paths (see below). -
Set
TZto your timezone. -
Start it:
docker compose up -d
-
Open
http://<host>:8000and follow First Run.
docker compose pull
docker compose up -dDatabase changes apply on startup. To control when you update, pin a vX.Y.Z tag.
docker run -d \
--name chub \
--restart unless-stopped \
-p 8000:8000 \
-e PUID=1000 -e PGID=1000 -e TZ=America/Los_Angeles \
-v /srv/apps/chub/config:/config \
-v /srv/apps/chub/posters:/posters \
-v /srv/media:/media \
-v /srv/kometa/assets:/kometa \
ghcr.io/chodeus/chub:latest| Container path | What goes here |
|---|---|
/config |
Config, database, logs, backups. Required. |
/posters |
Poster sources/output (poster modules). |
/media |
Your media library (nohl, jduparr). |
/kometa |
Kometa asset folder (poster_renamerr, asset_renamerr). |
CHUB listens on 8000 inside the container. Map it to any host port: -p 8080:8000.
The entrypoint starts as root, applies PUID/PGID, then runs CHUB as that user. Set them to the user and group that own your mounted folders.
| Host | PUID | PGID |
|---|---|---|
| Unraid | 99 |
100 |
| Typical Linux | 1000 |
1000 |
Find yours with id <user>. The defaults are 99/100; UMASK (default 002) sets the mode of new files.
The entrypoint fixes ownership of anything under /config. Other mounts (/posters, /media, /kometa) aren't touched, so they must already be writable by PUID/PGID.
Gotcha: if
/configstill isn't writable (e.g. a network share that ignoreschown), the container stops withFATAL: /config is not writable by <puid>:<pgid> after ownership correction. Runchown -R <puid>:<pgid> /srv/apps/chubon the host, or fix the variables.
Rootless: set user: "99:100" instead (the owner of your config folder). The container never runs as root, PUID/PGID are ignored, and nothing is chowned, so every mount must already be writable by that user.
Check docker compose logs chub, then Troubleshooting → Container won't start.
Next: First Run · Related: Unraid, Bare metal