add deploying instances tutorial

Author: gilesknap

docs/conf.py

@@ -152,7 +152,7 @@
 # to complete as the docs build warns and fails.
 html_theme_options = dict(
     logo=dict(
-        text=project,
+        text="EPICS Containers",
     ),
     navigation_with_keys=True,
     use_edit_page_button=True,

docs/user/images/bl01t-actions.png

@@ -17,8 +17,8 @@ side-bar.
             tutorials/setup_workstation
             tutorials/create_beamline
             tutorials/deploy_example
+            tutorials/create_ioc
             tutorials/ioc_changes
-            tutorials/release_beamline
             tutorials/generic_ioc
             tutorials/debug_generic_ioc
             tutorials/test_generic_ioc

docs/user/images/edm_sim.png

@@ -174,8 +174,8 @@ Wrapping Up
 -----------
 
 You should now have a working beamline repository. It contains a single
-IOC Instance and that is only a non-functional example. In the following
-tutorials we will investigate the example and then create a real IOC Instance.
+IOC Instance which is a non-functional example. In the following
+tutorial we will investigate the example and then create a real IOC Instance.
 
 You can now push the repository up to GitHub and give it a version tag like this:
 
@@ -185,7 +185,7 @@ You can now push the repository up to GitHub and give it a version tag like this
     git commit -m "changed blxxi to bl01t"
     git push
     git tag 2023.11.1
-    git push --tags
+    git push origin 2023.11.1
 
 
 We use ``CalVer`` version numbers for beamline repositories and Generic IOCs.

docs/user/index.rst

@@ -0,0 +1,15 @@
+Create a Working Example IOC Instance
+=====================================
+
+Introduction
+------------
+
+The last section covered deploying and managing the example Instance that
+came with the template beamline repository. Here we will create a new
+IOC Instance that implements a simulated detector.
+
+TODO - complete this.
+
+.. figure:: ../images/c2dv.png
+
+    the c2dv viewer showing an image from the example IOC

docs/user/tutorials/create_beamline.rst

@@ -1,29 +1,49 @@
-Deploy The Example IOC
-======================
-
-.. Warning::
-
-    This tutorial is out of date and will be updated soon.
+Deploying and Managing IOC Instances
+====================================
 
 Introduction
 ------------
 
-This tutorial will show you how to deploy some IOC Instances to the test
-beamline bl01t. You will need to have your own bl01t beamline repository
+This tutorial will show you how to deploy and manage the example IOC Instance
+that came with the template beamline repository.
+You will need to have your own ``bl01t`` beamline repository
 from the previous tutorial.
 
 For these early tutorials we are not using Kubernetes and instead are deploying
-IOCs to the local docker or podman instance. So for the this tutorial we
+IOCs to the local docker or podman instance. So for these tutorials we
 shall pretend that your workstation is one of the IOC servers on the fictitious
-beamline BL01T.
+beamline ``BL01T``.
+
+Continuous Integration
+----------------------
+
+Before we change anything, we shall make sure that the beamline repository CI
+is working as expected. To do this go to the following URL (make sure you insert
+your GitHub account name where indicated):
+
+.. code::
 
-Take a Look at Your Project's Continuous Integration
-----------------------------------------------------
+    [email protected]:**YOUR GITHUB ACCOUNT**/bl01t/actions
 
-Before we change anything we shall make sure that the beamline repository CI
-is working as expected. To do this go to the following URL:
+You should see something like the following:
 
--
+.. figure:: ../images/bl01t-actions.png
+
+    the GitHub Actions page for the example beamline repository
+
+This is a list of all the Continuous Integration (CI) jobs that have been
+executed (or are executing) for your beamline repository. There should be
+two jobs listed, one for when you pushed the main branch and one for when you
+tagged with the ``CalVer`` version number.
+
+If you click on the most recent job you can drill in and see the steps that
+were executed. The most interesting step is ``Run bash ./ci_verify.sh``. This
+is executing the script in the root of your beamline repository that verifies
+each IOC instance in the ``iocs`` folder. In future we can make this script
+more sophisticated when we have simulated hardware to test against.
+
+For the moment just check that your CI passed and if not review that you
+have followed the instructions in the previous tutorial correctly.
 
 Set up Environment for BL01T Beamline
 -------------------------------------
@@ -45,38 +65,28 @@ where indicated):
 
     cd /tmp
     curl -o ~/.local/bin/bl01t https://raw.githubusercontent.com/**YOUR GITHUB ACCOUNT**/bl01t/main/environment.sh?token=$(date +%s)
