changes from review after pvi branch merge

Author: gilesknap

docs/user/reference/environment.rst

@@ -38,11 +38,11 @@ Required Variables
 
     You can have multiple mappings if needed by separating them with a space.
 
--   **EC_NAMESPACE**: defines the namespace in a Kubernetes Cluster that your IOC
+-   **EC_K8S_NAMESPACE**: defines the namespace in a Kubernetes Cluster that your IOC
     Instances will be deployed to. When you come to set up a cluster you will
     need to create a namespace for your domain. This is the name you should
     use here. If you are not using Kubernetes then you can leave this as
-    ``EC_NAMESPACE=`` and this will deploy IOC Instances to the local server's
+    ``EC_K8S_NAMESPACE=local`` and this will deploy IOC Instances to the local server's
     docker or podman instance.
 
 -   **EC_DOMAIN_REPO**: this is a link back to the repository that defines this

docs/user/tutorials/create_beamline.rst

@@ -131,7 +131,7 @@ where indicated):
 - SECTION 1:
 
   - ``export EC_REGISTRY_MAPPING='github.com=ghcr.io'``
-  - ``export EC_K8S_NAMESPACE=``
+  - ``export EC_K8S_NAMESPACE=local``
   - ``export [email protected]:**YOUR GITHUB ACCOUNT**/bl01t``
 
 - SECTION 2:

docs/user/tutorials/create_ioc.rst

@@ -30,7 +30,7 @@ This folder needs to contain these two items:
     can take a number of forms
     `listed here <https://github.com/epics-containers/ibek/blob/ea9da7e1cfe88f2a300ad236f820221837dd9dcf/src/ibek/templates/ioc/config/start.sh>`_.
 
-values.yaml 
+values.yaml
 ~~~~~~~~~~~~~~~~~~~~~~~
 
 We will start by creating the values.yaml file:
@@ -45,7 +45,7 @@ This should launch vscode and open the values.yaml file. Add the following:
 
 .. code-block:: yaml
 
-    image: ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.10.7
+    image: ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.11.1
 
 This tells the IOC Instance to run in the ``ioc-adsimdetector-linux-runtime``
 container. This container was built by the Generic IOC source repo here
@@ -190,7 +190,7 @@ This should launch vscode and open the ioc.yaml file. Add the following:
 
 .. code:: yaml
 
-    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.10.7/ibek.ioc.schema.json
+    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.11.1/ibek.ioc.schema.json
 
     ioc_name: bl01t-ea-ioc-02
     description: Example simulated camera for BL01T
@@ -290,6 +290,9 @@ Now we can start our simulation detector like this:
 .. code-block:: bash
 
     ec ioc exec bl01t-ea-ioc-02
+    # enable the PVA plugin that publishes the output
+    caput BL01T-EA-TST-02:PVA:EnableCallbacks 1
+    # start the simulation detector
     caput BL01T-EA-TST-02:DET:Acquire 1
 
 You should see a moving image appear in the ``c2dv`` window. For smoothest
@@ -317,15 +320,15 @@ That is because every Generic IOC publishes an *IOC schema* that describes
 the set of entities that an instance of that IOC may instantiate.
 
 The Generic IOC we used was released at this location:
-https://github.com/epics-containers/ioc-adsimdetector/releases/tag/2023.10.7.
+https://github.com/epics-containers/ioc-adsimdetector/releases/tag/2023.11.1.
 This page includes the assets that are published as part of the release and
 one of those is ``ibek.ioc.schema.json``. This is the *IOC schema* for the
 ``ioc-adsimdetector`` Generic IOC. This is what we referred to at the top of
 our *IOC yaml* file like this:
 
 .. code:: yaml
 
-    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.10.7/ibek.ioc.schema.json
+    # yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.11.1/ibek.ioc.schema.json
 
 When editing with a YAML aware editor like VSCode this will enable auto
 completion and validation of the *IOC yaml* file. To enable this in VSCode
@@ -361,16 +364,17 @@ To see what ibek generated you can go and look inside the IOC container:
 .. code:: bash
 
     ec ioc exec bl01t-ea-ioc-02
-    ls /opt/epics/ioc/iocBoot/iocbl01t-ea-ioc-02
-    cat /tmp/ioc.subst
-    cat /tmp/st.cmd
+    cd /epics/runtime/
+    cat ioc.subst
+    cat st.cmd
 
 .. note::
 
         The startup script and database are generated at container run time,
