deploy: 6a868cc

2024.8.1gui/.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: 9b5ca99a40dface56730f10febf94955
+tags: 645f666f9bcd5a90fca523b33c5a78b7

2024.8.1gui/_sources/explanations.rst.txt

@@ -0,0 +1,13 @@
+:orphan:
+
+Explanations
+============
+
+Explanation of how the library works and why it works that way.
+
+.. toctree::
+    :caption: Explanations
+
+    explanations/how_it_works
+    explanations/differences
+    explanations/why_dev_c7

2024.8.1gui/_sources/explanations/differences.rst.txt

@@ -0,0 +1,76 @@
+RHEL7 native vs dev-c7
+======================
+
+The ``dev-c7`` container attempts to emulate the same environment and file systems
+that a DLS RHEL7 workstation sees. Inevitably there are a few differences
+which are documented on this page.
+
+Centos vs RHEL7
+---------------
+
+This container is based upon a Centos 7 image rather than a RHEL7 image
+because of complicated licensing for RHEL7 containers. In almost all
+respects this should make little difference because both OSes have the
+same packages available to them.
+
+Any code that queries the OS name will get a different answer. This affects
+dls-release.py because it uses the OS name to choose the default RHEL version
+to release to. However this has been patched to accept Centos 7 to mean
+a release for RHEL7.
+
+We are not aware of any other DLS tools affected by this at present.
+
+User IDs
+--------
+
+Inside of the container there are only two interactive users. Your own user
+and root. ``c7`` uses ``--userns=keep-id`` so that your same user id
+is used inside and outside of the container.
+
+Hence the container is able to see the file ownership of mounted file systems
+as long as they belong to root or to you.
+
+No other users are known to it and when listing the contents of
+a shared directory any files that have unknown user group membership will
+show up as uid or gid 65534.
+
+This does not affect your ability to write to files that have permission for
+your secondary group. So files with group write for the dcs account will
+be writeable. Unfortunately you will not be able to tell they are writeable
+by using ls -l because the dcs group is unknown inside the container.
+
+e.g.
+
+.. raw:: html
+
+    <pre><font color="#64BA12">(master) </font>[<font color="#6491CB">hgv27681@dev-c7</font> etc]$ pwd
+    /dls_sw/work/R3.14.12.7/support/BL16I-BUILDER/etc
+    <font color="#64BA12">(master) </font>[<font color="#6491CB">hgv27681@dev-c7</font> etc]$ &gt; giles-wrote-this.txt
+    <font color="#64BA12">(master) </font>[<font color="#6491CB">hgv27681@dev-c7</font> etc]$ ls -l
+    total 24
+    -rw-rw-r--. 1 hgv27681 65534     0 Jun 24 10:25 giles-wrote-this.txt
+    -rwxrwxr-x. 1    65534 65534  1018 Feb 21  2019 <font color="#8AE234"><b>home_pa_slits.py</b></font>
+    -rw-rw-r--. 1    65534 65534   269 Feb 21  2019 Makefile
+    drwxrwsr-x. 5    65534 65534 16384 Jun 13 16:41 <font color="#729FCF"><b>makeIocs</b></font>
+    -rw-rw-r--. 1    65534 65534    29 Feb 21  2019 module.ini
+    </pre>
+
+
+No Services
+-----------
+
+By default a container runs a single process (of id 1) and terminates when
+that process terminates. ``c7`` launches a background process
+that does nothing as process 1 and
+then executes any number of interactive shells inside of it.
+
+Although you
+have the filesystem of a Centos 7 workstation inside the
+container, by design it is not an entire virtual machine.
+
+Therefore none of the usual services will be running inside of the container.
+For example any apps that wish to communicate over DBus will not find the DBus
+service.
+
+So far this has not affected any DLS development workflow. It may be possible
+to launch services inside the container if they prove to be essential.

2024.8.1gui/_sources/explanations/how_it_works.rst.txt

