Skip to content

CLAUDE.md

Latest commit

 

History

History
89 lines (62 loc) · 3.37 KB

CLAUDE.md

File metadata and controls

89 lines (62 loc) · 3.37 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

This is the official Docker image repository for qBittorrent-nox (headless qBittorrent). It produces multi-arch Docker images pushed to Docker Hub (qbittorrentofficial/qbittorrent-nox) and GHCR (ghcr.io/qbittorrent/docker-qbittorrent-nox).

Build Commands

Build the image locally

# Standard build (replace with desired version)
docker build --build-arg QBT_VERSION=5.1.4 -t qbittorrent-nox:test .

# Development/devel build
docker build --build-arg QBT_VERSION=devel -t qbittorrent-nox:devel .

# libtorrent v2 variant
docker build \
  --build-arg QBT_VERSION=5.1.4 \
  --build-arg BOOST_VERSION_MAJOR=1 --build-arg BOOST_VERSION_MINOR=90 --build-arg BOOST_VERSION_PATCH=0 \
  --build-arg LIBBT_VERSION=RC_2_0 \
  --build-arg LIBBT_CMAKE_FLAGS="-Ddeprecated-functions=ON" \
  -t qbittorrent-nox:lt2 .

Test the built image

docker run --entrypoint "/usr/bin/qbittorrent-nox" qbittorrent-nox:test --version

Lint GitHub Actions workflows

pip install zizmor
zizmor ./

Architecture

Dockerfile (multi-stage build)

  1. base stage — Alpine Linux with runtime dependencies (Qt6, tini, doas, etc.)
  2. builder stage — Compiles Boost, libtorrent, and qBittorrent from source with security hardening flags
  3. runtime stage — Minimal final image with unprivileged user qbtUser (UID 1000), the binary, SBOM, and entrypoint.sh

The same Dockerfile is duplicated in manual_build/ for users who want to build manually outside of the CI workflow.

entrypoint.sh

Container startup script that:

  • Handles PUID/PGID/PAGID configuration when running as root
  • Creates default qBittorrent config if absent
  • Parses QBT_LEGAL_NOTICE (and deprecated QBT_EULA) environment variable — container refuses to start without QBT_LEGAL_NOTICE=confirm
  • Sets torrenting and WebUI ports from QBT_TORRENTING_PORT / QBT_WEBUI_PORT
  • Fixes volume ownership
  • Drops privileges via doas before executing qbittorrent-nox

GitHub Actions Workflows

Workflow Trigger Purpose
ci.yaml Push / PR Builds devel on linux/amd64, runs zizmor security check
release.yaml Manual dispatch Builds all 6 platforms × 2 libtorrent variants, pushes to Docker Hub + GHCR
alpha.yaml Weekly (Sun 00:00 UTC) + manual Builds devel with libtorrent v2, pushes as alpha tag

The release workflow hardcodes QBT_VERSION=5.1.4 and TAG_RELEASE_NUMBER=2 — these must be updated for each release.

Key Build Arguments

Arg Default Description
QBT_VERSION (required) Version tag, devel, or alpha
BOOST_VERSION_* 1.86.0 Boost library version
LIBBT_VERSION RC_1_2 libtorrent branch (RC_1_2 = v1.x, RC_2_0 = v2.x)
LIBBT_CMAKE_FLAGS (empty) Extra CMake flags for libtorrent

Supported Platforms

linux/386, linux/amd64, linux/arm/v6, linux/arm/v7, linux/arm64/v8, linux/riscv64

Release Process

  1. Update QBT_VERSION and TAG_RELEASE_NUMBER in .github/workflows/release.yaml
  2. Trigger the release.yaml workflow manually via GitHub Actions UI
  3. The workflow builds 12 jobs (6 platforms × 2 libtorrent variants), attests provenance (SLSA), and pushes multi-arch manifests to both registries