completed tutorial 08

gilesknap · gilesknap · commit 3ca577a316f3 · 2023-03-31T12:36:26.000Z
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -16,7 +16,9 @@
         "Beamlines",
         "blxxi",
         "blxxt",
+        "GRAPHICSMAGICK",
         "klogout",
+        "Magick",
         "MVME"
     ]
 }
diff --git a/docs/user/explanations/kubernetes_cluster.rst b/docs/user/explanations/kubernetes_cluster.rst
@@ -68,11 +68,11 @@ Overview
 
 Argus is the production DLS cluster. It comprises 22 bare metal worker nodes, with a 3 node control plane that runs in VMs. The control plane nodes run the K8s master processes such as the API server, controller manager etc. Each control plane node runs an etcd backend.
 
-.. image:: ../images/clusterHA.png
+.. figure:: ../images/clusterHA.png
 
 To load balance across the K8s API running on the control plane nodes, there is a haproxy load balancer. The DNS endpoint argus.api.diamond.ac.uk (which all nodes use as the main API endpoint) points to a single haproxy IP. The IP is HA by virtue of a pair of VMs that both run haproxy, bind on all IPs, and use VRRP/keepalived to make sure the IP is always up. Haproxy has the 3 control plane nodes as a target backend.
 
-.. image:: ../images/kubeadm-ha-topology-stacked-etcd.png
+.. figure:: ../images/kubeadm-ha-topology-stacked-etcd.png
 
 The cluster uses Kubeadm to deploy the K8s control plane in containers. It is provided by K8s upstream, and is architecturally similar to Rancher Kubernetes Engine (RKE). Kubeadm supports upgrades/downgrades and easy provisioning of nodes. The cluster is connected using Weave as the CNI. Weave is the only CNI tested that passes Broadcast/Unicast/Multicast (BUM) traffic through the iptables that control network access for pods. Metallb is used as a component to support K8s loadBalancer Service objects. Ingress nginx from nginxinc is used as an ingress controller. Logs are collected from the stdout of all pods using a fluentd daemonset which ships logs to a centralized graylog server. Cluster authentication is via KeyCloak.
 
@@ -81,7 +81,7 @@ The cluster sits in one rack, with a top of rack (TOR) switch/router connecting
 
 **One of the Argus racks**
 
-.. image:: ../images/argus3.jpg
+.. figure:: ../images/argus3.jpg
 
 The cluster is built and managed using Ansible. Heavy use of the k8s module enables direct installation of K8s components by talking directly to the K8s API using the k8s module. Ansible also configures the haproxy API load balancer. Prometheus_operator provides the monitoring stack.
 
diff --git a/docs/user/explanations/net_protocols.rst b/docs/user/explanations/net_protocols.rst
@@ -48,17 +48,13 @@ Initially we looked into workarounds to these issues. For example the
 diagram below shows a 'ca-forwarder' that sits on the EPICS client subnet
 and forwards requests to IOCs in the cluster.
 
-.. image:: ../images/caforwarder.png
-    :width: 1500px
-    :align: center
+.. figure:: ../images/caforwarder.png
 
 However this 2nd diagram shows why this approach fails when the client is in
 the cluster itself.
 
 
-.. image:: ../images/cabackwarder.png
-    :width: 1500px
-    :align: center
+.. figure:: ../images/cabackwarder.png
 
 The conclusion of this study was that workarounds were fiddly and needed to be
 implemented on a per protocol basis, plus there is no guarantee that there
diff --git a/docs/user/explanations/repos.rst b/docs/user/explanations/repos.rst
@@ -0,0 +1,9 @@
+What is the /repos Folder?
+==========================
+
+TODO: explain why we have a /repos folder and how it is
+mounted and synced with a the host to enable inside/outside
+access when debugging and testing container builds.
+
+
+.. figure:: ../images/repos_folder.png
diff --git a/docs/user/how-to/useful_k8s.rst b/docs/user/how-to/useful_k8s.rst
@@ -133,8 +133,7 @@ First you will need install `docker for WSL`_.
 You will also require an `X11 Server for Windows`_. When you run the server
 choose the option **Disable Access Control** as follows:
 
-.. image:: ../images/vcxsrv.png
-    :align: center
+.. figure:: ../images/vcxsrv.png
 
 The networking for docker on WSL will not broadcast between containers so
 you need to use EPICS_CA_ADDR_LIST to get edm to see the example IOC
diff --git a/docs/user/images/repos_folder.png b/docs/user/images/repos_folder.png
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -57,6 +57,7 @@ side-bar.
             explanations/docs-structure
             explanations/repositories
             explanations/cli-tools
+            explanations/repos
 
         +++
 
diff --git a/docs/user/tutorials/04_create_beamline.rst b/docs/user/tutorials/04_create_beamline.rst
@@ -106,8 +106,7 @@ repo in the future.
         git commit -m "rename blxxi to bl01t"
         git push origin main
 
-.. image:: ../images/create_repo.png
-    :align: center
+.. figure:: ../images/create_repo.png
 
 
 Make a Release of Example Beamline bl01t
@@ -138,8 +137,7 @@ 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/<YOUR USER NAME>/bl01t/actions
 
-.. image:: ../images/github_actions.png
-    :align: center
+.. 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'.
@@ -148,8 +146,7 @@ project page.
 
 Go to the code pane and click on the example package circled below to see it.
 
-.. image:: ../images/github_package.png
-    :align: center
+.. figure:: ../images/github_package.png
 
 The OCI registry name of the helm chart will be
 ghcr.io/<YOUR USER NAME>/bl01t/bl01t-ea-ioc-01:23.4.1.
diff --git a/docs/user/tutorials/05_deploy_example.rst b/docs/user/tutorials/05_deploy_example.rst
@@ -99,11 +99,13 @@ following images.
     `../explanations/cli-tools`
 
 
-.. image:: ../images/edm_sim.png
-    :align: center
+.. figure:: ../images/edm_sim.png
 
-.. image:: ../images/c2dv.png
-    :align: center
+    edm screen for the example IOC
+
+.. figure:: ../images/c2dv.png
+
+    the c2dv viewer showing an image from the example IOC
 
 
 Managing IOCs
diff --git a/docs/user/tutorials/07_generic_ioc.rst b/docs/user/tutorials/07_generic_ioc.rst
@@ -1,5 +1,5 @@
-Working with Generic IOCs
-=========================
+Create a Generic IOC
+====================
 
 In this tutorial we will learn how to create a generic IOC container image and
 test our changes locally before deploying it.
@@ -221,6 +221,12 @@ follows:
 ADCore and ADSupport already have ibek-defs files as they were previously created
 when making ``ioc-adsimdetector``.
 
+.. note::
+
+    The folder /repos is where all externally fetched source code is stored
+    inside our containers. For a detailed explanation see
+    `../explanations/repos`
+
 .. _CONFIG_SITE.local: https://areadetector.github.io/areaDetector/install_guide.html#edit-config-site-local-and-optionally-config-site-local-epics-host-arch
 
 Update the IOC Makefile
@@ -296,38 +302,3 @@ directory:
 
         ../URLDriver.cpp:22:10: fatal error: Magick++.h: No such file or directory
 
-
-
-
-.. git submodule init
-.. git submodule update
-.. cd ibek ibek-defs TODO - do they need a fork of this??
-.. checkout main
-.. push --set-upstream origin main
-.. mkdir adurl
-
-.. ec dev build
-
-
-.. copy steps from ADSimDetector
-.. copy makefile from ADSimDetector/ioc/iocApp/Makefile
-
-.. Update this but discuss how we could have changed ADSupport to build GraphicsMagick
-.. configure/CONFIG_SITE.linux-x86_64.Common
-..     WITH_GRAPHICSMAGICK = YES
-..     GRAPHICSMAGICK_INCLUDE=/usr/include/GraphicsMagick
-
-..     # THIS COULD GO INTO ADSUPPORT AND THEN WE DONT NEED INCLUDE OR apt-install
-..     # GRAPHICSMAGICK_EXTERNAL = NO
-
-.. apt update
-.. apt install apt-file
-.. apt-file find Magick++.h
-.. add boost lib apt install
-.. AND libgraphicsmagick++1-dev
-.. change last step to adurl from ADSimDetector
-.. cp ibek-defs/adcore/adcore.sh ibek-defs/adurl/adurl.sh
-
-
-.. Once running:-
-.. caput -S BL01T-EA-TST-02:CAM:URL1
diff --git a/docs/user/tutorials/08_debug_generic_ioc.rst b/docs/user/tutorials/08_debug_generic_ioc.rst
diff --git a/docs/user/tutorials/09_test_generic_ioc.rst b/docs/user/tutorials/09_test_generic_ioc.rst

Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,9 @@`
`16`	`16`	`"Beamlines",`
`17`	`17`	`"blxxi",`
`18`	`18`	`"blxxt",`
	`19`	`+ "GRAPHICSMAGICK",`
`19`	`20`	`"klogout",`
	`21`	`+ "Magick",`
`20`	`22`	`"MVME"`
`21`	`23`	`]`
`22`	`24`	`}`