@@ -0,0 +1,99 @@
+How the dev-c7 Container Works
+==============================
+
+
+Podman
+------
+
+Podman is a daemonless, rootless container engine developed by RedHat,
+designed as an alternative to Docker.
+
+Using containers allows us to package up all the dependencies of an
+application and execute it in an isolated fashion.
+
+In the case of ``dev-c7`` we use podman to package up everything required
+by the DLS controls developer workflow. This is essentially a set
+of system libraries and tools plus mounted shared file systems such
+as ``/dls_sw`` and ``/home``.
+
+Containers
+----------
+
+A quote from docker.com:
+
+.. tip::
+
+    A container is a standard unit of software that packages up code and all its dependencies so the application runs quickly and reliably from one computing environment to another. A Docker container image is a lightweight, standalone, executable package of software that includes everything needed to run an application: code, runtime, system tools, system libraries and settings.
+
+An image is a layered snapshot of a file system. Images adhere to the
+`Open Container Initiative <https://opencontainers.org/release-notices/v1-0-2-image-spec/>`_
+standard and therefore images built by Docker and Podman are interchangeable.
+
+Images are stored in a container registry such as DockerHub or GitHub Container
+Registry https://ghcr.io. The image for ``dev-c7`` is stored alongside its source
+code here:
+
+    https://ghcr.io/dls-controls/dev-c7:latest
+
+The ``c7`` script uses ``podman run`` to create a container based on
+the above image. The container is an isolated execution environment with
+its own file system based upon the above image. Any changes to the
+file system are added in a layered fashion.
+
+The container's file system changes are lost when the container is deleted.
+However with ``c7`` we arrange for that to happen only if
+the user explicitly deletes ``dev-c7``.
+
+
+Container lifetime
+------------------
+
+The script ``c7`` launches a container in the background using
+podman. It then executes an interactive bash shell inside of that
+container.
+
+This means that when you exit the bash prompt the container continues to
+run in the background.
+
+Further invocations of ``c7`` will execute further interactive bash
+shells in the same container.
+
+If the container is stopped (via ``podman stop dev-c7`` or due to a host
+reboot) then the next invocation of ``c7`` will detect this and
+restart it.
+
+Because of this the ``dev-c7`` container is not ephemeral like most containers,
+it persists changes that you make in the OS until it is explicitly deleted.
+
+File Systems
+------------
+
+The system partition in which the operating system is installed resides
+inside the container. However ``c7`` mounts a number of host and
+shared file systems. This is how the container is made to look very
+similar to a RHEL7 workstation. The mounted file systems are as follows::
+
+    /dls_sw/prod:/dls_sw/prod
+    /dls_sw/work:/dls_sw/work
+    /dls_sw/epics:/dls_sw/epics
+    /dls_sw/targetOS/vxWorks/Tornado-2.2:/dls_sw/targetOS/vxWorks/Tornado-2.2
+    /dls_sw/apps:/dls_sw/apps
+    /dls_sw/etc:/dls_sw/etc
+    /scratch:/scratch
+    /home:/home
+    /tmp:/tmp
+    /dls/science/users/:/dls/science/users/
+
+User Profile
+------------
+
+``c7`` executes ``bash -l`` in order to create an interactive
+shell in the container. The following features make this work:
+
+- The home directories folder /home is mounted
+- the HOME environment variable is passed into the container
+- the user namespace is mapped into the container namespace
+
+The above points mean that bash is able to run ``.bash_profile`` from your
+home directory under your account. Hence all the usual DLS profile
+features are loaded.

2024.8.1gui/_sources/explanations/why_dev_c7.rst.txt

@@ -0,0 +1,24 @@
+Purpose of the dev-c7 Container
+===============================
+
+This project allows controls developers to continue to work on IOCs and tools
+built for RHEL7, while at the same time allowing the DLS wide upgrade to
+RHEL8 to continue. 
+
+Some details of the plan to achieve this are here 
+https://confluence.diamond.ac.uk/x/NY8DCQ
+
+Previously the task of upgrading from RHEL6 to RHEL7 proved to be quite
+complicated and took several years to finalize.
+
+Hence this project is a stopgap so that we can use effort to work on replacing 
+our
+tools and deployment process with one based on containers and Kubernetes. 
+Some details of the epics-containers approach are documented here
+https://github.com/epics-containers.
+
+With the new approach under development it would be a waste of effort to
+port our legacy toolchain to RHEL8 only to replace it shortly afterward.
+The container based approach decouples the tools and IOCs from the
+host operating system so any future OS upgrades should be far 
+smoother.

2024.8.1gui/_sources/how-to.rst.txt

@@ -0,0 +1,15 @@
+:orphan:
+
+How-to Guides
+=============
+
+Practical step-by-step guides for the more experienced user.
+
+.. toctree::
+    :caption: How-to Guides
+
+    how-to/containers
+    how-to/troubleshooting
+    how-to/deriving
+    how-to/podman
+

2024.8.1gui/_sources/how-to/containers.rst.txt

