From 963ef9a8b3d3088dd7f8fa5e223d54b044412478 Mon Sep 17 00:00:00 2001 From: Robert Dailey Date: Mon, 30 May 2022 18:39:25 -0500 Subject: [PATCH] docs(wiki): Docker documentation --- wiki/Docker.md | 123 +++++++++++++++++++++++++++++++++++++++++++++++++ wiki/Home.md | 3 ++ 2 files changed, 126 insertions(+) create mode 100644 wiki/Docker.md diff --git a/wiki/Docker.md b/wiki/Docker.md new file mode 100644 index 00000000..474bc9ac --- /dev/null +++ b/wiki/Docker.md @@ -0,0 +1,123 @@ +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. + +```yml +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 + environment: + CRON_SCHEDULE: "* * * * *" +``` + +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](https://github.com/krallin/tini). Please visit that repo to understand the benefits in + detail, if you're interested. + +## 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](#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: + +```txt +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: + +```sh +# 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: + +```sh +recyclarr sonarr; recyclarr radarr +``` + +To enter Cron Mode, you simply start the container in background mode: + +```sh +docker compose up -d +``` + +This runs it without any subcommand or options, which will result in this mode being used. diff --git a/wiki/Home.md b/wiki/Home.md index 123f74f3..7263a9a3 100644 --- a/wiki/Home.md +++ b/wiki/Home.md @@ -3,7 +3,10 @@ Pages of Interest: - [[Command Line Reference]] - [[Configuration Reference]] - [[Settings Reference]] +- [[Upgrade Guide]] - [[Behavior]] +- [[Docker]] +- [[File Structure]] See the "Pages" list on the right side of this page for the complete list of wiki pages.