-        by ``ibek``. They are generated in the /tmp folder of the container.
-        This is because this is the only folder that is guaranteed to be
-        writeable due to container security considerations.
+        by ``ibek``. They are generated in the /epics/runtime folder
+        of the container.
+        In Kubernetes this will be a persistent volume so that it can be
+        shared for easy debugging of IOC Instances.
 
 If you would like to see an IOC Instance that uses a raw startup script and
 database then you can copy these two files out of the container and into
@@ -379,8 +383,8 @@ docker if that is what you are using):
 
 .. code-block:: bash
 
-    podman cp bl01t-ea-ioc-02:/tmp/st.cmd iocs/bl01t-ea-ioc-02/config
-    podman cp bl01t-ea-ioc-02:/tmp/ioc.subst iocs/bl01t-ea-ioc-02/config/ioc.subst
+    podman cp bl01t-ea-ioc-02:/epics/runtime/st.cmd iocs/bl01t-ea-ioc-02/config
+    podman cp bl01t-ea-ioc-02:/epics/runtime/ioc.subst iocs/bl01t-ea-ioc-02/config/ioc.subst
     # no longer need an ibek ioc yaml file
     rm iocs/bl01t-ea-ioc-02/config/ioc.yaml
     # re-deploy from local filesystem

docs/user/tutorials/deploy_example.rst

@@ -130,6 +130,13 @@ check that the IOC instance version is available as expected:
     Available instance versions for bl01t-ea-ioc-01:
         2023.11.1
 
+.. note::
+
+    The above command is the first one to look at your github repository.
+    This is how it finds out the versions
+    of the IOC instance that are available. If you get an error it may be
+    because you set EC_DOMAIN_REPO incorrectly in environment.sh. Check it
+    and source it again to pick up any changes.
 
 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

docs/user/tutorials/dev_container.rst

@@ -96,20 +96,12 @@ Starting a Developer Container
   This will affect most Redhat users and you will see an error regarding
   permissions on the /tmp folder when VSCode is building your devcontainer.
 
-  Here is a temporary workaround, paste this into a terminal:
+  Here is a workaround that disables SELinux labels in podman.
+  Paste this into a terminal:
 
   .. code-block:: bash
 
-    echo '
-    #!/bin/bash
-    if [[  "${@}" == "buildx build"* ]] ; then
-      shift 2
-      /usr/bin/podman buildx build --security-opt=label=disable "${@}"
-    else
-      /usr/bin/podman "${@}"
-    fi
-    ' > $HOME/.local/bin/podman
-    chmod +x $HOME/.local/bin/podman
+    sed -i ~/.config/containers/containers.conf -e '/label=false/d' -e '/^\[containers\]$/a label=false'
 
 
 For this section we will work with the ADSimDetector Generic IOC that we
@@ -125,7 +117,7 @@ this tutorial:
 
     # starting from folder bl01t so that the clone is next to bl01t
     cd ..
-    git clone --recursive [email protected]:epics-containers/ioc-adsimdetector.git -b 2023.10.7
+    git clone --recursive [email protected]:epics-containers/ioc-adsimdetector.git -b 2023.11.1
     cd ioc-adsimdetector
     ec dev build
 
@@ -228,6 +220,17 @@ clear it.
 
 Also take this opportunity to add the folder ``/epics`` to the workspace.
 
+.. note::
+
+  Docker Users: your account inside the container will not be the owner of
+  /epics files. vscode will try to open the repos in epics-base and support/*
+  and git will complain about ownership. You can cancel out of these errors
+  as you should not edit project folders inside of ``/epics`` - they were
+  built by the container and should be considered immutable. We will learn
+  how to work on support modules in later tuorials. This error should only
+  be seen on first launch. podman users will have no such problem becuase they
+  will be root inside the container and root build the container.
+
 You can now easily browse around the ``/epics`` folder and see all the
 support modules and epics-base. This will give you a feel for the layout of
 files in the container. Here is a summary (where WS is your workspace on your
@@ -282,10 +285,12 @@ Try the following:
 
 .. code::
 
-   cd /epics/ioc-adsimdetector
-   rm -r ioc/config
-   ln -s /repos/bl01t/iocs/bl01t-ea-ioc-02/config ioc
-   ioc/start.sh
+   cd /epics/ioc
+   rm -r config
+   ln -s /repos/bl02t/iocs/bl02t-ea-ioc-02/config .
+   # check the ln worked
+   ls -l config
+   ./start.sh
 
 This removed the boilerplate config and replaced it with the config from
 the IOC instance bl01t-ea-ioc-02. Note that we used a soft link, this