deploy: 949aafd

main/.buildinfo

@@ -1,4 +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: 2835a1986dbe3e42d92c6c5d24989128
+config: cc63392b6049ba5e288592f41f70f349
 tags: 645f666f9bcd5a90fca523b33c5a78b7

main/_sources/user/explanations/ioc-source.rst.txt

@@ -0,0 +1,8 @@
+.. _ioc-source:
+
+Dev Container vs Runtime Container
+==================================
+
+TODO: explain how and why ioc-xxxx is mounted in dev container and what happens
+to the ioc folder.
+

main/_sources/user/index.rst.txt

@@ -22,11 +22,13 @@ side-bar.
             tutorials/ioc_changes1
             tutorials/ioc_changes2
             tutorials/ioc_changes3
+            tutorials/ioc_changes4
             tutorials/generic_ioc
             tutorials/debug_generic_ioc
             tutorials/test_generic_ioc
             tutorials/support_module
             tutorials/setup_k8s
+            tutorials/setup_k8s_new_beamline
             tutorials/rtems_setup
             tutorials/rtems_ioc
             tutorials/ibek
@@ -61,6 +63,7 @@ side-bar.
             explanations/kubernetes_cluster
             explanations/docs-structure
             explanations/repositories
+            explanations/ioc-source
 
         +++
 

main/_sources/user/tutorials/dev_container.rst.txt

@@ -249,10 +249,10 @@ Adding the Beamline to the Workspace
 ------------------------------------
 
 To meaningfully test the Generic IOC we will need an instance to test it
-against. We will use the ``bl01t`` beamline that you already made. The container 
+against. We will use the ``bl01t`` beamline that you already made. The container
 has been configured to mount some useful local files from the user's home directory,
-including the parent folder of the workspace as ``/repos`` so we can work on 
-multiple peer projects. 
+including the parent folder of the workspace as ``/repos`` so we can work on
+multiple peer projects.
 
 In VSCode click the ``File`` menu and select ``Add Folder to Workspace``.
 Navigate to ``/repos`` and you will see all the peers of your ``ioc-adsimdetector``
@@ -320,6 +320,10 @@ host. i.e. the root folder under which your projects are all cloned):
      - WS
      - all peers to Generic IOC source repo
 
+.. _choose-ioc-instance:
+
+Choose the IOC Instance to Test
+-------------------------------
 
 Now that we have the beamline repo visible in our container we can
 easily supply some instance configuration to the Generic IOC.

main/_sources/user/tutorials/ioc_changes1.rst.txt

@@ -110,6 +110,11 @@ However all of the steps except for the ``ec`` command could have been done
 We choose not to have ``ec`` installed inside of the devcontainer because
 that would involve containers in containers which adds too much complexity.
 
+If you like working entirely from the vscode window you can open a terminal
+in vscode *outside* of the devcontainer. To do so, press ``Ctrl-Shift-P`` and
+choose the commnd ``Terminal: Create New Integrated Terminal (Local)``.
+This will open a terminal to the host. You can then run ``ec`` from there.
+
 Raw Startup Assets
 ------------------
 

main/_sources/user/tutorials/ioc_changes2.rst.txt

@@ -1,16 +1,127 @@
-Changing the Generic IOC
-========================
+Changing a Generic IOC Part 1
+=============================
+
+.. warning ::
+
+    This tutorial is a work in progress. It is not yet complete.
 
-This tutorial will make a simple change to the Generic IOC ``ioc-adsimdetector``.
-We will also update the IOC instance ``bl01t-ea-ioc-02`` use the new feature of
-the Generic IOC.
 This is a type 2 change from `ioc_change_types`.
 
