chore: add examples for scheduled execution

docs/docs/configuration/scheduled.md

@@ -0,0 +1,33 @@
+---
+sidebar_position: 3
+title: Scheduling
+description: "How to run configarr regulary/schedueld"
+keywords: [configarr configuration, schedule, scheduler, regular, cron]
+---
+
+# Scheduling configarr
+
+This section describes how you could run configarr in a scheduled manner.
+
+:::info
+Configarr does not support scheduled execution inside the container and most likely never will.
+Scheduling functionalities should be something which is handled outside of the container and something which should be bundled inside each app.
+:::
+
+## Kubernetes
+
+Kubernetes support for scheduling jobs is straigthforward.
+We have explicit resources for this tasks: `CronJobs`
+See [Kubernetes Setup](/docs/installation/kubernetes) for more information.
+
+## Docker
+
+For docker and docker-compose we do not have explicit functionalities.
+Therefore we have to create our own scheduled tasks.
+There are different ways we could achieve this:
+
+- default cron scheduler on linux systems
+- running scheduler containers which executes other docker containers
+
+We have create examples for how to run the container based solutions.
+Check [examples/scheduled](/docs/examples#scheduled-example) for more information.

docs/docs/examples.md

@@ -52,3 +52,11 @@ To remove all containers and volumes:
 ```bash
 docker-compose down -v
 ```
+
+## Scheduled Example
+
+This is an example of how to execute configarr in a scheduled manner.
+
+You can find the full example at: [configarr/examples/scheduled](https://github.com/raydak-labs/configarr/tree/main/examples/scheduled)
+
+Please check the documentation for how to configure and use the variants.

examples/scheduled/.gitignore

@@ -0,0 +1,2 @@
+!config/*.yml
+dockerrepos/

examples/scheduled/README.md

@@ -0,0 +1,89 @@
+# Configarr - scheduled exammple
+
+This is an example how you could run configarr in a scheduled manner outside of kubernetes.
+Kubernetes has built in support with CronJobs.
+
+URLs:
+
+- radarr: http://localhost:6501
+
+Cleanup:
+
+```bash
+docker-compose -f docker-compose.ofelia.yml down -v
+docker-compose -f docker-compose.cron.yml -p cron down -v
+docker-compose down -v
+```
+
+## Variant: Ofelia (recommended)
+
+Compose file: `docker-compose.ofelia.yml`
+
+This is run with the `ofelia` image.
+Check guide of ofelia for more configs.
+We can rerun an existing container and reuse it or create new containers.
+Check `ofelia.ini` for example.
+
+The example shows two variants.
+Please just use one which matches your needs.
+Both solutions work:
+
+- running with an existing container which always exits and will be restarted
+- always running a fresh new container.
+
+```bash
+# full path is needed in multiple docker-compose files. Either set direct in file or via env variable
+export CONFIGARR_FULL_PATH=$(pwd)
+docker-compose up -d
+
+# ofelia
+# Please update paths in ofelia.ini before running
+docker-compose -f docker-compose.ofelia.yml -p ofelia up -d
+docker-compose -f docker-compose.ofelia.yml -p ofelia logs
+# clean
+docker-compose -f docker-compose.ofelia.yml -p ofelia down -v
+```
+
+## Variant: Cron-Like
+
+Compose file: `docker-compose.cron.yml`
+
+This starts a container which will run cron and we have to mount cron like configurations.
+Check the compose file and mounted volumes for how this works.
+In summary: mount folder with cron files, cron triggers commands defined there.
+
+The example shows two variants.
+Please just use one which matches your needs.
+Both solutions work:
+
+- running with an existing container which always exits and will be restarted
+- always running a fresh new container.
+
+```bash
+# full path is needed in multiple docker-compose files. Either set direct in file or via env variable
+export CONFIGARR_FULL_PATH=$(pwd)
+docker-compose up -d
+
+# cron like
+# please update the paths and uncomment in dir ./cron/*
+docker-compose -f docker-compose.cron.yml -p cron up -d cron
+
+# Optional: If using the container reuse functionality:
+docker-compose -f docker-compose.cron.yml -p cron up -d configarr
+
+docker-compose -f docker-compose.cron.yml -p cron logs
+
+# clean
+docker-compose -f docker-compose.cron.yml -p cron down -v
+```
+
+## Side notes
+
+With approaches like this you can easily extends functionalities like:
+
+- notifications (errored state or not)
+- cleanup procedures
+
+## Drawbacks with some solutions
+
+- because we are reusing the `docker.sock` (this means running containers on the host) we have to use absolute paths for mounts.

examples/scheduled/config/config.yml

@@ -0,0 +1,21 @@
+#trashGuideUrl: https://github.com/BlackDark/fork-TRASH-Guides
+#recyclarrConfigUrl: https://github.com/BlackDark/fork-recyclarr-configs
+localCustomFormatsPath: /app/cfs
+localConfigTemplatesPath: /app/templates
+
+radarr:
+  instance1:
+    # Set the URL/API Key to your actual instance
+    base_url: http://radarr:7878
+    #base_url: https://sonarr.oci.eduard-marbach.de/
+    api_key: !secret RADARR_API_KEY
+
+    quality_definition:
+      type: movies
+
+    include:
+      - template: radarr-quality-definition-movie
+      - template: radarr-quality-profile-hd-bluray-web
+      - template: radarr-custom-formats-hd-bluray-web
+
+    custom_formats: []

examples/scheduled/config/secrets.yml

@@ -0,0 +1 @@
+RADARR_API_KEY: 0daa3a2b940f4e08bac991e9a30e9e12

examples/scheduled/cron/configarr-reuse

@@ -0,0 +1,4 @@
+LOGFILE_DEFAULT=/var/log/cron.log
+#CONFIGARR_FULL_PATH=/tmp/configarr/full/path
+
+* * * * * root docker compose -f /app/docker-compose.yaml -p cron start configarr >> $LOGFILE_DEFAULT 2>&1

examples/scheduled/cron/configarr-run

@@ -0,0 +1,4 @@
+LOGFILE_DEFAULT=/var/log/cron.log
+#CONFIGARR_FULL_PATH=/tmp/configarr/full/path
+
+* * * * * root docker compose -f /app/docker-compose.yaml -p cron run --rm configarr-run >> $LOGFILE_DEFAULT 2>&1

examples/scheduled/docker-compose.cron.yml

@@ -0,0 +1,32 @@
+services:
+  configarr:
+    image: ghcr.io/raydak-labs/configarr:latest
+    networks:
+      - configarr-full
+    volumes:
+      - ${CONFIGARR_FULL_PATH:?"missing"}/config:/app/config
+      - ${CONFIGARR_FULL_PATH:?"missing"}/dockerrepos:/app/repos
+      #- ${CONFIGARR_FULL_PATH:?"missing"}/cfs:/app/cfs
+      #- ${CONFIGARR_FULL_PATH:?"missing"}/templates:/app/templates
+
+  configarr-run:
+    image: ghcr.io/raydak-labs/configarr:latest
+    networks:
+      - configarr-full
+    volumes:
+      - ${CONFIGARR_FULL_PATH:?"missing"}/config:/app/config
+      - ${CONFIGARR_FULL_PATH:?"missing"}/dockerrepos:/app/repos
+      #- ${CONFIGARR_FULL_PATH:?"missing"}/cfs:/app/cfs
+      #- ${CONFIGARR_FULL_PATH:?"missing"}/templates:/app/templates
+
+  cron:
+    image: blackdark93/dockerfiles-cron-dind:main
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ${CONFIGARR_FULL_PATH:?"missing"}/cron:/app/schedules:ro
+      - ${CONFIGARR_FULL_PATH:?"missing"}/docker-compose.cron.yml:/app/docker-compose.yaml:ro
+
+networks:
+  configarr-full:
+    name: configarr-full
+    external: true

examples/scheduled/docker-compose.ofelia.yml

@@ -0,0 +1,24 @@
+services:
+  configarr:
+    container_name: configarr-reused
+    image: ghcr.io/raydak-labs/configarr:latest
+    networks:
+      - configarr-full
+    volumes:
+      - ./config:/app/config
+      - ./dockerrepos:/app/repos
+      #- ./cfs:/app/cfs
+      #- ./templates:/app/templates
+
+  ofelia:
+    image: mcuadros/ofelia:latest
+    command: daemon --config=/opt/config.ini
+    #command: daemon --docker
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - ./ofelia.ini:/opt/config.ini
+
+networks:
+  configarr-full:
+    name: configarr-full
+    external: true

examples/scheduled/docker-compose.yml

@@ -0,0 +1,22 @@
+services:
+  radarr:
+    image: lscr.io/linuxserver/radarr:5.15.1
+    networks:
+      - configarr-full
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=Etc/UTC
+    volumes:
+      - radarr:/config
+      - ${PWD}/radarr.xml:/config/config.xml:rw
+    ports:
+      - 6501:7878
+    restart: unless-stopped
+
+networks:
+  configarr-full:
+    name: configarr-full
+
+volumes:
+  radarr:

examples/scheduled/ofelia.ini

@@ -0,0 +1,15 @@
+; Example of how to run on existing container which will be restarted 
+[job-run "run-configarr-existing-container"]
+schedule = @every 10s
+container = configarr-reused
+
+; Creates new container and executes with given parameters
+[job-run "run-configarr-new-container"]
+schedule = @every 10s
+image = ghcr.io/raydak-labs/configarr:latest
+; Full path for volume
+volume = /tmp/configarr/full/path/config:/app/config
+volume = /tmp/configarr/full/path/dockerrepos:/app/repos
+;volume = /tmp/configarr/full/path/cfs:/app/cfs
+;volume = /tmp/configarr/full/path/templates:/app/templates
+network = configarr-full

examples/scheduled/radarr.xml

@@ -0,0 +1,17 @@
+<Config>
+  <BindAddress>*</BindAddress>
+  <Port>7878</Port>
+  <SslPort>9898</SslPort>
+  <EnableSsl>False</EnableSsl>
+  <LaunchBrowser>True</LaunchBrowser>
+  <ApiKey>0daa3a2b940f4e08bac991e9a30e9e12</ApiKey>
+  <AuthenticationMethod>Basic</AuthenticationMethod>
+  <AuthenticationRequired>DisabledForLocalAddresses</AuthenticationRequired>
+  <Branch>master</Branch>
+  <LogLevel>info</LogLevel>
+  <SslCertPath></SslCertPath>
+  <SslCertPassword></SslCertPassword>
+  <UrlBase></UrlBase>
+  <InstanceName>Radarr</InstanceName>
+  <UpdateMechanism>Docker</UpdateMechanism>
+</Config>