-    . ~/.bash_profile
-    . bl01t
+    source ~/.bash_profile
+    source bl01t
 
 Once you have done this and logged out and back in again to pick up your new
-profile you should be able enable the bl01t environment as follows:
+profile you should be able enable the ``bl01t`` environment as follows:
 
 .. code-block:: bash
 
-    . bl01t
+    # first make sure you have loaded your virtual environment
+    source $HOME/ec-venv/bin/activate
+    source bl01t
 
 
-Deploy the IOC Instance to Kubernetes
--------------------------------------
+Deploy the Example IOC Instance
+-------------------------------
 
-For this tutorial we are going to work with the example IOC bl01t-ea-ioc-01
-that came with our beamline repository from the previous tutorial.
-Here we will deploy the IOC into our cluster and then learn how to interact
-with it.
+For this section we will be making use of the epics-containers-cli tool.
+This command line entry point for the tool is ``ec``. For more
+details see: `CLI` or try ``ec --help``.
 
-If you are interested in the detail of what is in the bl01t-ea-ioc-01 folder
-that describes this IOC instance then see: `../reference/ioc_helm_chart`.
-
-Also, if you are interested in how the helm chart manifests itself in your
-cluster when deployed then see: `../reference/k8s_resources`.
-
-For this section we will be making use of the epics-containers-cli tool. This makes
-it easier to interact with kubernetes and helm from the command line and is
-described in more detail here: `CLI`.
-
-You will need a working Kubernetes cluster for most of the rest of the
-tutorials. You can verify that it is working by asking for a list of IOCs
-running in your default domain as follows:
+The simplest command to check that the tool is working is ``ps`` which lists
+the IOC Instances that are currently running:
 
 .. code-block:: bash
 
@@ -85,134 +95,115 @@ running in your default domain as follows:
 You should see some headings and an empty list as you have not yet started an
 IOC Instance.
 
-.. note::
-
-    The command ``ec`` is the epics-containers command line utilities entry
-    point. For more information see `CLI` or try ``ec --help``.
-
-
-The following command will deploy the example IOC instance to your cluster
-(if you changed the ioc name in the previous tutorial then
-remember to change bl01t-ea-ioc-01 to your unique name here):
+The following command will deploy the example IOC instance to your local
+machine (unless you have skipped ahead and set up your Kubernetes config
+in which case the same command  will deploy to your Kubernetes cluster).
 
 .. code-block:: bash
 
-    ec ioc deploy bl01t-ea-ioc-01 23.4.1
-
-Note that this is looking for the IOC's helm chart in your OCI helm registry.
-You delivered the IOC helm chart to the registry when you made a release of
-the beamline repo in the previous tutorial. You must supply a version number
-that exists. If you do not recall the version number you used in the last tutorial,
-you can use the following command to list the versions available in your
-registry:
-
-.. code-block:: bash
+    cd bl01t # (if you are not already in your beamline repo)
+    ec ioc deploy-local iocs/bl01t-ea-ioc-01
 
-    ec ioc versions bl01t-ea-ioc-01
+You will be prompted to say that this is a *TEMPORARY* deployment. This is
+because we are deploying directly from the local filesystem. You should only
+use this for testing purposes because there is no guarantee that you could
+ever roll back to this version of the IOC (as it is lost as soon as filesystem
+changes are made). Local filesystem deployments are given a beta version
+number to indicate that they are not permanent.
 
-As the deployment is progressing you could use the following command to
-monitor the progress (hit ctrl-C to stop following the logs):
+You can now see the beta IOC instance running with:
 
 .. code-block:: bash
 
-    ec ioc logs bl01t-ea-ioc-01 -f
-
-Note there may be a little delay while the cluster pulls the Generic IOC
-image from the GitHub container registry. The error
-"recGblRecordError: devStringinEnvVar (init_record) Illegal INP parm field Illegal field value PV: BL01T-EA-IOC-01:TIMEZONE"
-is benign, TODO: take a look at the cause of this error.
+    $ ec ps
+    IOC NAME            VERSION             STATUS              IMAGE
+    bl01t-ea-ioc-01     2023.10.26-b11.53   Up 6 minutes        ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.10.5
 
-Once the IOC is running you can find out the IP address of the pod it is
-running in with:
+At the end of the last tutorial we tagged the beamline repository with a
+``CalVer`` version number and pushed it up to GitHub. This means that we
+can now release the IOC instance with that same version number. First let's
+check that the IOC instance version is available as expected:
 
 .. code-block:: bash
 