-We are going to add an additional support module to the Generic IOC and then
-use it to add a new record to the IOC instance to use this new support.
+The changes that you can make in an IOC instance are limited to what
+the author of the associated Generic IOC has made configurable.
+Therefore you will
+occasionally need to update the Generic IOC that your instance is using.
+Some of the reasons for doing this are:
+
+- Update one or more support modules to new versions
+- Add additional support such as autosave or iocStats
+- For ibek generated IOC instances, you may need to add or change functionality
+  in the support YAML file.
+
+This tutorial will make some changes to the generic IOC ``ioc-adsample``.
+This Generic IOC is a simplified copy of ``ioc-adsimdetector`` tailored for
+use in these tutorials.
+
+For this exercise we will initially work locally inside the ``ioc-adsample``
+developer container.
+
+At the end we will push the changes and see the CI build a new version of the
+generic IOC container image. This allows for the demonstration of:
+
+- Deploying an IOC instance using a new image published by the CI
+- Showing how to do a Pull Request back to the original repository.
+
+For this exercise we will be using an example IOC Instance to test our changes.
+Instead of working with a beamline repository, we will use the example ioc instance
+that comes with ``ioc-adsample``. It is a good idea for Generic IOC authors to
+include an example IOC Instance in their repository for testing changes in
+isolation.
+
+
+Preparation
+-----------
+
+Because we want to push our changes we will first make a fork of the
+``ioc-adsample`` repository. We will then clone our fork locally and
+make the changes there.
+
+To make a fork go to
+`ioc-adsample <https://github.com/epics-containers/ioc-adsample>`_
+and click the ``Fork`` button in the top right corner. This will create a fork
+of the repository under your own GitHub account.
+
+Now, clone the fork, build the container image locally and open the
+developer container:
+
+.. code-block:: console
+
+    git clone [email protected]:<YOUR GITHUB ACCOUNT NAME>/ioc-adsample.git
+    cd ioc-adsample
+    ./build
+    code .
+    # click the green button in the bottom left corner of vscode and select
+    # "Reopen in Container"
+
+The ``build`` script does two things.
+
+- it fetches the git submodule called ``ibek-support``. This submodule is shared
+  between all the EPICS IOC container images and contains the support YAML files
+  that tell ``ibek`` how to build support modules inside the container
+  environment.
+- it builds the Generic IOC container image locally.
+
+.. note::
+
+    The ``build`` script is a convenience script that is provided in the
+    Generic IOC Template project. It is exactly equivalent to cloning
+    with ``--recursive`` flag and then running ``ec dev build``.
+
+Verify the Example IOC Instance is working
+------------------------------------------
+
+When a new Generic IOC developer container is opened, there are two things
+that need to be done before you can run an IOC instance inside of it.
+
+- Build the IOC source code
+- Select an IOC instance definition to run
+
+The folder ``ioc`` inside of the ``ioc-adsample`` is where the IOC source code
+is created and built. When you open the developer container, this folder does
+not yet exist. The following command will create it and build the IOC:
+
+.. code-block:: console
+
+    ec ioc build
+
+The IOC instance definition is a YAML file that tells ``ibek`` what the runtime
+assets (ie. EPICS DB and startup script) should look like. Previous tutorials
+selected the IOC instance definition from a beamline repository. In this case
+we will use the example IOC instance that comes with ``ioc-adsample``. The
+following command will select the example IOC instance:
+
+.. code-block:: console
+
+    ibek dev instance /epics/ioc-adsample/ioc_examples/bl01t-ea-ioc-02
+
+In an earlier tutorial when learning about the dev container, we manually
+performed this step, see `choose-ioc-instance`. The above command does
+exactly the same thing: removes the existing config folder in ``/epics/ioc``
+and symlinks in the chosen IOC instance definition's ``config`` folder.
+
+Now  run the IOC:
+
+.. code-block:: console
+
+    ibek dev run
+
+You should see a iocShell prompt and no error messages above.
+
+.. note::
 
-For this exercise all changes will be local so you will not need to make a
-fork of ``ioc-adsimdetector``. The next tutorial will show how to a new
-Generic IOC and we will look at the Generic IOC CI at that time.
+    The ``ec ioc build`` command required to re-create the IOC source code.
+    This is even though the container you are using already had the IOC
+    source code built by its Dockerfile (``ioc-adsample/Dockerfile``
+    contains the same command).
 
-TODO: WIP.
+    For a detailed explanation of why this is the case see
+    `ioc-source`

main/_sources/user/tutorials/ioc_changes3.rst.txt

@@ -1,12 +1,9 @@
-Making a new Support Module
-===========================
+Changing a Generic IOC Part 2
+=============================
 
-This tutorial will create a new Generic IOC for a new support module. We will
-then create a new IOC Instance that uses this new support module.
-This is a type 3 change from `ioc_change_types`.
+This is a type 2 change from `ioc_change_types`.
+
+This tutorial will change the support yaml used by a generic IOC.
 
-This exercise will create a new Stream Device support module that implements
-a very simple ASCII protocol. So simple that we will be able to test it
-by typing into a telnet session.
 
 TODO: WIP.

main/_sources/user/tutorials/ioc_changes4.rst.txt

@@ -0,0 +1,12 @@
+Making a new Support Module
+===========================
+
+This tutorial will create a new Generic IOC for a new support module. We will
+then create a new IOC Instance that uses this new support module.
+This is a type 3 change from `ioc_change_types`.
+
+This exercise will create a new Stream Device support module that implements
+a very simple ASCII protocol. So simple that we will be able to test it
+by typing into a telnet session.
+
+TODO: WIP.

main/_sources/user/tutorials/setup_k8s.rst.txt

@@ -4,30 +4,17 @@
 Setup a Kubernetes Server
 =========================
 
-.. Warning::
-
-    This information is out of date. It will be updated soon.
-
 .. Note::
 
-    **DLS Users**: DLS already has the test cluster Pollux and further
-    beamline and machine clusters are coming soon.
-
-    To use the Pollux cluster, run ``module load pollux`` outside of the
-    devcontainer and then run the script ``.devcontainer/dls-copy-k8s-crt.sh``
+    **DLS Users**: DLS already has the test cluster ``Pollux`` which includes
+    the test beamline p45 and the training beamlines p46 through to p49.
 
-    The Pollux Cluster already has a beamline namespace ``bl01t``
-    for you to use as a training area. *You will need
-    to ask SciComp to add you as a user of this namespace.*
-    Please be aware that this is a shared resource so others might be using
-    it at the same time.
+    We have also started to roll out production clusters for some of our
+    beamlines. To date we have clusters for p38, i20, i22 and c01.
 
-    The Pollux Cluster already has the Kubernetes dashboard installed.
-    To access it go to http://pollux.diamond.ac.uk and click
-    ``Pollux K8S Dashboard``.
-
-    Then select ``bl01t`` from the namespace drop down menu in the top left,
-    to see the training namespace.
+    For this reason DLS users should skip this tutorial unless you have a
+    spare linux machine with root access and an interest in how Clusters
+    are created.
 
 Introduction
 ------------
@@ -39,7 +26,7 @@ Bring Your Own Cluster
 ----------------------
 
 If you already have a Kubernetes cluster then you can skip this section.
-and go straight to `./create_beamline`.
+and go straight to the next tutorial.
 
 IMPORTANT: you will require appropriate permissions on the cluster to work
 with epics-containers. In particular you will need to be able to create
@@ -137,17 +124,18 @@ uses a namespace for each beamline or accelerator domain.
 A context is a combination of a cluster, namespace, and user. It tells kubectl
 which cluster and namespace to use when communicating with the Kubernetes API.
 
-So here we will create a namespace for our first test beamline BEAMLINE TEST 01
-or bl01t for short. We will also create a context for this namespace and set
-it as the default context.
+Here we will create a namespace for our first test beamline bl46p. We are
+using this name because it is the name of the first test Kubernetes beamline
+at DLS. This just means I can use some of the following tutorials for both
+DLS and non-DLS users.
 
 From the workstation INSIDE the devcontainer execute the following:
 
 .. code-block:: bash
 
-    kubectl create namespace bl01t
-    kubectl config set-context bl01t --namespace=bl01t --user=default --cluster=default
-    kubectl config use-context bl01t
+    kubectl create namespace bl46p
+    kubectl config set-context bl46p --namespace=bl46p --user=default --cluster=default
+    kubectl config use-context bl46p
 
 Create a service account to run the IOCs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -163,7 +151,7 @@ Create the account:
     apiVersion: v1
     kind: ServiceAccount
     metadata:
-        name: bl01t-priv
+        name: bl46p-priv
     EOF
 
 Generate a login token for the account:
@@ -174,9 +162,9 @@ Generate a login token for the account:
     apiVersion: v1
     kind: Secret
     metadata:
-        name: bl01t-priv-secret
+        name: bl46p-priv-secret
         annotations:
-            kubernetes.io/service-account.name: bl01t-priv
+            kubernetes.io/service-account.name: bl46p-priv
     type: kubernetes.io/service-account-token
     EOF
 
@@ -195,3 +183,4 @@ simply use this command:
     k3s-uninstall.sh
 
 If you are interested in looking at the k3s files see **/var/lib/rancher/k3s/**.
+