completed create_ioc

Author: gilesknap

docs/explanations/introduction.md

@@ -39,7 +39,7 @@ forks of these repositories.
 
 #### Generic IOCs and instances
 
-An important principal of the approach presented here is that an IOC container image represents a 'Generic' IOC. The Generic IOC image is used for all IOC instances that connect to a given class of device. For example the Generic IOC image here: [ghcr.io/epics-containers/ioc-adaravis-linux-runtime:2024.1.2](https://github.com/epics-containers/ioc-adaravis/pkgs/container/ioc-adaravis-linux-runtime) uses the AreaDetector driver ADAravis to connect to GigE cameras.
+An important principal of the approach presented here is that an IOC container image represents a 'Generic' IOC. The Generic IOC image is used for all IOC instances that connect to a given class of device. For example the Generic IOC image here: [ghcr.io/epics-containers/ioc-adaravis-linux-runtime:2024.2.2 ](https://github.com/epics-containers/ioc-adaravis/pkgs/container/ioc-adaravis-linux-runtime) uses the AreaDetector driver ADAravis to connect to GigE cameras.
 
 An IOC instance runs in a container runtime by loading two things:
 

docs/how-to/debug.md

@@ -1,7 +1,88 @@
 # Debug an IOC instance locally
 
-Todo
+:::{warning}
+This is an early draft
+:::
 
-# Debug an IOC instance in Kubernetes
+This guide will show you how to debug an IOC instance locally. It will use the example IOC made in the [Create an IOC instance](./create-ioc-instance.md) guide. That IOC is called `bl01t-ea-test-02` in the guide but you may have chosen a different name.
 
-Todo
+## Setting up
+
+Get the IOC Instance definition repository and deliberately break the IOC instance so that you can debug it.
+
+```bash
+git clone [email protected]:YOUR_GITHUB_USERNAME/bl01t.git
+cd bl01t
+source environment.sh
+code .
+# now edit services/bl01t-ea-test-02/config/ioc.yaml
+```
+
+## Breaking the IOC instance
+
+Add the phrase 'deliberate_error' to the top of the `ioc.yaml` file. Then try to launch the IOC instance, but use the `-v` flag to see the underlying commands:
+
+```bash
+ec -v deploy-local services/bl01t-ea-test-02
+```
+
+You should see something like this (for docker users - podman users will see something similar):
+
+<pre>$ ec -v deploy-local services/bl01t-ea-test-02
+<font color="#5F8787">docker --version</font>
+<font color="#5F8787">docker buildx version</font>
+Deploy TEMPORARY version 2024.2.17-b8.30 from /home/giles/tutorial/bl01t/services/bl01t-ea-test-02 to the local docker instance
+Are you sure ? [y/N]: y
+<font color="#5F8787">docker stop -t0 bl01t-ea-test-02</font>
+<font color="#5F8787">docker rm -f bl01t-ea-test-02</font>
+<font color="#5F8787">docker volume rm -f bl01t-ea-test-02_config</font>
+<font color="#5F8787">docker volume create bl01t-ea-test-02_config</font>
+<font color="#5F8787">docker rm -f busybox</font>
+<font color="#5F8787">docker container create --name busybox -v bl01t-ea-test-02_config:/copyto busybox</font>
+<font color="#5F8787">docker cp /home/giles/tutorial/bl01t/services/bl01t-ea-test-02/config/ioc.yaml busybox:copyto</font>
+<font color="#5F8787">docker rm -f busybox</font>
+<font color="#5F8787">docker run -dit --net host --restart unless-stopped -l is_IOC=true -l version=2024.2.17-b8.30 -v bl01t-ea-test-02_config:/epics/ioc/config/ -e IOC_NAME=bl01t-ea-test-02  --name bl01t-ea-test-02 ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.2.2</font>
+76c2834dac805780b3329af91c332abb90fb2692a510c11b888b82e48f60b44f
+<font color="#5F8787">docker ps -f name=bl01t-ea-test-02 --format &apos;{{.Names}}&apos;</font>
+</pre>
+
+Now if you try these commands you should see that the IOC instance keeps restarting and that the logs show an error:
+
+```bash
+ec ps
+ec logs bl01t-ea-test-02
+```
+
+## Debugging the IOC instance
+
+Now you can tell `ec` to stop the IOC instance and then run it in a way that you can debug it, by copying the command that `ec` used to run the IOC instance and adding the `--entrypoint bash` and removing `-d` flag and `--restart unless-stopped`. Also change the name to have a `-debug` suffix, like so:
+
+```bash
+ec stop bl01t-ea-test-02
+docker run --entrypoint bash -it --net host -l is_IOC=true -l version=2024.2.17-b8.30 -v bl01t-ea-test-02_config:/epics/ioc/config/ -e IOC_NAME=bl01t-ea-test-02  --name bl01t-ea-test-02-debug ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.2.2
+```
+
+You should now be in a shell inside the container. You can look at the files and run the IOC instance manually to see what the error is. You can re-run the IOC instance multiple times and you can even install your favourite editor or debugging tools.
+
+e.g.
+
+```bash
+apt update
+apt install vim
+ls /epics/ioc/config/
+cat /epics/ioc/config/ioc.yaml
+cd /epics/ioc
+./start.sh
+# ctrl-d to exit
+vim /epics/ioc/config/ioc.yaml
+# fix the error
+./start.sh
+```
+
+When you are done you can exit the container with `ctrl-d` and then remove it (or you can keep it around for later and restart it with `docker start -i bl01t-ea-test-02-debug`):
+
+```bash
+docker rm -f bl01t-ea-test-02-debug
+```
+
+You can now apply the fix you made to the local filesystem and retry the deployment.

docs/tutorials/create_ioc.md

@@ -52,7 +52,7 @@ code services/bl01t-ea-test-02/values.yaml
 You will now have vscode and open and editing the values.yaml file. Add the following:
 
 ```yaml
-image: ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.1.1
+image: ghcr.io/epics-containers/ioc-adsimdetector-linux-runtime:2024.2.2
 ```
 
 This tells the IOC Instance to run in the `ioc-adsimdetector-linux-runtime`
@@ -283,15 +283,15 @@ the c2dv viewer showing an image from the example IOC
 
 Above we looked at some ibek *Support yaml* and created an *IOC yaml* file.
 The details of where *Support yaml* files come from and how to create your
-own are covered in later tutorials on creating Generic services.
+own are covered a later tutorial {any}`generic_ioc`.
 
 However, without looking into the set of *Support yaml* files that are
 inside a given Generic IOC we can still make a meaningful *IOC yaml* file.
 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/2024.1.1>.
+<https://github.com/epics-containers/ioc-adsimdetector/releases/tag/2024.2.2>.
 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
@@ -355,14 +355,21 @@ podman cp bl01t-ea-test-02:/epics/runtime/st.cmd services/bl01t-ea-test-02/confi
 podman cp bl01t-ea-test-02:/epics/runtime/ioc.subst services/bl01t-ea-test-02/config/ioc.subst
 # no longer need an ibek ioc yaml file
 rm services/bl01t-ea-test-02/config/ioc.yaml
-# re-deploy from local filesystem
-ec deploy-local services/bl01t-ea-test-02
 ```
 
+You will need to make a minor change to the `ioc.subst` file. Edit this and remove references to the two template files with `.pvi` in their name. These are PVI generated templates for use with BlueSky Asyc and are not available in manually build IOC Instances.
+
 Your IOC Instance will now be using the raw startup script and database. But
 should behave exactly the same as before. You are free to experiment with
 changes in the startup script and substitution file and re-deploy the IOC.
 
+To start your new version of the the Instance and replace the previous one use the `deploy-local` command again:
+
+```bash
+# re-deploy from local filesystem
+ec deploy-local services/bl01t-ea-test-02
+```
+
 :::{note}
 We used some raw podman / docker commands in the above script. If you
 want to know what commands `ec` is running under the hood then you can