deploy: ba97463

2023.11.1/_sources/user/reference/environment.rst.txt

@@ -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

2023.11.1/_sources/user/tutorials/create_beamline.rst.txt

@@ -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:

2023.11.1/_sources/user/tutorials/create_ioc.rst.txt

@@ -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

2023.11.1/_sources/user/tutorials/deploy_example.rst.txt

@@ -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

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

@@ -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

2023.11.1/user/reference/environment.html

@@ -543,11 +543,11 @@ <h3>Required Variables<a class="headerlink" href="#required-variables" title="Li
 </ul>
 <p>You can have multiple mappings if needed by separating them with a space.</p>
 </li>
-<li><p><strong>EC_NAMESPACE</strong>: defines the namespace in a Kubernetes Cluster that your IOC
+<li><p><strong>EC_K8S_NAMESPACE</strong>: 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
-<code class="docutils literal notranslate"><span class="pre">EC_NAMESPACE=</span></code> and this will deploy IOC Instances to the local server’s
+<code class="docutils literal notranslate"><span class="pre">EC_K8S_NAMESPACE=local</span></code> and this will deploy IOC Instances to the local server’s
 docker or podman instance.</p></li>
 <li><p><strong>EC_DOMAIN_REPO</strong>: this is a link back to the repository that defines this
 domain. For example the bl38p reference beamline repository uses

2023.11.1/user/tutorials/create_beamline.html

@@ -611,7 +611,7 @@ <h3>Environment.sh<a class="headerlink" href="#environment-sh" title="Link to th
 <li><p>SECTION 1:</p>
 <ul>
 <li><p><code class="docutils literal notranslate"><span class="pre">export</span> <span class="pre">EC_REGISTRY_MAPPING='github.com=ghcr.io'</span></code></p></li>
-<li><p><code class="docutils literal notranslate"><span class="pre">export</span> <span class="pre">EC_K8S_NAMESPACE=</span></code></p></li>
+<li><p><code class="docutils literal notranslate"><span class="pre">export</span> <span class="pre">EC_K8S_NAMESPACE=local</span></code></p></li>
 <li><p><code class="docutils literal notranslate"><span class="pre">export</span> <span class="pre">EC_DOMAIN_REPO=git&#64;github.com:**YOUR</span> <span class="pre">GITHUB</span> <span class="pre">ACCOUNT**/bl01t</span></code></p></li>
 </ul>
 </li>

2023.11.1/user/tutorials/create_ioc.html

@@ -546,7 +546,7 @@ <h3>values.yaml<a class="headerlink" href="#values-yaml" title="Link to this hea
 </pre></div>
 </div>
 <p>This should launch vscode and open the values.yaml file. Add the following:</p>
-<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.10.7</span>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">image</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2023.11.1</span>
 </pre></div>
 </div>
 <p>This tells the IOC Instance to run in the <code class="docutils literal notranslate"><span class="pre">ioc-adsimdetector-linux-runtime</span></code>
@@ -684,7 +684,7 @@ <h3>config<a class="headerlink" href="#config" title="Link to this heading">#</a
 </pre></div>
 </div>
 <p>This should launch vscode and open the ioc.yaml file. Add the following:</p>
-<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.10.7/ibek.ioc.schema.json</span>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.11.1/ibek.ioc.schema.json</span>
 
 <span class="nt">ioc_name</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bl01t-ea-ioc-02</span>
 <span class="nt">description</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">Example simulated camera for BL01T</span>
@@ -768,6 +768,9 @@ <h3>Viewing IOC output<a class="headerlink" href="#viewing-ioc-output" title="Li
 </div>
 <p>Now we can start our simulation detector like this:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ec<span class="w"> </span>ioc<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>bl01t-ea-ioc-02
+<span class="c1"># enable the PVA plugin that publishes the output</span>
+caput<span class="w"> </span>BL01T-EA-TST-02:PVA:EnableCallbacks<span class="w"> </span><span class="m">1</span>
+<span class="c1"># start the simulation detector</span>
 caput<span class="w"> </span>BL01T-EA-TST-02:DET:Acquire<span class="w"> </span><span class="m">1</span>
 </pre></div>
 </div>
