update dev_container2 to comply with simplified ioc-template

docs/reference/troubleshooting.md

@@ -1,5 +1,34 @@
 # Troubleshooting
 
+(multiple-iocs)=
+## Running Multiple IOCs in DevContainers on one Workstation
+
+If you want to test two or more IOCs on a workstation, you can launch two developer containers and run an IOC instance in each.
+
+However, the auto port forwarding will not be able to bind to the default ports for the second container. It will therefore pick a different port number to bind to on the host. Inside of the container the IOC will still be listening on the default ports, but on the host the ports will be different. For example here is the PORTS tab of vscode when I have launched a second IOC on my workstation:
+
+:::{figure} ../images/auto-ports2.png
+Port Forwarding in the bottom panel of VSCode
+:::
+
+You will be able to interact with each of these IOCs as usual inside the container but what if you want to connect to both of them from outside the container? This can be done by adding the list of ports to the appropriate environment variables. For example:
+
+```bash
+export EPICS_CA_NAME_SERVERS="127.0.0.1:5064 127.0.0.1:5065"
+export EPICS_PVA_NAME_SERVERS="127.0.0.1:5075 127.0.0.1:5076"
+```
+
+The equivalent settings in phoebus' settings.ini file would be:
+
+```ini
+org.phoebus.pv.ca/name_servers=127.0.0.1:5064 127.0.0.1:5064
+org.phoebus.pv.pva/epics_pva_name_servers=127.0.0.1:5075 127.0.0.1:5076
+```
+
+## Unable to contact IOC PVs from outside the developer container
+
+Note that sometimes you may get a zombie process holding on to your host's Channel Access ports. In this case when you start an IOC in devcontainer it will not bind to those ports as they are already in use. You just need to go to the PORTS tab and see which ports have been bound to the IOC and then set the environment variables accordingly. See the {any}`multiple-iocs` section for more information.
+
 ## Resetting VSCode Cache
 
 Occasionally if vscode gets stuck in a bad state, you may need to reset the cache.
