Development Guide
This document describes how to set up, build, test, and contribute to YTMDL locally.
GitHub-only Development Model
Development and integration take place exclusively at Der-Felix/ytmdl on GitHub. Create a feature branch from the latest dev and submit a PR to dev. Wait for the final commit's GitHub CI and follow applicable branch protection before merging. main is the reviewed stable branch; promotion, release tags and production deployment need separate scope and approval. Do not push private history, internal configuration, credentials or local overrides. See CONTRIBUTING.
The non-publishing .github/workflows/ci.yml checks frontend tests/lint/build and backend formatting/vet/build/tests/race tests with isolated PostgreSQL 18. A development PR does not invoke the release or documentation deployment jobs.
Prerequisites
- Go: the version required by
backend/go.mod(currently 1.26.6) - Node.js / Bun: Bun 1.1+ (or Node 20+ with npm)
- Container Runtime: Podman or Docker with Compose
- PostgreSQL: 18 server and client tools (for running integration tests)
- CLI Tools:
ffmpeg,ffprobe,yt-dlp
Local Development Setup
1. Backend
The Go backend code is located in the backend/ directory.
cd backend
# Format and analyze code
gofmt -w .
go vet ./...
# Build server binary
go build -o server ./cmd/serverRunning Backend Tests
Backend tests include both unit tests and PostgreSQL integration tests. If MUSICDL_TEST_DATABASE_URL is set, integration tests run automatically with an isolated schema per test package:
# Optional: Spin up a local PostgreSQL test container
podman run -d --rm --name ytmdl-pgtest \
-e POSTGRES_USER=ytmdl -e POSTGRES_PASSWORD=testpw -e POSTGRES_DB=ytmdl_test \
-p 127.0.0.1:55432:5432 docker.io/library/postgres:18-alpine
# Run tests
export MUSICDL_TEST_DATABASE_URL='postgres://ytmdl:testpw@127.0.0.1:55432/ytmdl_test?sslmode=disable'
go test -count=1 ./...
# Race condition detection
go test -race ./...2. Frontend
The frontend is a single-page application built with React, TypeScript, Vite, Tailwind CSS, and Base UI located in frontend/.
cd frontend
# Install dependencies
bun install
# Run development server with live reload (proxies /api to backend:8080)
bun run dev
# Run unit and component tests
bun test
# Type check
bunx tsc -b
# Lint with Oxlint
bun run lint
# Production build
bun run buildRunning Full Stack Locally via Compose
To test the entire stack as a cohesive deployment:
# In repository root
cp .env.example .env
podman compose up -d --build
# or: docker compose up -d --buildAccess the web interface at http://localhost:8080.
Release container smoke test
After building the backend and frontend images, run the release smoke test with Python 3 and Docker (or add --engine podman):
python3 scripts/smoke-release-containers.py \
--backend ytmdl-backend:release-smoke \
--frontend ytmdl-frontend:release-smoke \
--version 1.6.0The test creates uniquely named networks, disposable PostgreSQL 18, volumes and containers. Backend and database use an internal network without internet access; the frontend also joins an ingress network to publish its test port on host loopback under both Docker and Podman. It checks first-run setup, the default-disabled combined fallback, exact 25 MiB multipart uploads through both route aliases, oversized file/request rejection, and cookie content, permissions and authentication after backend restart and recreation. It uses synthetic cookies, sends no provider requests, and removes its own containers, volumes and networks when finished.
The release workflow runs this test before publishing. Its manual verify-only mode also builds both container architectures, compiles the host CLI binaries, and validates the manifest without publishing artifacts:
gh workflow run release.yml --repo Der-Felix/ytmdl --ref dev -f verify_only=truev1 Release Qualification
scripts/test-installation.py checks private configuration, refusal of existing files and the reproducible package whitelist. scripts/qualify-compose.py uses the packaged Compose stack, an isolated synthetic catalogue and a real FLAC tone to exercise setup, search, acquisition, PostgreSQL backup/restore and recreation. It runs with Docker and rootless Podman. The browser qualification covers Chromium setup/search/acquisition/playback and ordinary-user role denial, plus Firefox login and playback. It does not measure real provider throughput.
A release tag push first pushes the multi-arch images under a run-unique candidate-<version>-<run>-<attempt> tag, never under the version. Against those candidates, by digest, the workflow scans both image architectures, records SBOMs and runtime tool versions, exercises ARM64 runtime under QEMU, and performs real v0.28.1, v1.0.0, v1.1.1, v1.2.0, v1.3.0, v1.4.0, v1.4.1 and v1.5.0 upgrades for both engines and both storage guard modes (qualify-upgrade.py --stage-target pulls the candidates by digest and tags them locally as the target version; ytmdlctl still verifies both digests against the manifest and GHCR). Chromium and Firefox also qualify explicit offline copies, failed/canceled renewal, byte bounds, real local playback and offline restart. Only then does it create the draft release, give the qualified index digests the version tag (docker buildx imagetools create, which keeps the digests the manifest pins), publish the checked draft and promote the same digests to latest. Release assets include qualification.json, full scan reports and SPDX inventories; every asset is covered by SHA256SUMS.
Published version tags are immutable: the workflow refuses to start, and refuses to promote, if ytmdl-backend:<version> or ytmdl-frontend:<version> already exists. A run that fails before the promotion step leaves only candidate-* tags (and possibly a draft release), so the version is not used up: delete a leftover draft, then push the tag again or re-run the workflow. A run that fails after the promotion has published the version tag; that version is then used up and the fix is released as the next version. A failed run and a rehearsal delete their own candidate-* package versions at the end (scripts/delete-candidate-images.sh). The script deletes an image only if all its tags are candidate-* or rehearsal-*, never one that a version tag or latest also names. If that step itself fails, delete the leftovers from the GHCR package pages under the same rule.
Manual verify-only runs publish no images or releases and report the tag-only gates as unqualified. A rehearsal runs the whole image path without a release and without any version tag:
gh workflow run release.yml --repo Der-Felix/ytmdl --ref <branch> \
-f verify_only=false -f rehearse=trueIt pushes candidate-* images, qualifies them, upgrades included, and tags them rehearsal-<run>-<attempt>, and deletes those package versions again at the end. upgrade-qualification.yml can re-qualify the candidates of a failed release run with -f candidate=candidate-<version>-<run>-<attempt> -f target=<version>.
