Skip to content

Installation

chodeus edited this page Oct 22, 2026 · 9 revisions

🏠 Home › Installation

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.

Prerequisites

  • 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.

Image tags

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.

Docker Compose (recommended)

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
  1. Replace the four host paths with yours. The image has a built-in health check on /api/health.

  2. Set PUID/PGID to the user that owns those paths (see below).

  3. Set TZ to your timezone.

  4. Start it:

    docker compose up -d
  5. Open http://<host>:8000 and follow First Run.

Updating

docker compose pull
docker compose up -d

Database changes apply on startup. To control when you update, pin a vX.Y.Z tag.

Docker single-run

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

Volumes & ports

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.

PUID / PGID & permissions

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 /config still isn't writable (e.g. a network share that ignores chown), the container stops with FATAL: /config is not writable by <puid>:<pgid> after ownership correction. Run chown -R <puid>:<pgid> /srv/apps/chub on 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.

If it won't start

Check docker compose logs chub, then Troubleshooting → Container won't start.


Next: First Run · Related: Unraid, Bare metal

Clone this wiki locally