further updates to introduction pages

gilesknap · gilesknap · commit d7d50a362703 · 2023-10-24T15:44:39.000+01:00
diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -15,16 +15,14 @@ side-bar.
 
             tutorials/intro
             tutorials/setup_workstation
-            tutorials/devcontainer
-            tutorials/epics_devcontainer
-            tutorials/setup_k8s
             tutorials/create_beamline
             tutorials/deploy_example
             tutorials/ioc_changes
             tutorials/generic_ioc
             tutorials/debug_generic_ioc
             tutorials/test_generic_ioc
             tutorials/support_module
+            tutorials/setup_k8s
             tutorials/rtems_setup
             tutorials/rtems_ioc
             tutorials/ibek
diff --git a/docs/user/reference/faq.rst b/docs/user/reference/faq.rst
@@ -33,7 +33,7 @@ Answers:
 How can I do IOC rollback if the internet is down?
 --------------------------------------------------
 The examples all use cloud registries for storing the Generic IOC images and
-IOC instance Helm Charts. However it is still possible to roll back an IOC
+IOC instances. However it is still possible to roll back an IOC
 version when the internet is not available.
 
 That is because Helm keeps track of several versions of each chart it
diff --git a/docs/user/tutorials/create_beamline.rst b/docs/user/tutorials/create_beamline.rst
@@ -5,14 +5,15 @@ Create a Beamline Repository
 
 In this tutorial we will create a new beamline source repository.
 
-All IOCs that we deploy to the cluster will be grouped into domains and each
-domain will have its own repository for the source code of the IOC instances
-that it contains.
+All IOC Instances that we deploy will be grouped into domains and each
+domain will have its own repository which defines those Instances.
+Typically each beamline would have its own domain and
+the accelerator would be split into a few functional domains.
 
-In the case of Beamlines, the domain is the beamline itself. Here
+In the case of Beamlines, the domain named after the beamline itself. At DLS
 we use the naming convention ``blxxc`` where ``xx`` is the beamline number,
 and c is the class of beamline. For example ``bl01t`` is the beamline 1,
-type test.
+type ``test``.
 
 .. note::
 
@@ -22,14 +23,19 @@ type test.
 
 In this tutorial we will create the test beamline repository ``bl01t``.
 When the project ``bl01t`` is pushed to GitHub, continuous integration will
-generate helm charts for each IOC instance it defines
-and push them to your GitHub account's OCI registry.
+verify that each of the IOCs in the beamline are valid by launching them
+with basic configuration.
+
+Each of these instances will be using a
+Generic IOC image. Ideally the CI for each Generic IOC should have already run
+system tests against simulated hardware. (this is something we aspire to
+using simulated hardware provided by `Tickit <https://github.com/dls-controls/tickit>`_)
 
 The beamline will come with a single example IOC and further steps in the
 following tutorials will teach you how to add your own.
 
 For accelerator domains the approach described here will be identical. The
-only difference is that IOCs are split by domain rather than by beamline.
+only difference is that IOC repos are split by domain rather than by beamline.
 A different naming convention will be used for accelerator domains (to be
 determined).
 
diff --git a/docs/user/tutorials/devcontainer.rst b/docs/user/tutorials/devcontainer.rst
diff --git a/docs/user/tutorials/epics_devcontainer.rst b/docs/user/tutorials/epics_devcontainer.rst
diff --git a/docs/user/tutorials/setup_k8s.rst b/docs/user/tutorials/setup_k8s.rst
@@ -1,8 +1,13 @@
 .. _setup_kubernetes:
 
+
 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
@@ -136,11 +141,6 @@ If you do have separate workstation then edit the file .kube/config replacing
 127.0.0.1 with your server's IP Address. For a single machine the file is left
 as is.
 
-Note that in the previous step  `devcontainer-configure`
-you already configured the environment variable
-``KUBECONFIG`` to point to the cluster configuration file at
-``~/.kube/config``.
-
 
 Create an epics IOCs namespace and context
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
diff --git a/docs/user/tutorials/setup_workstation.rst b/docs/user/tutorials/setup_workstation.rst
@@ -74,15 +74,17 @@ devcontainer in the next tutorial.
 
 
 Next install docker or podman as the your container platform. epics-containers
-has been tested with podman 4.4.1 on RedHat 8, and docker is also be supported.
-If you are using docker, simply replace ``podman`` with ``docker`` in the commands.
-
-The podman version required is 4.0 or later. This is not easy to obtain on debian
-distributions at the time of writing, but details of how to compile from source
-are contained
-`in this Dockerfile <https://github.com/epics-containers/dev-e7/blob/main/docker/Dockerfile>`_
-under the heading  ``Stage to add a recent podman client``
-
+has been tested with podman 4.4.1 on RedHat 8, and the current version of Docker
+for Ubuntu 22.04.
+If you are using docker, simply replace ``podman`` with ``docker`` in the
+commands listed in these tutorials.
+
+The podman version required is 4.0 or later. Any version of docker since 20.10
+will also work. Pick the tool that has the most recent version for your platform.
+RedHat 8 and above have recent podman versions. Debian platforms don't yet
+have recent podman versions available. If you have a choice then podman is
+preferred because it does not require root access and it is the tool with
+which epics-containers has had the most testing.
 
 The links below have details of how to install your choice of container platform:
 
@@ -96,3 +98,17 @@ CLI tools by clicking on the appropriate linux distribution link.
 .. _Install docker: https://docs.docker.com/engine/install/
 .. _Install podman: https://podman.io/getting-started/installation
 
+Kubernetes
+----------
+
+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.
+
+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
+point and continue with the tutorials.
+
