23b5be713f
From [PR feedback](https://github.com/jmbannon/ytdl-sub/pull/1321#discussion_r2320515419).
135 lines
4.6 KiB
ReStructuredText
135 lines
4.6 KiB
ReStructuredText
Automating
|
|
==========
|
|
|
|
Automate downloading your subscriptions by running the :ref:`'sub' sub-command
|
|
<usage:subscriptions options>` periodically. There are various tools that can run
|
|
commands on a schedule you may use any of them that work with your installation
|
|
method. Most users use `cron`_ in `Docker containers <docker and unraid_>`_.
|
|
|
|
|
|
Docker and Unraid
|
|
-----------------
|
|
|
|
:doc:`The 'ytdl-sub' Docker container images <../install/docker>` provide optional cron
|
|
support. Enable cron support by setting `a cron schedule`_ in the ``CRON_SCHEDULE``
|
|
environment variable:
|
|
|
|
.. code-block:: yaml
|
|
:caption: ./compose.yaml
|
|
:emphasize-lines: 4
|
|
|
|
services:
|
|
ytdl-sub:
|
|
environment:
|
|
CRON_SCHEDULE: "0 */6 * * *"
|
|
|
|
Then recreate the container to apply the change and start it to generate the default
|
|
``/config/ytdl-sub-configs/cron`` script. Read the comments in that script and edit as
|
|
appropriate.
|
|
|
|
The container cron wrapper script will write output from the cron job to
|
|
``/config/ytdl-sub-configs/.cron.log``. The default image ``ENTRYPOINT`` will ``$ tail
|
|
...`` that file so you can monitor the cron job in the container's output and thus also
|
|
in the Docker logs.
|
|
|
|
You may also set the ``CRON_RUN_ON_START`` environment variable to ``true`` to have the
|
|
image run your cron script whenever the container starts in addition to the cron
|
|
schedule.
|
|
|
|
.. warning::
|
|
|
|
Using ``CRON_RUN_ON_START`` is not recommended because it may cause your cron script
|
|
to run too often and may trigger throttles and bans. When enabled, your cron script
|
|
will run *whenever* the container starts including when the host reboots, when ``#
|
|
dockerd`` is upgraded, when a new image is pulled, when something applies Compose
|
|
changes, etc.. This may result in running ``ytdl-sub`` right before or after the next
|
|
cron scheduled run or even at the same time on top of each other. Instead, run your
|
|
cron script manually inside the running container as needed:
|
|
|
|
.. code-block:: console
|
|
|
|
docker compose exec ytdl-sub bash /config/ytdl-sub-configs/cron
|
|
|
|
|
|
.. _linux-setup:
|
|
|
|
Linux, Mac OS X, BSD, or other UNIX's
|
|
-------------------------------------
|
|
|
|
For installations on systems already running ``# crond``, you can also use cron to run
|
|
``ytdl-sub`` periodically. Write a script to run ``ytdl-sub`` in the cron job. Be sure
|
|
the script changes to the same directory as your configuration and uses the full path to
|
|
``ytdl-sub``:
|
|
|
|
.. code-block:: shell
|
|
:caption: ~/.local/bin/ytdl-sub-cron
|
|
:emphasize-lines: 2,3
|
|
|
|
#!/bin/bash
|
|
cd "~/.config/ytdl-sub/"
|
|
~/.local/bin/ytdl-sub --dry-run sub -o '--ytdl_options.max_downloads 3' |&
|
|
tee -a "~/.local/state/ytdl-sub/.cron.log"
|
|
|
|
Then tell ``# crond`` when to run the script:
|
|
|
|
.. code-block:: console
|
|
|
|
echo "0 */6 * * * ${HOME}/.local/bin/ytdl-sub-cron" | crontab "-"
|
|
|
|
Remove the ``--dry-run`` and ``-o ...`` CLI options from your cron script when you've
|
|
tested your configuration and you're ready to download entries unattended.
|
|
|
|
|
|
.. _windows-setup:
|
|
|
|
Windows
|
|
-------
|
|
|
|
For most Windows users, the best way to run commands periodically is `the Task
|
|
Scheduler`_:
|
|
|
|
.. attention::
|
|
|
|
These instructions are untested. Use at your own risk. If you use them, whether they
|
|
work or not, please let us know how it went in `a support post in Discord`_ or `a new
|
|
GitHub issue`_.
|
|
|
|
#. Open the Task Scheduler app.
|
|
|
|
#. Click ``Create Basic Task`` at the top of the right sidebar.
|
|
|
|
#. Set all the fields as appropriate until you get to the ``Action``...
|
|
|
|
#. For the ``Action``, select ``Start a program``...
|
|
|
|
#. Click ``Browse...`` to the installed ``ytdl-sub.exe`` executable...
|
|
|
|
#. Add CLI arguments to ``Add arguments (optional):``, for example ``--dry-run sub -o
|
|
'--ytdl_options.max_downloads 3'``...
|
|
|
|
#. Set ``Start in (optional):`` to the directory containing your configuration.
|
|
|
|
#. Finish the rest of the ``Create Basic Task`` wizard.
|
|
|
|
|
|
Next Steps
|
|
----------
|
|
|
|
At this point, ``ytdl-sub`` should run periodically and keep your subscriptions current
|
|
in your media library without your intervention. As your :doc:`subscriptions file
|
|
<./subscriptions>` grows or you discover new use cases, it becomes worth while to
|
|
simplify things by :doc:`defining your own custom presets <./first_config>`.
|
|
|
|
|
|
|
|
.. _`cron`:
|
|
https://en.wikipedia.org/wiki/Cron
|
|
.. _`a cron schedule`:
|
|
https://crontab.cronhub.io/
|
|
|
|
.. _`the Task Scheduler`:
|
|
https://learn.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page
|
|
.. _`a support post in Discord`:
|
|
https://discord.com/channels/994270357957648404/1084886228266127460
|
|
.. _`a new GitHub issue`:
|
|
https://github.com/jmbannon/ytdl-sub/issues/new
|