recyclarr/wiki/Docker.md

Recyclarr has an official Docker image hosted by the Github Container Registry (GHCR). The image name is ghcr.io/recyclarr/recyclarr.

Docker Compose Example

Before we get into the details of how to use the Docker image, I want to start with an example. I personally hardly ever run docker commands directly. Instead, I use docker compose mainly because the docker-compose.yml file is a fantastic way to keep configuration details in one place. Thus, for the remainder of this page, all instruction and advice will be based on the example YAML below. I highly recommend you set up your own docker-compose.yml this way. I understand there will be minor differences for everyone's use case, but it should mostly be taken verbatim.

version: '3'

networks:
  recyclarr:
    name: recyclarr
    external: true

services:
  recyclarr:
    image: ghcr.io/recyclarr/recyclarr
    container_name: recyclarr
    init: true
    networks: [recyclarr]
    volumes:
      - ./config:/config

Here is a breakdown of the above YAML:

• networks
  You are going to ultimately want Recyclarr to be able to connect to your Sonarr and Radarr instances. How you have Radarr and Sonarr hosted on your system will greatly impact how this part gets set up. In my case, I have a dedicated docker bridge network (in this example, named recyclarr) for those services. Naturally, that means I want Recyclarr to also run on that bridge network so it can access those services without going out and back in through my reverse proxy.
• image
  The official Recyclarr image, hosted on Github.
• container_name
  Optional, but I don't want the funky prefix_recyclarr name that Docker Compose uses for services by default.
• init
  Required: This will ensure that the container can be stopped without terminating it when you run docker compose down or docker compose stop. Internally, this runs Recyclarr using tini. Please visit that repo to understand the benefits in detail, if you're interested.

Tags

Tags for the docker image are broken down into the various components of the semantic version number following the format of X.Y.Z, where:

• X: Represents a major release containing breaking changes.
• Y: Represents a feature release.
• Z: Represents a bugfix release.

The structure of the tags are described by the following table. Assume for example purposes we're talking about v2.1.2. The table is sorted by risk in descending order. In other words, if you value stability the most, you want the bottom row. If you value being on the bleeding edge (highest risk), you want the top row.

Tag	Description
latest	Latest release, no matter what, including breaking changes
2	Latest feature and bugfix release; manual update for major releases
2.1	Latest bugfix release; manual update if you want new features
2.1.2	Exact release; no automatic updates

Configuration

Volumes

• /config
  This is the application data directory for Recyclarr. In this directory, files like recyclarr.yml and settings.yml exist, as well as logs, cache, and other directories.

Environment

• CRON_SCHEDULE (Default: @daily)
  Standard cron syntax for how often you want Recyclarr to run (see Cron Mode).

Modes

The docker container can operate in one of two different ways, which are documented below.

TIP: The first time you run Recyclarr in docker, it will automatically run the create-config subcommand to create your recyclarr.yml file in the /config directory (in the container) if that file does not exist yet.

Manual Mode

In manual mode, the container starts up, runs a user-specified operation, and then exits. This is semantically identical to running Recyclarr directly on your host machine, but without all of the set up requirements.

The general syntax is:

docker compose run --rm recyclarr [subcommand] [options]

Where:

• [subcommand] is one of the supported Recyclarr subcommands, such as sonarr and radarr.
• [options] are any options supported by that subcommand (e.g. --debug, --preview).

Examples:

# Sync Sonarr with debug logs
docker compose run --rm recyclarr sonarr --debug

# Do a preview (dry run) sync for Radarr
docker compose run --rm recyclarr radarr --preview --debug

TIP: The --rm option ensures the container is deleted after it runs (without it, your list of stopped containers will start to grow the more often you run it manually).

Cron Mode

In this mode, no immediate action is performed. Rather, the container remains alive and continuously runs both Sonarr and Radarr sync at whatever CRON_SCHEDULE you set (default is daily).

If either the Sonarr or Radarr sync operations fail, they will not prevent each other from proceeding. In other words, if the order the sync happens is first Sonarr and then Radarr, if Sonarr fails, the Radarr sync will still proceed after. From a linux shell perspective, it effectively runs this command:

recyclarr sonarr; recyclarr radarr

To enter Cron Mode, you simply start the container in background mode:

docker compose up -d

This runs it without any subcommand or options, which will result in this mode being used.