@@ -16,6 +45,42 @@ rm -rf ~/.vscode/* ~/.vscode-server/*
 # restart vscode
 ```
 
+
+## Cleaning up Container Cache
+
+Very occasionally it may be necessary to reset all of your container cache. You might want to do this if you have filled up your disk or if you just want to get back to a known state.
+
+To remove all container cache on a workstation:
+
+```bash
+# clean out the docker local cache
+docker system prune -af
+# clean out the podman local cache
+podman system reset -f
+```
+
+The above removes:
+- all images
+- all containers including running containers
+- all volumes
+- all networks
+
+
+If on the other hand you would like to just clear individual containers or images then:
+
+
+```bash
+# list all containers including stopped ones
+docker ps -a
+# use the generated name (last column) to remove some containers
+docker rm container_name1 container_name2
+
+# list all images
+docker images
+# use the image id to remove some images
+docker rmi image_id1 image_id2
+```
+
 ## Permissions issues with GitHub
 
 Problem: in the devcontainer you see the following error:

docs/tutorials/create_ioc.md

@@ -42,7 +42,7 @@ You can find the Generic IOC container source for SimDetector here: <https://git
 
 Edit the `compose.yml` file in the `bl01t-ea-cam-01` folder to reflect the new IOC name and to refer to the Generic IOC container image for the SimDetector:
 
-- find and replace **replace_me** with **bl01t-ea-cam-01**
+- find and replace **ioc_default_name** with **bl01t-ea-cam-01**
 - replace **replace_with_image_uri** with **ghcr.io/epics-containers/ioc-adsimdetector-runtime:2024.9.1**
 
 That's it for the `compose.yml` file. This file is essentially boilerplate and would look very similar for every IOC Instance you create. The two unique things that this file does are:

docs/tutorials/deploy_example.md

@@ -70,9 +70,10 @@ There will be a short delay the first time while the container images are downlo
 The default example project will launch:
 
 - a basic IOC instance with a few records
-- a ca-gateway container that publishes the IOC PVs on localhost
+- a ca-gateway container that publishes the IOC PVs on localhost over Channel Access
+- a pva-gateway container that publishes the IOC PVs on localhost over PVAccess
 - a phoebus container that can be used to view the IOC PVs using an example bob file that comes with the template.
-
+- you will also see an init container run which just configures settings for pvagw and phoebus, then exits.
 
 You can see the status of the services by running the following command:
 
@@ -112,6 +113,9 @@ To run a bash shell inside the IOC container:
 ```bash
 docker compose exec example-test-01 bash
 caget EXAMPLE:SUM
+# or if you have the epics tools installed on your host
+export EPICS_CA_ADDR_LIST=127.0.0.1:5064
+caget EXAMPLE:SUM
 ```
 
 Once you have a shell inside the container you could inspect the following folders. Because this is the runtime container you will only see the binaries and runtime files, not the source code:

docs/tutorials/dev_container2.md

@@ -42,13 +42,13 @@ Note that you have the ability to install any other tools you might need inside
 
 ## Auto Port Forwarding
 
-If you want to use a GUI tool such as Phoebus or any other tools outside of your container, they cannot see the container network that your IOC is running in. However this is not an issue because developer containers provide auto port forwarding for you. When you start your IOC it will try to bind to the following ports by default:
+If you want to use a GUI tool such as Phoebus or any other tools outside of your container, they cannot see the container network that your IOC is running in. However this is not an issue because developer containers provide auto port forwarding for you. When you start your IOC it will bind to the following ports by default:
 
 - 5064 for Channel Access
 - 5065 for the caRepeater
 - 5075 for PV Access
 
-When the developer container sees these binds it auto forwards the hosts ports to the IOC's ports. The host binding that is forwarded is to the loopback adapter only, so only the host machine can see the forwarded ports. This is good for development as your PVs are only visible to your workstation.
+When the developer container sees the IOC bind to a port it auto forwards a host port to the IOC's port. The host binding that is forwarded is to the loopback adapter only, so only the host machine can see the forwarded ports. This is good for development as your PVs are only visible to your workstation.
 
 Once you have started your IOC you can check the ports are forwarded by looking in the PORTS tag of the bottom panel of VSCode. You should see something like this:
 
@@ -67,6 +67,10 @@ caget BL01T-EA-CAM-01:DET:Acquire
 
 Note that we are using the lesser know `EPICS_CA_NAME_SERVERS` environment variable here. This is because auto port forwarding has not forwarded the udp port required for the EPICS_CA_ADDR_LIST environment variable to work. The `EPICS_CA_NAME_SERVERS` environment variable tells channel access clients to use TCP only. For a detailed explanation of EPICS and container networks see [](../explanations/epics_protocols.md).
 
+:::{note}
+A useful consequence of auto port forwarding is that you can run multiple IOCs in multiple developer containers. Port conflicts will be automatically resolved, see {any}`multiple-iocs` for details.
+:::
+
 ## Phoebus
 
 Generic IOCs can use PVI to auto generate engineering screens for your IOC instance in the form of phoebus bob files. ioc-adsimdetector uses this to make screens for the simdetector driver and for all of the AreaDetector plugins installed in the IOC instance.
@@ -76,11 +80,14 @@ The ioc-template project supplies a startup script that configures Phoebus corre
 IMPORTANT: the commands we are about to run must be executed on the host, not in the developer container. We are looking for a host installed copy of phoebus or we are going to launch a container with phoebus in it. In either case, trying to do that from inside the developer container will fail.
 
 ```bash
-cd /workspaces/ioc-adsimdetector
+# Run this OUTSIDE of the developer container
+cd ioc-adsimdetector
 ./opi/phoebus-launch.sh
 ```
 
-Phoebus will be launched and attempt to load the bob file called **opi/auto-generated/index.bob**. The **opi** folder is a place where the author of this generic IOC could place some screens. The subfolder **auto-generated** is not committed to git and is where the IOC instance will place its autogenerated engineering screens - this folder is mounted into the container at target **/epics/opis**. The autogenerated screens always include an index.bob which is the entry point to all other autogenerated screens.
+Phoebus will be launched and attempt to load the bob file called **opi/auto-generated/index.bob**. The **opi** folder is a place where the author of this generic IOC could place some example screens. The subfolder **auto-generated** is not committed to git and is where the IOC instance will place its autogenerated engineering screens. This folder is mounted into the container at target **/epics/opis**. The autogenerated screens always include an index.bob which is the entry point to all other autogenerated screens.
+
+You should see an index screen that will have a button for the simdetector driver and for each of the AreaDetector plugins installed in the IOC instance. These screens are all autogenerated and simply show all the PVs in the IOC instance, with some grouping for clarity. You should now be able to interact with the detector using these screens.
 
 ## Nicer Overview Screen
 

docs/tutorials/ioc_changes1.md

@@ -68,16 +68,10 @@ If you like working entirely from the vscode window you can open a terminal in v
 ## Launching the Test Beamline
 
 Because the changes have been made in `t01-services` you can now launch the test beamline from outside of the devcontainer.
-However, it is important to remember that we cannot have two ca-gateway's trying to bind to the default CA port on the same host.
 
-Make sure the ca-gateway from the previous tutorial is stopped before launching the test beamline with the following:
+Before you do this. You must stop the IOC running in the devcontainer, that IOC is currently auto port forwarding the Channel Access ports to the host. If you launch the test beamline without stopping the IOC in the devcontainer then the test beamline's gateway will not be able to bind to the ports.
 
-```bash
-# IMPORTANT: do this in a terminal outside of the devcontainer
-cd ioc-adsimdetector/compose
-. ./environment.sh
-docker compose down
-```
+So stop the IOC in the devcontainer by typing `exit` in the IOC shell.
 
 Now you can launch your test beamline and it will have picked up the new extras.db. Note that we run caget inside the IOC container because not all users will have caget on their host. Those that have it on the host can just type: `caget BL01T-EA-CAM-01:TEST`.
 
@@ -92,6 +86,10 @@ docker compose exec example-test-01 caget BL01T-EA-CAM-01:TEST
 docker compose down
 ```
 
+:::{note}
+if you see the error "listen tcp 127.0.0.1:5064: bind: address already in use" they you have probably forgotten to stop the IOC in the devcontainer. Go back and stop the IOC in the devcontainer and type `docker compose up -d` again.
+:::
+
 ## Raw Startup Assets
 
 If you plan not to use `ibek` runtime asset creation you could use the raw startup assets from {any}`raw-startup-assets`. If you do this then the process above is identical except that you will add the `dbLoadRecords` command to the end of raw `st.cmd`.