Skip to content

Commit 0867420

Browse files
rpattersonrpatterson
committed
fix(docker): Add default crontab download command
Clarify the `/config/ytdl-sub-configs/cron` script with explanatory comments and a default `--dry-run` command. Also change the wrapper script to echo commands for easier debugging. To update an existing script, move the old script aside, restart the container to regenerate it, and edit the new script. Also clarify the Automating page in the Getting Started guide docs.
1 parent 9cbb232 commit 0867420

File tree

8 files changed

+139
-81
lines changed

8 files changed

+139
-81
lines changed

‎docker/root/custom-cont-init.d/defaults‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,8 @@ if [ "$CRON_SCHEDULE" != "" ] ; then
3131

3232
# create cron script wrapper
3333
echo '#!/bin/bash' > "$CRON_WRAPPER_SCRIPT"
34+
# Echo commands for easier user debugging:
35+
echo "set -x" >> "$CRON_WRAPPER_SCRIPT"
3436
echo "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin" >> "$CRON_WRAPPER_SCRIPT"
3537
echo "cd \"$DEFAULT_WORKSPACE\"" >> "$CRON_WRAPPER_SCRIPT"
3638
echo ". \"$CRON_SCRIPT\" | tee -a \"$LOGS_TO_STDOUT\"" >> "$CRON_WRAPPER_SCRIPT"

‎docker/root/defaults/cron‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,12 @@
1-
echo "Beginning cron job..."
2-
31
# Place your ytdl-sub command(s) here.
4-
# This script is executed in the same relative path as this file.
2+
#
3+
# This script is executed in the same directory as this file which also contains the
4+
# default `./config.yaml` and `./subscriptions.yaml`, so you don't need to use the
5+
# `--config` CLI option or pass a `SUBPATH` to the `$ ytdl-sub sub` sub-command.
6+
#
7+
# To prevent users accidentally triggering throttles or bans or downloading before
8+
# testing their configuration, these default options only simulate a few
9+
# downloads. Remove the `--dry-run` and `-o ...` CLI options when you've tested your
10+
# configuration and you're ready to download entries unattended:
11+
12+
ytdl-sub --dry-run sub -o '--ytdl_options.max_downloads 3'

‎docs/source/faq/index.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,8 +41,8 @@ download your YouTube cookie, then add it to your :ref:`ytdl options
4141
...automate my downloads?
4242
~~~~~~~~~~~~~~~~~~~~~~~~~
4343

44-
:doc:`This page </guides/getting_started/automating_downloads>` shows how to set up
45-
``ytdl-sub`` to run automatically on various platforms.
44+
:doc:`This page </guides/getting_started/automating>` shows how to set up ``ytdl-sub``
45+
to run automatically on various platforms.
4646

4747
...download large channels?
4848
~~~~~~~~~~~~~~~~~~~~~~~~~~~

‎docs/source/guides/getting_started/automating.rst‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
Automating
2+
==========
3+
4+
Automate downloading your subscriptions by running the :ref:`'sub' sub-command
5+
<usage:subscriptions options>` periodically. There are various tools that can run
6+
commands on a schedule you may use any of them that work with your installation
7+
method. Most users use `cron`_ in `Docker containers <docker and unraid_>`_.
8+
9+
10+
Docker and Unraid
11+
-----------------
12+
13+
:doc:`The 'ytdl-sub' Docker container images <../install/docker>` provide optional cron
14+
support. Enable cron support by setting `a cron schedule`_ in the ``CRON_SCHEDULE``
15+
environment variable:
16+
17+
.. code-block:: yaml
18+
:caption: ./compose.yaml
19+
:emphasize-lines: 4
20+
21+
services:
22+
ytdl-sub:
23+
environment:
24+
CRON_SCHEDULE: "0 */6 * * *"
25+
26+
Then recreate the container to apply the change and start it to generate the default
27+
``/config/ytdl-sub-configs/cron`` script. Read the comments in that script and edit as
28+
appropriate.
29+
30+
The container cron wrapper script will write output from the cron job to
31+
``/config/ytdl-sub-configs/.cron.log``. The default image ``ENTRYPOINT`` will ``$ tail
32+
...`` that file so you can monitor the cron job in the container's output and thus also
33+
in the Docker logs.
34+
35+
36+
.. _linux-setup:
37+
38+
Linux, Mac OS X, BSD, or other UNIX's
39+
-------------------------------------
40+
41+
For installations on systems already running ``# crond``, you can also use cron to run
42+
``ytdl-sub`` periodically. Write a script to run ``ytdl-sub`` in the cron job. Be sure
43+
the script changes to the same directory as your configuration and uses the full path to
44+
``ytdl-sub``:
45+
46+
.. code-block:: shell
47+
:caption: ~/.local/bin/ytdl-sub-cron
48+
:emphasize-lines: 2,3
49+
50+
#!/bin/bash
51+
cd "~/.config/ytdl-sub/"
52+
~/.local/bin/ytdl-sub --dry-run sub -o '--ytdl_options.max_downloads 3' |&
53+
tee -a "~/.local/state/ytdl-sub/.cron.log"
54+
55+
Then tell ``# crond`` when to run the script:
56+
57+
.. code-block:: console
58+
59+
echo "0 */6 * * * ${HOME}/.local/bin/ytdl-sub-cron" | crontab "-"
60+
61+
Remove the ``--dry-run`` and ``-o ...`` CLI options from your cron script when you've
62+
tested your configuration and you're ready to download entries unattended.
63+
64+
65+
.. _windows-setup:
66+
67+
Windows
68+
-------
69+
70+
For most Windows users, the best way to run commands periodically is `the Task
71+
Scheduler`_:
72+
73+
.. attention::
74+
75+
These instructions are untested. Use at your own risk. If you use them, whether they
76+
work or not, please let us know how it went in `a support post in Discord`_ or `a new
77+
GitHub issue`_.
78+
79+
#. Open the Task Scheduler app.
80+
81+
#. Click ``Create Basic Task`` at the top of the right sidebar.
82+
83+
#. Set all the fields as appropriate until you get to the ``Action``...
84+
85+
#. For the ``Action``, select ``Start a program``...
86+
87+
#. Click ``Browse...`` to the installed ``ytdl-sub.exe`` executable...
88+
89+
#. Add CLI arguments to ``Add arguments (optional):``, for example ``--dry-run sub -o
90+
'--ytdl_options.max_downloads 3'``...
91+
92+
#. Set ``Start in (optional):`` to the directory containing your configuration.
93+
94+
#. Finish the rest of the ``Create Basic Task`` wizard.
95+
96+
97+
Next Steps
98+
----------
99+
100+
At this point, ``ytdl-sub`` should run periodically and keep your subscriptions current
101+
in your media library without your intervention. As your :doc:`subscriptions file
102+
<./subscriptions>` grows or you discover new use cases, it becomes worth while to
103+
simplify things by :doc:`defining your own custom presets <./first_config>`.
104+
105+
106+
107+
.. _`cron`:
108+
https://en.wikipedia.org/wiki/Cron
109+
.. _`a cron schedule`:
110+
https://en.wikipedia.org/wiki/Cron#Overview
111+
112+
.. _`the Task Scheduler`:
113+
https://learn.microsoft.com/en-us/windows/win32/taskschd/task-scheduler-start-page
114+
.. _`a support post in Discord`:
115+
https://discord.com/channels/994270357957648404/1084886228266127460
116+
.. _`a new GitHub issue`:
117+
https://github.com/jmbannon/ytdl-sub/issues/new

‎docs/source/guides/getting_started/automating_downloads.rst‎

Lines changed: 0 additions & 69 deletions
This file was deleted.

‎docs/source/guides/getting_started/index.rst‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,6 +152,6 @@ adding subscriptions <./subscriptions>`.
152152

153153
subscriptions
154154
first_download
155-
automating_downloads
155+
automating
156156
first_config
157157
quick_start

‎docs/source/guides/getting_started/quick_start.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -69,5 +69,5 @@ instructions to the letter.
6969

7070
#. Automate downloads:
7171

72-
:ref:`Set up ytdl-sub to run periodically
73-
<guides/getting_started/automating_downloads:docker and unraid>`.
72+
:ref:`Set up ytdl-sub to run periodically <guides/getting_started/automating:docker
73+
and unraid>`.

‎docs/source/guides/install/docker.rst‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ on top. There are two flavors or variants to choose from. For a more user-friend
77
experience editing the `configuration`_, we recommend the `GUI image`_
88
variant. :ref:`Docker Compose <guides/install/docker:install with docker compose>` is
99
the recommended way of managing a ``ytdl-sub`` docker container. See :ref:`Automating
10-
Downloads <guides/getting_started/automating_downloads:docker and unraid>` for how to
11-
automate running ``ytdl-sub`` in a container running either variant.
10+
Downloads <guides/getting_started/automating:docker and unraid>` for how to automate
11+
running ``ytdl-sub`` in a container running either variant.
1212

1313

1414
GUI Image
@@ -28,8 +28,8 @@ Headless Image
2828

2929
The headless image is based on LSIO's :lsio-gh:`docker-baseimage-alpine`. Once running,
3030
the default command just starts services including cron for :ref:`Automating Downloads
31-
<guides/getting_started/automating_downloads:docker and unraid>` but otherwise doesn't
32-
run ``ytdl-sub``. You may run arbitrary ``ytdl-sub`` commands using the
31+
<guides/getting_started/automating:docker and unraid>` but otherwise doesn't run
32+
``ytdl-sub``. You may run arbitrary ``ytdl-sub`` commands using the
3333
``--rm --user="${PUID}:${PGID}" --entrypoint="ytdl-sub"`` options to either ``$ docker
3434
run`` or ``$ docker compose run``. Overriding the image's ``ENTRYPOINT`` is important so
3535
that cron doesn't run ``ytdl-sub`` while you're running it manually.

0 commit comments

Comments
 (0)