Debug an IOC instance locally#
Warning
This is an early draft
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 guide. That IOC is called bl01t-ea-test-02 in the guide but you may have chosen a different name.
Setting up#
Get the IOC Instance definition repository and deliberately break the IOC instance so that you can debug it.
git clone git@github.com: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:
ec -v deploy-local services/bl01t-ea-test-02
You should see something like this (for docker users - docker users will see something similar):
$ ec -v deploy-local services/bl01t-ea-test-02
docker --version
docker buildx version
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
docker stop -t0 bl01t-ea-test-02
docker rm -f bl01t-ea-test-02
docker volume rm -f bl01t-ea-test-02_config
docker volume create bl01t-ea-test-02_config
docker rm -f busybox
docker container create --name busybox -v bl01t-ea-test-02_config:/copyto busybox
docker cp /home/giles/tutorial/bl01t/services/bl01t-ea-test-02/config/ioc.yaml busybox:copyto
docker rm -f busybox
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-adsimdetectorruntime:2024.2.2
76c2834dac805780b3329af91c332abb90fb2692a510c11b888b82e48f60b44f
docker ps -f name=bl01t-ea-test-02 --format '{{.Names}}'
Now if you try these commands you should see that the IOC instance keeps restarting and that the logs show an error:
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:
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-adsimdetectorruntime: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.
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):
docker rm -f bl01t-ea-test-02-debug
You can now apply the fix you made to the local filesystem and retry the deployment.