Installation

Blockbusterr is distributed as a Linux container for AMD64 and ARM64 systems. Use Docker directly, Docker Compose, or a container-management UI such as Unraid, TrueNAS SCALE, or Portainer.

If you want one complete walkthrough from installation to your first additions, start with Your first movie job. This page covers other installation choices and maintaining the container.

You do not need to install your whole media stack again. Keep your existing Radarr, Sonarr, and download client. Blockbusterr needs its own data folder and network access to those apps; it does not need access to your movie or TV files.

Keep it private

Blockbusterr can use an optional owner token, but you should still keep port 9090 behind a trusted LAN, VPN, or HTTPS reverse proxy. The built-in owner boundary is not a multi-user identity system.

Prerequisites

Docker

Docker 20.10+ or Docker Desktop

Persistent storage

A named Docker volume or writable host directory mounted at /app/data

Network

Access to at least one discovery provider (TMDB, Simkl, Trakt, or MDBList) and your delivery stack

Trakt is optional

Configure any one supported discovery provider: TMDB, Simkl, Trakt, or MDBList. You only need Trakt credentials for jobs that use Trakt as their source.

Installing v2

Pin ghcr.io/mahcks/blockbusterr:v2.0.1 for this release. latest follows stable releases and can move across major versions; latest-beta follows prereleases. Before upgrading from v1, back up the complete data directory and follow the upgrade guide.

Using a NAS or container UI

See Deployment platforms for field-by-field Unraid, TrueNAS SCALE, and Portainer instructions.

Installation Methods

Docker Run

Use this when you manage containers from the command line.

1. Pull the release image:

   docker pull ghcr.io/mahcks/blockbusterr:v2.0.1

2. Run the container:

   docker run -d \
     --name blockbusterr \
     -p 9090:9090 \
     -v blockbusterr-data:/app/data \
     -e BLOCKBUSTERR_DRY_RUN=true \
     -e TZ=America/New_York \
     --restart unless-stopped \
     ghcr.io/mahcks/blockbusterr:v2.0.1

3. Open http://localhost:9090 on the Docker host, or http://YOUR-SERVER-IP:9090 from another device. Confirm the dry-run banner appears.

Tip

Use docker logs blockbusterr -f to view live logs and verify startup.

Docker Compose

Use this when you want the container settings saved in a file you can edit and reuse.

1. Create compose.yaml:

   services:
     blockbusterr:
       image: ghcr.io/mahcks/blockbusterr:v2.0.1
       container_name: blockbusterr
       ports:
         - "9090:9090"
       volumes:
         - blockbusterr-data:/app/data
       environment:
         TZ: America/New_York
         BLOCKBUSTERR_DRY_RUN: "true"
         # BLOCKBUSTERR_AUTH_TOKEN: replace-with-at-least-32-random-characters
       restart: unless-stopped
   
   volumes:
     blockbusterr-data:

2. Start the stack:

   docker compose up -d

3. View logs:

   docker compose logs -f blockbusterr

With Full Stack

An example of putting Blockbusterr, Radarr, and Sonarr on the same network. Skip this if you already run Radarr and Sonarr. The paths are placeholders; Radarr and Sonarr still need their own indexer, download-client, and media-path configuration.

networks:
  media:
    driver: bridge

services:
  blockbusterr:
    image: ghcr.io/mahcks/blockbusterr:v2.0.1
    container_name: blockbusterr
    networks:
      - media
    ports:
      - "9090:9090"
    volumes:
      - ./blockbusterr/data:/app/data
    environment:
      - TZ=America/New_York
      - BLOCKBUSTERR_DRY_RUN=true
    restart: unless-stopped

  radarr:
    image: linuxserver/radarr:latest
    container_name: radarr
    networks:
      - media
    ports:
      - "7878:7878"
    volumes:
      - ./radarr/config:/config
      - /path/to/movies:/movies
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    restart: unless-stopped

  sonarr:
    image: linuxserver/sonarr:latest
    container_name: sonarr
    networks:
      - media
    ports:
      - "8989:8989"
    volumes:
      - ./sonarr/config:/config
      - /path/to/tv:/tv
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/New_York
    restart: unless-stopped