-    ec ps -w
-
-This will show you the status of the IOC instance and the IP address of the
-pod it is running in. In a real beamline setup the IOCs would run in the same
-subnet as your workstation so you would not care about the IP address. But
-for the example you may need to do the following to let our EPICS clients
-know where to look for PVs:
-
-.. code-block:: bash
+    $ ec ioc instances bl01t-ea-ioc-01
+    Available instance versions for bl01t-ea-ioc-01:
+        2023.11.1
 
-    export EPICS_CA_ADDR_LIST=ip_address_of_pod
-    export EPICS_PVA_ADDR_LIST=ip_address_of_pod
 
-epics-containers does not yet have any provision for EPICS operator interfaces.
-For this example we have hand crafted some EDM screens to control and monitor
-the test IOC. These EDM screens are supplied in the template so you will
-have them in the ``opi`` folder in your beamline repository.
-
-You can now launch the client applications as follows:
+Now that we know the latest version number we can deploy a release version.
+This command will extract the IOC instance using the tag from GitHub and deploy
+it to your local machine:
 
 .. code-block:: bash
 
-    ./blxxi-ea-ioc-01-gui.sh
-    c2dv --pv $USER-EA-TST-01:IMAGE
-
-Now make sure the AreaDetector is Acquiring by clicking Start if needed on
-the CAM screen. Next click on Auto to scale the
-black and white thresholds on the C2D viewer. You should see something like the
-following images.
-
-.. figure:: ../images/edm_sim.png
-
-    edm screen for the example IOC
+    $ ec ioc deploy bl01t-ea-ioc-01 2023.11.1
+    bdbd155d437361fe88bce0faa0ddd3cd225a9026287ac5e73545aeb4ab3a67e9
 
-.. figure:: ../images/c2dv.png
+    $ ec ps
+    IOC NAME            VERSION             STATUS              IMAGE
+    bl01t-ea-ioc-01     2023.11.1           Up 4 seconds        ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.10.5
 
-    the c2dv viewer showing an image from the example IOC
 
-
-Managing IOCs
---------------
-
-IOCs running in Kubernetes can be managed using the ``ec`` command.
+Managing the Example IOC Instance
+---------------------------------
 
 Starting and Stopping IOCs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To stop / start  the example IOC:
+To stop / start  the example IOC try the following commands. Note that
+``ec ps -a`` shows you all IOCs including stopped ones.
 
 .. code-block:: bash
 
+    ec ps -a
     ec ioc stop bl01t-ea-ioc-01
+    ec ps -a
     ec ioc start bl01t-ea-ioc-01
+    ec ps
+
+.. Note::
+
+    Generic IOCs.
+
+    You may have noticed that the IOC instance has is showing that it has
+    an image ``ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.10.5``.
+
+    This is a Generic IOC image and all IOC Instances must be based upon one
+    of these images. This IOC instance has no startup script and is therefore
+    not functional, it could have been based on any Generic IOC.
 
 Monitoring and interacting with an IOC shell
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-To attach to the ioc shell:
+To attach to the ioc shell you can use the following command. HOWEVER, this
+will attach you to nothing in the case of this example IOC as it has no
+shell. In the next tutorial we will use this command to interact with
+iocShell.
 
 .. code-block:: bash
 
     ec ioc attach bl01t-ea-ioc-01
 
-Use the command sequence ctrl-P then ctrl-Q to detach or ctrl-D to restart the
-IOC and detach.
-
-TODO: I'm having issues with the shell eating the ^P^Q sequences so
-at present you can only detach from the IOC by killing the terminal or
-using ^D.
+Use the command sequence ctrl-P then ctrl-Q to detach from the IOC
+You can also usually restart and detach from the IOC using ctrl-D or
+ctrl-C.
 
 To run a bash shell inside the IOC container:
 
 .. code-block:: bash
 
     ec ioc exec bl01t-ea-ioc-01
 
-Once you have a shell inside the container you can inspect the following
+Once you have a shell inside the container you could inspect the following
 folders:
 
 =============== ==============================================================
-ioc code        repos/epics/ioc
-support modules repos/epics/support
-epics binaries  repos/epics/epics-base
+ioc code        /epics/ioc
+support modules /epics/support
+EPICS binaries  /epics/epics-base
 =============== ==============================================================
 
-
 Logging
 ~~~~~~~
 
@@ -228,6 +219,9 @@ Or follow the IOC log until you hit ctrl-C:
 
     ec ioc logs bl01t-ea-ioc-01 -f
 
+You will notice that this IOC simply prints out a message regarding what
+you can place in the /epics/ioc/config folder. In the next tutorial
+we will look at how to configure a real EPICS IOC.