Installation

🏠 Home › Installation

Installation

How to run CHUB in Docker, plus the PUID/PGID and permissions reference for every install method.

CHUB runs as a Docker container from ghcr.io/chodeus/chub:latest. 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.

Docker Compose (recommended)

Create a folder (e.g. /opt/stacks/chub/) and save this as 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
    healthcheck:
      test: ["CMD-SHELL", "curl -fsS http://127.0.0.1:8000/api/health >/dev/null || exit 1"]
      interval: 30s
      timeout: 5s
      retries: 5
      start_period: 45s
    security_opt:
      - no-new-privileges:true
    tmpfs:
      - /tmp

1. Replace the four host paths with yours.

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://localhost:8000 and follow First Run.

Updating

docker compose pull
docker compose up -d

CHUB migrates its database schema automatically on startup — no manual steps.

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

CHUB's entrypoint briefly runs as root to apply PUID/PGID, then drops to that unprivileged user for the app. Set them to the user/group that owns your mounted host folders so CHUB can read and write them.

Host	PUID	PGID
Unraid	99	100
Typical Linux	1000	1000

Find yours with id <user> on the host. If you omit both, the image defaults to 100:99.

Gotcha: "Permission denied" on startup almost always means PUID/PGID don't match the owner of /config. Run chown -R <puid>:<pgid> /srv/apps/chub on the host, or correct the env vars.

Rootless option: instead of PUID/PGID, set user: "99:100" (the uid:gid that owns your config dir, pre-chown'd). The container then never runs as root.

If it won't start

docker compose logs chub

Common causes: Troubleshooting → Container won't start.

---

Next: First Run · Related: Unraid, Bare metal