From 7f6862efe9a62d8d88ef0ea05924879a2ebf70d1 Mon Sep 17 00:00:00 2001 From: Jeff Ohrstrom Date: Fri, 8 Dec 2023 12:46:31 -0500 Subject: [PATCH] add docs on vnc_container bc templates (#908) Add documentation on vnc_container batch connect templates. --- .../app-development/interactive/submit.rst | 38 +++-- source/reference/files/submit-yml-erb.rst | 1 + .../submit-yml/vnc-container-bc-options.rst | 142 ++++++++++++++++++ 3 files changed, 171 insertions(+), 10 deletions(-) create mode 100644 source/reference/files/submit-yml/vnc-container-bc-options.rst diff --git a/source/how-tos/app-development/interactive/submit.rst b/source/how-tos/app-development/interactive/submit.rst index e83d3e2a..7b733c9f 100644 --- a/source/how-tos/app-development/interactive/submit.rst +++ b/source/how-tos/app-development/interactive/submit.rst @@ -96,23 +96,41 @@ The three possible configuration options that can be used in the Each of these configuration options take a set of their own configuration options described below. -Configure Batch Connect -``````````````````````` +Batch Connect Template types +```````````````````````````` -All batch scripts are generated from either the ``basic`` template or the -``vnc`` template specified with the following configuration option: +Open OnDemand has three distinct batch connect template types. +These template types determine the resulting shell scripts that wrap +your batch connect application. + +For example the ``vnc`` type will provide a script that boots up a +VNC server, exports a ``DISPLAY`` variable and other utilities to +ensure that the job has been bootstrapped appropriately to +start GUI applications. + +The options available are ``basic``, ``vnc`` or ``vnc_container``. +``vnc_container`` is basically just like ``vnc`` only in that it +boostraps the VNC programs inside a container instead of on the +host machine. .. describe:: template (String) - the template used for rendering the batch script (``"basic"`` or ``"vnc"``) + The template used to create the wrapper script for your batch connect + application. - Default - ``"basic"`` + Default + Generate a basic wrapper script for HTTP applications. - Example - Render a batch script for a VNC Interactive Application + .. code-block:: yaml - .. code-block:: yaml + --- + batch_connect: + template: "basic" + + Example + Generate a wrapper script for a VNC interactive application. + + .. code-block:: yaml # ${HOME}/ondemand/dev/my_app/submit.yml.erb --- diff --git a/source/reference/files/submit-yml-erb.rst b/source/reference/files/submit-yml-erb.rst index 2ea53169..caf820c3 100644 --- a/source/reference/files/submit-yml-erb.rst +++ b/source/reference/files/submit-yml-erb.rst @@ -16,6 +16,7 @@ These are reference pages, you can see submit-yml/basic-bc-options submit-yml/vnc-bc-options + submit-yml/vnc-container-bc-options submit-yml/script Simple Example diff --git a/source/reference/files/submit-yml/vnc-container-bc-options.rst b/source/reference/files/submit-yml/vnc-container-bc-options.rst new file mode 100644 index 00000000..0f843060 --- /dev/null +++ b/source/reference/files/submit-yml/vnc-container-bc-options.rst @@ -0,0 +1,142 @@ +.. _vnc-container-bc-options: + +Batch Connect VNC Container Options +=================================== + + +All the options in :ref:`vnc-bc-options` apply in addition to what's listed below. + + # @option context [#to_s] :container_path ("vnc_container.sif") the path + # to the container with VNC + # @option context [#to_s] :container_bindpath ("") paths to bind into + # the container with VNC + # @option context [#to_s] :container_module ("singularity") the module + # that loads Singularity or Apptainer with Lmod. Supports versions (i.e. + # apptainer/1.10). If Singularity or Apptainer are installed at a + # system level (i.e., no module loaded to activate), set this to an + # empty string. + # @option context [#to_s] :container_command ("singularity") the + # singularity or apptainer execution command + + .. code-block:: yaml + + batch_connect: + template: "vnc_container" + # other 'vnc' or 'basic' options removed for brevity. + container_path: "vnc_container.sif" + container_bindpath: "" + container_module: "singularity" + container_command: "singularity" + + +.. describe:: container_path (String, "vnc_container.sif") + + The full path to the container image you wish to boot. + + Default + Load the vnc_container.sif image. + + .. code-block:: yaml + + container_path: "vnc_container.sif" + + Example + Provide an absolute path to a ``vnc_container.sif`` image. + + .. code-block:: yaml + + container_path: "/absolute/path/to/my/container/vnc_container.sif" + +.. describe:: container_bindpath (String, "") + + A comma seperated list of mountpoints you wish to bind into the container. + + Default + Do not bind any paths into the container. + + .. code-block:: yaml + + container_bindpath: "" + + Example + Bind /etc, /dev and /usr into the container. + + .. code-block:: yaml + + container_bindpath: "/etc,/dev,/usr" + +.. describe:: container_module (String, "singularity") + + The module to load before starting the container. + + Default + Load the ``singularity`` module. + + .. code-block:: yaml + + container_module: "singularity" + + Example + Load the ``singularity/1.1.3`` module. + + .. code-block:: yaml + + container_module: "singularity/1.1.3" + +.. describe:: container_command (String, "singularity") + + The command used to start the container. + + Default + Use the ``singularity`` command. + + .. code-block:: yaml + + container_module: "singularity" + + Example + Use the ``apptainer`` command. + + .. code-block:: yaml + + container_module: "apptainer" + + +Starter def file +................ + +This is a ``.def`` file that we've tested this feature with. +You can use this as an example to start and update as required. + + +.. note:: + Note that we're installing turbovnc and websockify *inside* + the container. This is important as all processes will run + inside the contianer and not on the host. + + You can still install these on the host machine, but they will + need to be mounted inside the container as the processes are + expected to be ran *inside* the container. + +.. code-block:: singularity + + Bootstrap: docker + + From: rockylinux/rockylinux:8 + + %environment + PATH=/opt/TurboVNC/bin:$PATH + LANGUAGE="en_US.UTF-8" + LC_ALL="en_US.UTF-8" + LANG="en_US.UTF-8" + + %post + dnf install -y epel-release + dnf groupinstall -y xfce + dnf install -y python3-pip xorg-x11-xauth + pip3 install ts + dnf install -y https://yum.osc.edu/ondemand/latest/compute/el8Server/x86_64/python3-websockify-0.10.0-1.el8.noarch.rpm + dnf install -y https://yum.osc.edu/ondemand/latest/compute/el8Server/x86_64/turbovnc-2.2.5-1.el8.x86_64.rpm + dnf clean all + chown root:root /opt/TurboVNC/etc/turbovncserver-security.conf + rm -rf /var/cache/dnf/*