diff --git a/docs/source/config_reference/plugins.rst b/docs/source/config_reference/plugins.rst index 1fd114ab..bc8bf0a3 100644 --- a/docs/source/config_reference/plugins.rst +++ b/docs/source/config_reference/plugins.rst @@ -852,10 +852,11 @@ for representing audio albums. static_nfo_tags --------------- -Adds an NFO file for every entry, but does not link it to an entry in the download archive. -This is intended to produce ``season.nfo``s in each season directory. Each entry within a -season will overwrite this file with its season name. If the entry gets deleted from ytdl-sub, -this file will remain since it's not linked. +Adds an NFO file for every entry, but does not link it to an entry in the download +archive. This is intended to produce ``season.nfo`` files in each season +directory. Each entry within a season will overwrite this file with its season +name. If the entry gets deleted from ytdl-sub, this file will remain since it's not +linked. Usage: diff --git a/docs/source/guides/getting_started/index.rst b/docs/source/guides/getting_started/index.rst index c86ed757..b5ecf033 100644 --- a/docs/source/guides/getting_started/index.rst +++ b/docs/source/guides/getting_started/index.rst @@ -4,20 +4,23 @@ Getting Started Prerequisite Knowledge ---------------------- -In order to use ``ytdl-sub`` in any of the forms listed in these docs, you will need some basic knowledge. +As a lower level tool with no GUI, ``ytdl-sub`` requires some technical knowledge. You +must be able to: -Be sure that you: - ☑ Can navigate directories in a command line interface (or CLI) +- do `basic CLI shell navigation`_ +- read and write `YAML text files`_ - ☑ Have a basic understanding of YAML syntax +If you plan on using a :ref:`Docker headless image variant +` of ``ytdl-sub``, you can: -If you plan on using the headless image of ``ytdl-sub``, you: - ☑ Can use ``nano`` or ``vim`` to edit OR +- use ``$ nano /config/...`` to edit configuration files inside the container +- or bind mount ``/config/`` as a Docker volume and use the editor of your choice from + the host - ☑ Can mount the config directory somewhere you can open it using gui text editors +.. _`basic CLI shell navigation`: + https://developer.mozilla.org/en-US/docs/Learn_web_development/Getting_started/Environment_setup/Command_line +.. _`YAML text files`: http://thomasloven.com/blog/2018/08/YAML-For-Nonprogrammers/ -Additional useful (but not required) knowledge: - ☑ Understanding how :yt-dlp:`\ ` works Terminology ----------- diff --git a/docs/source/guides/install/docker.rst b/docs/source/guides/install/docker.rst index b9813e94..9aac6419 100644 --- a/docs/source/guides/install/docker.rst +++ b/docs/source/guides/install/docker.rst @@ -2,141 +2,94 @@ Docker ====== -For automating ``subscriptions.yaml`` downloads to pull new media, see :ref:`this page ` 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 to choose from. - -.. margin:: - - .. tip:: - - The recommended docker image is the GUI image. - - :ref:`Docker Compose ` is the recommended way of setting up a ``ytdl-sub`` docker container. +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 +experience editing the `configuration`_, we recommend the `GUI image`_ +variant. :ref:`Docker Compose ` is +the recommended way of managing a ``ytdl-sub`` docker container. See :ref:`Automating +Downloads ` for how to +automate running ``ytdl-sub`` in a container running either variant. 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's :lsio-gh:`docker-code-server` 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 -------------- -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's :lsio-gh:`docker-baseimage-alpine`. Once running, +the default command just starts services including cron for :ref:`Automating Downloads +` 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 --------------------------- -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. - -.. margin:: - - .. 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: - - :/config - - :/tv_shows # optional - - :/movies # optional - - :/music_videos # optional - - :/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: - - :/config - - :/tv_shows # optional - - :/movies # optional - - :/music_videos # optional - - :/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 -^^^^^^^^^^^^^^^ +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 +directory such as: .. code-block:: yaml - :emphasize-lines: 5-6 - :caption: compose.yaml + :caption: compose.yaml - services: - ytdl-sub: - image: ghcr.io/jmbannon/ytdl-sub-gui:latest - container_name: ytdl-sub - devices: - - /dev/dri:/dev/dri # CPU passthrough - restart: unless-stopped - -GPU Passthrough -^^^^^^^^^^^^^^^ - -.. Awe - -.. code-block:: yaml - :caption: compose.yaml - :emphasize-lines: 5-13 - - services: - ytdl-sub: - image: ghcr.io/jmbannon/ytdl-sub-gui:latest - container_name: ytdl-sub - environment: - - .. - - NVIDIA_DRIVER_CAPABILITIES=all # Nvidia ENV args - - NVIDIA_VISIBLE_DEVICES=all - deploy: - resources: - reservations: - devices: - - capabilities: ["gpu"] # GPU passthrough - restart: unless-stopped + services: + ytdl-sub: + # The GUI image variant: + image: ghcr.io/jmbannon/ytdl-sub-gui:latest + # Or use the headless image variant: + # image: ghcr.io/jmbannon/ytdl-sub:latest + # For CPU/GPU passthrough, use the GUI image above or the headless Ubuntu image: + # image: ghcr.io/jmbannon/ytdl-sub:ubuntu-latest + container_name: ytdl-sub + restart: unless-stopped + environment: + - TZ=America/Los_Angeles + # Set these as appropriate so your users can access the downloaded files in + # your library: + - PUID=1000 + - PGID=1000 + # Optionally passthrough your NVidia GPU: + # - NVIDIA_DRIVER_CAPABILITIES=all + # - NVIDIA_VISIBLE_DEVICES=all + volumes: + - :/config + - :/tv_shows # optional + - :/movies # optional + - :/music_videos # optional + - :/music # optional + # Not necessary for the headless image variant: + ports: + - 8443:8443 + # Optionally passthrough the CPU for hardware acceleration: + # devices: + # - /dev/dri:/dev/dri + # Optionally passthrough the GPU: + # deploy: + # resources: + # reservations: + # devices: + # - capabilities: ["gpu"] 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 `_ 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 @@ -153,6 +106,9 @@ If you prefer to only run the container once, you can use the CLI command instea -v :/music \ ghcr.io/jmbannon/ytdl-sub-gui:latest +See `the Docker reference `_ for further +details. + Configuration ------------- diff --git a/docs/source/guides/install/index.rst b/docs/source/guides/install/index.rst index ff1d293f..75cc02de 100644 --- a/docs/source/guides/install/index.rst +++ b/docs/source/guides/install/index.rst @@ -8,7 +8,7 @@ All installations require a 64-bit CPU. 32-bit is not supported. .. tip:: - The recommended install method of ``ytdl-sub`` is one of our :doc:`docker containers `. For install on Unraid, check out our :unraid:`unraid community apps `. + The recommended install method of ``ytdl-sub`` is one of our :doc:`docker containers `. :doc:`/guides/install/docker` diff --git a/src/ytdl_sub/plugins/static_nfo_tags.py b/src/ytdl_sub/plugins/static_nfo_tags.py index e4c1dbea..3476bda5 100644 --- a/src/ytdl_sub/plugins/static_nfo_tags.py +++ b/src/ytdl_sub/plugins/static_nfo_tags.py @@ -7,10 +7,11 @@ from ytdl_sub.validators.string_formatter_validators import StringFormatterValid class StaticNfoTagsOptions(SharedNfoTagsOptions): """ - Adds an NFO file for every entry, but does not link it to an entry in the download archive. - This is intended to produce ``season.nfo``s in each season directory. Each entry within a - season will overwrite this file with its season name. If the entry gets deleted from ytdl-sub, - this file will remain since it's not linked. + Adds an NFO file for every entry, but does not link it to an entry in the download + archive. This is intended to produce ``season.nfo`` files in each season + directory. Each entry within a season will overwrite this file with its season + name. If the entry gets deleted from ytdl-sub, this file will remain since it's not + linked. Usage: