docs(docker): Clarify container image install
Capturing my changes thus far while I go off to educate myself about rST/Sphinx refs vs
links. As such, this duplicates a reference link in a way I don't like:
:ref:`Automating Downloads <guides/getting_started/automating_downloads:docker and
unraid>`
If you want to fix that or are OK with the duplication, this should be ready to
go. Otherwise, I'll fix and force push once I've learned how to do this correctly.
A matter of opinion in this change, I did away with the tabbed GUI vs headless code
blocks and the separate CPU/GPU passthrough code blocks because I find comments in
example code to be more clear, more readable, and more approachable. This also has the
benefit of putting informative comments in the resulting user's configuration. For
example, imagine a user that learns only later that they require GPU passthrough, their
configuration is already ready to get them started. This comes at the cost some repeated
comments (`environment:` and `deploy:` for GPU passthrough) and the fancy Sphinx
highlighting of relevant lines. I think the trade-off is a net benefit for users.
This commit is contained in:
Ross Patterson
parent
d639045ba7
commit
66c792b80b
1 changed files with 70 additions and 113 deletions
|
|
@ -2,141 +2,95 @@
|
||||||
Docker
|
Docker
|
||||||
======
|
======
|
||||||
|
|
||||||
For automating ``subscriptions.yaml`` downloads to pull new media, see :ref:`this page <guides/getting_started/automating_downloads:docker and unraid>` on how to set up a cron job in any of the docker containers.
|
The ``ytdl-sub`` Docker images use :lsio:`LSIO-based images <\ >` and install ytdl-sub
|
||||||
|
on top. There are two flavors or variants to choose from. For a more user-friendly
|
||||||
The ``ytdl-sub`` Docker images use :lsio:`LSIO-based images <\ >` and install ytdl-sub on top. There are two flavors to choose from.
|
experience editing the `configuration`_, we recommend the `GUI image`_
|
||||||
|
variant. :ref:`Docker Compose <guides/install/docker:install with docker compose>` is
|
||||||
.. margin::
|
the recommended way of managing a ``ytdl-sub`` docker container. See :ref:`Automating
|
||||||
|
Downloads <guides/getting_started/automating_downloads:docker and unraid>` for how to
|
||||||
.. tip::
|
automate running ``ytdl-sub`` in a container running either variant.
|
||||||
|
|
||||||
The recommended docker image is the GUI image.
|
|
||||||
|
|
||||||
:ref:`Docker Compose <guides/install/docker:install with docker compose>` is the recommended way of setting up a ``ytdl-sub`` docker container.
|
|
||||||
|
|
||||||
GUI Image
|
GUI Image
|
||||||
---------
|
---------
|
||||||
|
|
||||||
The GUI image uses LSIO's :lsio-gh:`docker-code-server image <\ >` for its base image. More info on other code-server environment variables can be found within its documentation.
|
The GUI image is based on :lsio-gh:`LSIO's docker-code-server image <\ >` to provide you
|
||||||
|
full management of ``ytdl-sub``, such as file editing and terminal access, all within
|
||||||
|
your browser using the VS Code web UI. See its documentation regarding environment
|
||||||
|
variables and other details. Once running, open `the web UI`_ to edit the
|
||||||
|
`configuration`_ and run ``ytdl-sub``.
|
||||||
|
|
||||||
After starting, the code-server will be running at http://localhost:8443. Open this page in a browser to access and interact with ``ytdl-sub``.
|
.. _`the web UI`: http://localhost:8443
|
||||||
|
|
||||||
Headless Image
|
Headless Image
|
||||||
--------------
|
--------------
|
||||||
|
|
||||||
The headless image uses LSIO's :lsio-gh:`docker-baseimage-alpine image <\ >` for its base image. Execute the following command to access and interact with ``ytdl-sub``:
|
The headless image is based on :lsio-gh:`LSIO's docker-baseimage-alpine image <\
|
||||||
|
>`. Once running, the default command just starts services including cron for
|
||||||
|
:ref:`Automating Downloads <guides/getting_started/automating_downloads:docker and
|
||||||
|
unraid>` but otherwise doesn't run ``ytdl-sub``. You may run arbitrary ``ytdl-sub``
|
||||||
|
commands using the ``--rm --user="${PUID}:${PGID}" --entrypoint="ytdl-sub"`` options to
|
||||||
|
either ``$ docker run`` or ``$ docker compose run``. Overriding the image's
|
||||||
|
``ENTRYPOINT`` is important so that cron doesn't run ``ytdl-sub`` while you're running
|
||||||
|
it manually.
|
||||||
|
|
||||||
.. code-block:: bash
|
For example::
|
||||||
|
|
||||||
docker exec -u abc -it ytdl-sub /bin/bash
|
$ docker compose run --rm --user="${PUID}:${PGID}" --entrypoint="ytdl-sub" ytdl-sub sub
|
||||||
|
|
||||||
Install with Docker Compose
|
Install with Docker Compose
|
||||||
---------------------------
|
---------------------------
|
||||||
|
|
||||||
Docker Compose is an easy "set it and forget it" install method. Follow the instructions below to create a ``compose.yaml`` file for your chosen ``ytdl-sub`` image.
|
Docker Compose provides a declarative way to configure and orchestrate containers which
|
||||||
|
makes them easier to manage and re-use. Create a ``compose.yaml`` file in your project
|
||||||
.. margin::
|
directory such as:
|
||||||
|
|
||||||
.. important::
|
|
||||||
|
|
||||||
Set the PUID and PGID to the UID and GID associated with the user you want to own the downloaded files. Setting these values to root UID and GID may create issues with your media managers.
|
|
||||||
|
|
||||||
.. tab-set::
|
|
||||||
|
|
||||||
.. tab-item:: GUI Image
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
:caption: compose.yaml
|
|
||||||
|
|
||||||
services:
|
|
||||||
ytdl-sub:
|
|
||||||
image: ghcr.io/jmbannon/ytdl-sub-gui:latest
|
|
||||||
container_name: ytdl-sub
|
|
||||||
environment:
|
|
||||||
- PUID=1000
|
|
||||||
- PGID=1000
|
|
||||||
- TZ=America/Los_Angeles
|
|
||||||
volumes:
|
|
||||||
- <path/to/ytdl-sub/config>:/config
|
|
||||||
- <path/to/tv_shows>:/tv_shows # optional
|
|
||||||
- <path/to/movies>:/movies # optional
|
|
||||||
- <path/to/music_videos>:/music_videos # optional
|
|
||||||
- <path/to/music>:/music # optional
|
|
||||||
ports:
|
|
||||||
- 8443:8443
|
|
||||||
restart: unless-stopped
|
|
||||||
|
|
||||||
.. tab-item:: Headless Image
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
|
||||||
:caption: compose.yaml
|
|
||||||
|
|
||||||
services:
|
|
||||||
ytdl-sub:
|
|
||||||
image: ghcr.io/jmbannon/ytdl-sub:latest
|
|
||||||
container_name: ytdl-sub
|
|
||||||
environment:
|
|
||||||
- PUID=1000
|
|
||||||
- PGID=1000
|
|
||||||
- TZ=America/Los_Angeles
|
|
||||||
volumes:
|
|
||||||
- <path/to/ytdl-sub/config>:/config
|
|
||||||
- <path/to/tv_shows>:/tv_shows # optional
|
|
||||||
- <path/to/movies>:/movies # optional
|
|
||||||
- <path/to/music_videos>:/music_videos # optional
|
|
||||||
- <path/to/music>:/music # optional
|
|
||||||
restart: unless-stopped
|
|
||||||
|
|
||||||
Device Passthrough
|
|
||||||
~~~~~~~~~~~~~~~~~~~
|
|
||||||
For CPU or GPU passthrough, you must use either the GUI image or the headless Ubuntu image
|
|
||||||
``ghcr.io/jmbannon/ytdl-sub:ubuntu-latest``.
|
|
||||||
|
|
||||||
The docker-compose examples use the GUI image.
|
|
||||||
|
|
||||||
CPU Passthrough
|
|
||||||
^^^^^^^^^^^^^^^
|
|
||||||
|
|
||||||
.. code-block:: yaml
|
.. code-block:: yaml
|
||||||
:emphasize-lines: 5-6
|
:caption: compose.yaml
|
||||||
:caption: compose.yaml
|
|
||||||
|
|
||||||
services:
|
services:
|
||||||
ytdl-sub:
|
ytdl-sub:
|
||||||
image: ghcr.io/jmbannon/ytdl-sub-gui:latest
|
# The GUI image variant:
|
||||||
container_name: ytdl-sub
|
image: ghcr.io/jmbannon/ytdl-sub-gui:latest
|
||||||
devices:
|
# Or use the headless image variant:
|
||||||
- /dev/dri:/dev/dri # CPU passthrough
|
# image: ghcr.io/jmbannon/ytdl-sub:latest
|
||||||
restart: unless-stopped
|
# For CPU/GPU passthrough, use the GUI image above or the headless Ubuntu image:
|
||||||
|
# image: ghcr.io/jmbannon/ytdl-sub:ubuntu-latest
|
||||||
GPU Passthrough
|
container_name: ytdl-sub
|
||||||
^^^^^^^^^^^^^^^
|
restart: unless-stopped
|
||||||
|
environment:
|
||||||
.. Awe
|
- TZ=America/Los_Angeles
|
||||||
|
# Set these as appropriate so your users can access the downloaded files in
|
||||||
.. code-block:: yaml
|
# your library:
|
||||||
:caption: compose.yaml
|
- PUID=1000
|
||||||
:emphasize-lines: 5-13
|
- PGID=1000
|
||||||
|
# Optionally passthrough your NVidia GPU:
|
||||||
services:
|
# - NVIDIA_DRIVER_CAPABILITIES=all
|
||||||
ytdl-sub:
|
# - NVIDIA_VISIBLE_DEVICES=all
|
||||||
image: ghcr.io/jmbannon/ytdl-sub-gui:latest
|
volumes:
|
||||||
container_name: ytdl-sub
|
- <path/to/ytdl-sub/config>:/config
|
||||||
environment:
|
- <path/to/tv_shows>:/tv_shows # optional
|
||||||
- ..
|
- <path/to/movies>:/movies # optional
|
||||||
- NVIDIA_DRIVER_CAPABILITIES=all # Nvidia ENV args
|
- <path/to/music_videos>:/music_videos # optional
|
||||||
- NVIDIA_VISIBLE_DEVICES=all
|
- <path/to/music>:/music # optional
|
||||||
deploy:
|
# Not necessary for the headless image variant:
|
||||||
resources:
|
ports:
|
||||||
reservations:
|
- 8443:8443
|
||||||
devices:
|
# Optionally passthrough the CPU for hardware acceleration:
|
||||||
- capabilities: ["gpu"] # GPU passthrough
|
# devices:
|
||||||
restart: unless-stopped
|
# - /dev/dri:/dev/dri
|
||||||
|
# Optionally passthrough the GPU:
|
||||||
|
# deploy:
|
||||||
|
# resources:
|
||||||
|
# reservations:
|
||||||
|
# devices:
|
||||||
|
# - capabilities: ["gpu"]
|
||||||
|
|
||||||
Docker CLI
|
Docker CLI
|
||||||
----------
|
----------
|
||||||
|
|
||||||
If you prefer to only run the container once, you can use the CLI command instead. The following command is for the gui image, and will not restart if it comes down for any reason. See `the Docker reference <https://docs.docker.com/engine/reference/run/>`_ for further information on the parameters and other options you can use.
|
You can run the container on an ad-hoc basis without Docker Compose using the Docker CLI
|
||||||
|
instead. It will not restart if stopped for any reason, including rebooting the
|
||||||
|
host. The following command is for the gui image:
|
||||||
|
|
||||||
.. code-block:: bash
|
.. code-block:: bash
|
||||||
|
|
||||||
|
|
@ -153,6 +107,9 @@ If you prefer to only run the container once, you can use the CLI command instea
|
||||||
-v <OPTIONAL/path/to/music>:/music \
|
-v <OPTIONAL/path/to/music>:/music \
|
||||||
ghcr.io/jmbannon/ytdl-sub-gui:latest
|
ghcr.io/jmbannon/ytdl-sub-gui:latest
|
||||||
|
|
||||||
|
See `the Docker reference <https://docs.docker.com/engine/reference/run/>`_ for further
|
||||||
|
details.
|
||||||
|
|
||||||
Configuration
|
Configuration
|
||||||
-------------
|
-------------
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue