Development

Prerequisites

Tool	Version	Purpose
Go	1.24+	Backend compilation
Node.js	22+	Frontend build toolchain
npm	(bundled with Node)	Frontend dependency management
ffmpeg	any recent	Stream downloading and muxing

Building

Frontend

cd frontend
npm ci
npm run build

Copy frontend assets into the Go embed directory

cp -r frontend/dist/* internal/web/dist/

This step is necessary because Go embeds internal/web/dist/ via //go:embed, not frontend/dist/. The Dockerfile handles this automatically in its multi-stage build, but local development requires the manual copy.

Backend

go build ./cmd/iplayer-arr/

Testing

go test ./...

The test suite contains roughly 90 tests covering API handlers, BBC service integration, download logic, and storage operations.

Docker Build

docker build -t iplayer-arr .

The Dockerfile uses a three-stage build:

1. node:22-alpine -- installs frontend dependencies and runs the Vite build
2. golang:1.24-alpine -- copies the frontend output into the embed directory, then compiles the Go binary
3. ghcr.io/hotio/base:alpinevpn -- runtime image with VPN support and s6-overlay

Build arguments

Arg	Injected via	Purpose
VERSION	-ldflags	Embedded version string shown on the System page
BUILD_DATE	-ldflags	Build timestamp

Project Structure

cmd/iplayer-arr/          Entry point (main.go)
internal/
  api/                    REST API handlers, SSE hub, ring buffer
  bbc/                    BBC iPlayer integration (IBL, Media Selector, playlist resolver)
  download/               Download manager, ffmpeg integration
  newznab/                Newznab XML API (Sonarr-compatible search/grab)
  sabnzbd/                SABnzbd JSON API (download client protocol)
  store/                  BoltDB storage layer
  web/                    Embedded SPA handler (//go:embed dist/)
frontend/                 Solid.js SPA (Vite, TypeScript, React-style components)
s6/                       s6-overlay service definitions for the runtime container