@@ -795,12 +798,12 @@ <h2>ibek Explanation<a class="headerlink" href="#ibek-explanation" title="Link t
 That is because every Generic IOC publishes an <em>IOC schema</em> that describes
 the set of entities that an instance of that IOC may instantiate.</p>
 <p>The Generic IOC we used was released at this location:
-<a class="github reference external" href="https://github.com/epics-containers/ioc-adsimdetector/releases/tag/2023.10.7">epics-containers/ioc-adsimdetector</a>.
+<a class="github reference external" href="https://github.com/epics-containers/ioc-adsimdetector/releases/tag/2023.11.1">epics-containers/ioc-adsimdetector</a>.
 This page includes the assets that are published as part of the release and
 one of those is <code class="docutils literal notranslate"><span class="pre">ibek.ioc.schema.json</span></code>. This is the <em>IOC schema</em> for the
 <code class="docutils literal notranslate"><span class="pre">ioc-adsimdetector</span></code> Generic IOC. This is what we referred to at the top of
 our <em>IOC yaml</em> file like this:</p>
-<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.10.7/ibek.ioc.schema.json</span>
+<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="c1"># yaml-language-server: $schema=https://github.com/epics-containers/ioc-adsimdetector/releases/download/2023.11.1/ibek.ioc.schema.json</span>
 </pre></div>
 </div>
 <p>When editing with a YAML aware editor like VSCode this will enable auto
@@ -829,24 +832,25 @@ <h2>Raw Startup Script and Database<a class="headerlink" href="#raw-startup-scri
 <code class="docutils literal notranslate"><span class="pre">start.sh</span></code> in the <code class="docutils literal notranslate"><span class="pre">config</span></code> folder, this can contain any script you like.</p>
 <p>To see what ibek generated you can go and look inside the IOC container:</p>
 <div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>ec<span class="w"> </span>ioc<span class="w"> </span><span class="nb">exec</span><span class="w"> </span>bl01t-ea-ioc-02
-ls<span class="w"> </span>/opt/epics/ioc/iocBoot/iocbl01t-ea-ioc-02
-cat<span class="w"> </span>/tmp/ioc.subst
-cat<span class="w"> </span>/tmp/st.cmd
+<span class="nb">cd</span><span class="w"> </span>/epics/runtime/
+cat<span class="w"> </span>ioc.subst
+cat<span class="w"> </span>st.cmd
 </pre></div>
 </div>
 <div class="admonition note">
 <p class="admonition-title">Note</p>
 <p>The startup script and database are generated at container run time,
-by <code class="docutils literal notranslate"><span class="pre">ibek</span></code>. 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.</p>
+by <code class="docutils literal notranslate"><span class="pre">ibek</span></code>. 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.</p>
 </div>
 <p>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
 your IOC Instance config folder like this (replace podman with
 docker if that is what you are using):</p>
-<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>podman<span class="w"> </span>cp<span class="w"> </span>bl01t-ea-ioc-02:/tmp/st.cmd<span class="w"> </span>iocs/bl01t-ea-ioc-02/config
-podman<span class="w"> </span>cp<span class="w"> </span>bl01t-ea-ioc-02:/tmp/ioc.subst<span class="w"> </span>iocs/bl01t-ea-ioc-02/config/ioc.subst
+<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>podman<span class="w"> </span>cp<span class="w"> </span>bl01t-ea-ioc-02:/epics/runtime/st.cmd<span class="w"> </span>iocs/bl01t-ea-ioc-02/config
+podman<span class="w"> </span>cp<span class="w"> </span>bl01t-ea-ioc-02:/epics/runtime/ioc.subst<span class="w"> </span>iocs/bl01t-ea-ioc-02/config/ioc.subst
 <span class="c1"># no longer need an ibek ioc yaml file</span>
 rm<span class="w"> </span>iocs/bl01t-ea-ioc-02/config/ioc.yaml
 <span class="c1"># re-deploy from local filesystem</span>

2023.11.1/user/tutorials/deploy_example.html

@@ -615,6 +615,14 @@ <h2>Deploy the Example IOC Instance<a class="headerlink" href="#deploy-the-examp
 <span class="w">    </span><span class="m">2023</span>.11.1
 </pre></div>
 </div>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>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.</p>
+</div>
 <p>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:</p>