diff --git a/docs/conf.py b/docs/conf.py index f276796c..11af8909 100644 --- a/docs/conf.py +++ b/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, diff --git a/docs/user/images/bl01t-actions.png b/docs/user/images/bl01t-actions.png new file mode 100644 index 00000000..3ed00773 Binary files /dev/null and b/docs/user/images/bl01t-actions.png differ diff --git a/docs/user/images/edm_sim.png b/docs/user/images/edm_sim.png deleted file mode 100644 index b24029ab..00000000 Binary files a/docs/user/images/edm_sim.png and /dev/null differ diff --git a/docs/user/index.rst b/docs/user/index.rst index f6468f92..9a621135 100644 --- a/docs/user/index.rst +++ b/docs/user/index.rst @@ -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 diff --git a/docs/user/tutorials/create_beamline.rst b/docs/user/tutorials/create_beamline.rst index 20449758..fea649b2 100644 --- a/docs/user/tutorials/create_beamline.rst +++ b/docs/user/tutorials/create_beamline.rst @@ -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. diff --git a/docs/user/tutorials/create_ioc.rst b/docs/user/tutorials/create_ioc.rst new file mode 100644 index 00000000..b4f09892 --- /dev/null +++ b/docs/user/tutorials/create_ioc.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 \ No newline at end of file diff --git a/docs/user/tutorials/deploy_example.rst b/docs/user/tutorials/deploy_example.rst index 696a5ec6..bc402eee 100644 --- a/docs/user/tutorials/deploy_example.rst +++ b/docs/user/tutorials/deploy_example.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 ----------------------------------------------------- + git@github.com:**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,117 +95,99 @@ 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: @@ -203,16 +195,15 @@ To run a bash shell inside the IOC container: 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. diff --git a/docs/user/tutorials/release_beamline.rst b/docs/user/tutorials/release_beamline.rst deleted file mode 100644 index d40f2cd5..00000000 --- a/docs/user/tutorials/release_beamline.rst +++ /dev/null @@ -1,59 +0,0 @@ - - -Make a Release of Example Beamline bl01t ----------------------------------------- - -.. Warning :: - - This information is out of date. It will be updated soon. - -To make a release of the project we defined in `deploy_example`, -we will -tag your repo with a calendar based version number see (https://calver.org/). - -We use YY.MM.MINOR for versioning things like beamlines and Generic IOCs. You -can choose your own scheme, but because these projects do not have APIs as -such it is more instructive to use a date based scheme. - -The example version below was the first revision in the month of April 2023. - -.. code-block:: bash - - cd bl01t - git tag 23.4.1 - # push the tag - git push origin 23.4.1 - -This will cause GitHub to create a release of the project and trigger -continuous integration. The continuous integration will look at all of -the IOCs in the beamline and generate helm charts for each one. If the helm -chart has changed since the last release then a new version of the helm chart -is delivered to your GitHub account's OCI registry. - -To watch the progress go to the Actions Panel for your project at -https://github.com//bl01t/actions - -.. figure:: ../images/github_actions.png - -Once the CI completes you should have a helm chart delivered in your project -OCI registry. You can see this listed in project 'packages'. -Look for a link to the package on the right hand side of your -project page. - -Go to the code pane and click on the example package circled below to see it. - -.. figure:: ../images/github_package.png - -The OCI registry name of the helm chart will be -ghcr.io//bl01t/bl01t-ea-ioc-01:23.4.1. - -You have now completed this tutorial. Here you have created a new beamline -repository and made a release of it. The release includes the example IOCs -instance called ``bl01t-ea-ioc-01``. This IOC has had a helm chart generated -for it and published ready for deployment to your cluster. - -In the next tutorial we will look into what we have created in more detail -and we will deploy and test the new example IOC. - -For details of what goes into the helm chart of an IOC instance see -`../reference/ioc_helm_chart`. diff --git a/docs/user/tutorials/setup_workstation.rst b/docs/user/tutorials/setup_workstation.rst index e97c12f2..75c17b78 100644 --- a/docs/user/tutorials/setup_workstation.rst +++ b/docs/user/tutorials/setup_workstation.rst @@ -169,11 +169,11 @@ The following tutorials will take you through creating, deploying and debugging IOC instances, generic IOCs and support modules. For simplicity we don't encourage using Kubernetes at this stage. Instead we -will deploy containers to the local workstations docker or podman instance. +will deploy containers to the local workstation's docker or podman instance. However, everything in these tutorials would also work with Kubernetes. If you are particularly interested in Kubernetes then you can jump to -`setup_kubernetes` and follow the instructions there. Then come back to this +`setup_kubernetes` and follow the instructions there. Then '{{(index (index .NetworkSettings.Ports "8787/tcp") 0).HostPort}}'come back to this point and continue with the tutorials. If you are planning not to use Kubernetes at all then now might be