Caution

When using container networking, use container names in URLs:

• Radarr: http://radarr:7878
• Sonarr: http://sonarr:8989

From Source

For developers - Build from source code.

1. Clone the repository:

   git clone https://github.com/mahcks/blockbusterr.git
   cd blockbusterr

2. Install Go 1.25.13 or newer and a C compiler for SQLite, then download dependencies:

   go mod download

3. Build the binary:

   make build

4. Run Blockbusterr:

   ./bin/blockbusterr

Run from source (restart after Go code changes):

make dev

Understand the container settings

Setting	What it does
9090:9090	The left number is the port you open on the host. The right number is Blockbusterr’s port inside the container. If you use 8080:9090, open port 8080 in your browser.
blockbusterr-data:/app/data	Keeps your settings, credentials, and history when you replace the container. Reuse this same volume when updating.
TZ	Controls the timezone used for schedules. Use a value such as America/Chicago or Europe/London.
BLOCKBUSTERR_DRY_RUN=true	Lets you inspect job results without adding titles to Radarr/Sonarr or making requests. Remove it when ready for live delivery.
restart: unless-stopped	Starts the container again after a host restart unless you stopped it yourself.

Changing an environment value means recreating the container, not just refreshing the browser. For Compose, edit the file and run docker compose up -d blockbusterr. Keep the same data volume.

Before turning off dry-run, check which jobs are enabled: interval-based jobs can run when the container starts. Follow Your first movie job to configure and preview one small job.

Environment Variables

Configure Blockbusterr behavior with environment variables:

Variable	Default	Description
CONFIG_PATH	config search paths	Directory containing the config file
DATA_DIR	./data	Database directory
DISABLE_UI	false	Disable the web UI when set to true, 1, or yes
BLOCKBUSTERR_AUTH_TOKEN	unset	Optional owner token (at least 32 characters); sign in with username blockbusterr
BLOCKBUSTERR_DRY_RUN	false	Evaluate jobs and record decisions without sending content to Radarr, Sonarr, Jellyseerr, or Seerr
VERSION	build metadata	Override displayed version metadata
COMMIT	build metadata	Override displayed commit metadata
TZ	UTC	Timezone for scheduling

Example with custom settings:

docker run -d \
  --name blockbusterr \
  -p 8080:9090 \
  -e DATA_DIR=/app/data \
  -e TZ=Europe/London \
  -v $(pwd)/data:/app/data \
  ghcr.io/mahcks/blockbusterr:v2.0.1

Health Check

Verify Blockbusterr is running correctly:

curl -u "blockbusterr:$BLOCKBUSTERR_AUTH_TOKEN" http://localhost:9090/v1/

Expected response:

{
  "version": "v2.0.1",
  "uptime": "1785518792000"
}

Updating

Docker

docker pull ghcr.io/mahcks/blockbusterr:v2.0.1
docker stop blockbusterr
docker rm blockbusterr
# Then run the original docker run command

Docker Compose

Update image: in your Compose file to the intended version before pulling. For this release, use ghcr.io/mahcks/blockbusterr:v2.0.1.

docker compose pull blockbusterr
docker compose up -d blockbusterr

From source

Download the new release or pull the latest code:

git pull origin main
make build
./bin/blockbusterr

Backup Before Updating

Back up the stopped container’s actual data mount before major version upgrades. Run from outside the data directory and use a new filename for each backup:

docker stop blockbusterr
docker run --rm \
  --volumes-from blockbusterr:ro \
  -v "$PWD:/backup" \
  alpine:3.22 tar -czf /backup/blockbusterr-data.tar.gz -C /app/data .

Troubleshooting

Port Already in Use

Change the port mapping: -p 8080:9090 (host:container)

Permission Denied

Ensure the data directory is owned and writable by the user running Blockbusterr.

Can't Connect to *arr

Use container names if on same Docker network, not localhost

Database Locked

Only run one Blockbusterr instance per data directory

Next Steps

Quick Start

Connect TMDB and Radarr, then preview your first movie job

Configuration

Configure a discovery provider and your delivery integrations

Set Up Jobs

Create automated content discovery jobs