@@ -0,0 +1,122 @@
+Managing Containers and Images on a Workstation
+===============================================
+
+Definitions
+-----------
+
+**Images** are snapshots of a filesystem used to bootstrap a container.
+
+**Containers** are isolated execution environments with their file system based
+upon an Image.
+
+Monitoring
+----------
+
+You can see which **Containers** are running on your system with::
+
+    podman ps -a
+
+The ``-a`` means it will also show stopped containers.
+
+You can see what **Images** are cached on your system with::
+
+    podman images
+
+Images are usually cached from a container registry like ghcr.io. They can
+usually be deleted without any consequence except waiting for the download
+next time you launch a container that uses them.
+
+Cleaning Up Space
+-----------------
+
+The container and image cache is stored in /scratch/<fed_id>/podman. If you
+are short on space you can use the following.
+
+To remove temporary images and stopped containers::
+
+    podman system prune
+
+To remove individual images::
+
+    podman rmi IMAGE_ID # from third column of podman images
+
+    OR ...
+
+    podman rmi REPOSITORY:TAG # 1st , 2nd columns of podman images
+
+To remove all images with wildcard on REPOSITORY::
+
+    podman rmi $(podman images --filter=reference='*PATTERN*' -q)
+
+    # PATTERN matches the REPOSITORY column
+
+
+.. _dockerfile:
+
+Defining a Container Image
+==========================
+
+The dev-c7 container image is built from the container context folder
+``dev-c7/docker``.
+The context contains a Dockerfile which details the steps to build the
+container image.
+
+To experiment with making additions to the dev-c7 project, first clone
+the project and do a test build of the container::
+
+    git clone https://dls-controls.github.io/dev-c7/main/index.html
+    cd dev-c7
+    ./build-dev-c7
+
+``build-dev-c7`` will create a container image with the tag
+``ghcr.io/dls-controls/dev-c7``. This is the same tag that ``c7``
+uses so it will launch a container based on your newly built image.
+
+.. note::
+    You will likely already have a dev-c7 container running and you must delete
+    that before your new one will launch. Otherwise the launch script will
+    just open a new bash session in the existing container.
+    To do this see `deleting`.
+
+Now you are ready to make any changes you wish to the Dockerfile and add
+any additional files to the context (i.e. in the ``dev-c7/docker`` folder).
+
+Below is the current Dockerfile, read on for an explanation of the
+commands used.
+
+
+.. literalinclude:: ../../docker/Dockerfile
+   :language: docker
+
+
+
+The base image is selected with the ``FROM`` command this defines what the
+container file system looks like initially. Every command in the Dockerfile
+then adds a layer of change to the container image.
+
+The majority of the Dockerfile for ``dev-c7`` is using yum install to get
+packages installed into the OS. Yum is executed via the ``RUN`` command.
+Note that the ``RUN`` command takes a single shell command line input.
+
+.. Note::
+    It is
+    common in Dockerfiles to use ``&& \`` to string multiple commands together
+    in a single ``RUN``. The reason to do this is to minimize the number
+    of layers
+    in the container image. In particular, if you want to clean up temporary
+    files, it must be done in the same layer they were created or it will not
+    reduce the size of the resulting image (because there is a layer with the
+    temp files and then another layer that removes them).
+
+The ``RUN`` command may execute any command that is available inside the
+container. For example the above uses a single ``RUN`` to get the source for
+a new version of git and compile it.
+
+Another command in this Dockerfile is ``ENV`` which simply sets an environment
+variable for the processes the container launches.
+
+The ``COPY`` command allows you to supply files from the context
+(``dev-c7/docker`` folder in this case).
+Note that the path / is the root of the context. You can only
+copy files from inside the context, thus the context folder holds the entire
+definition of the image generated.

2024.8.1gui/_sources/how-to/deriving.rst.txt

@@ -0,0 +1,33 @@
+.. _deriving:
+
+Derive your own container image
+===============================
+
+Each developer is free to derive their own container image if they have
+specific requirements e.g.
+
+- Additional system libraries
+- Additional command line or GUI tools
+- Any other OS configuration that they prefer
+
+.. note::
+    If the changes you need are likely to be useful to all developers then
+    you should consider contributing to the base image for dev-c7.
+    See `../reference/contributing`
+
+To make your own derived container.
+
+- Create a folder (this is your container context folder)
+- Make a Dockerfile in that folder
+- Drop in any files that you want to copy into the container
+- cd into the folder
+- ``podman build --tag my-dev-c7 .``
+- c7 -i my-dev-c7
+
+Below is an example Dockerfile derived from dev-c7 that adds a package with
+yum, sets an environment variable and copies a script into /usr/bin. Note
+that the build is running as root inside the container so it is allowed
+to write to a system folder.
+
+.. literalinclude:: Dockerfile
+   :language: docker