diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 44de8d36..5a12f276 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -19,10 +19,6 @@ "upgradePackages": false } }, - // Set *default* container specific settings.json values on container create. - "settings": { - "python.defaultInterpreterPath": "/venv/bin/python" - }, "customizations": { "vscode": { // Add the IDs of extensions you want installed when the container is created. @@ -51,4 +47,4 @@ "workspaceFolder": "${localWorkspaceFolder}", // After the container is created, install the python project in editable form "postCreateCommand": "pip install -e '.[dev]'" -} +} \ No newline at end of file diff --git a/docs/user/reference/environment.rst b/docs/user/reference/environment.rst index 41791a04..f961a1c6 100644 --- a/docs/user/reference/environment.rst +++ b/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 diff --git a/docs/user/tutorials/create_beamline.rst b/docs/user/tutorials/create_beamline.rst index 75257cf6..7c25cae8 100644 --- a/docs/user/tutorials/create_beamline.rst +++ b/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 EC_DOMAIN_REPO=git@github.com:**YOUR GITHUB ACCOUNT**/bl01t`` - SECTION 2: diff --git a/docs/user/tutorials/create_ioc.rst b/docs/user/tutorials/create_ioc.rst index e1cc063b..d4332371 100644 --- a/docs/user/tutorials/create_ioc.rst +++ b/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 `_. -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,7 +320,7 @@ 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 @@ -325,7 +328,7 @@ 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 diff --git a/docs/user/tutorials/deploy_example.rst b/docs/user/tutorials/deploy_example.rst index bc402eee..fd9c0142 100644 --- a/docs/user/tutorials/deploy_example.rst +++ b/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 diff --git a/docs/user/tutorials/dev_container.rst b/docs/user/tutorials/dev_container.rst index f9f2da61..b6746a03 100644 --- a/docs/user/tutorials/dev_container.rst +++ b/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 git@github.com:epics-containers/ioc-adsimdetector.git -b 2023.10.7 + git clone --recursive git@github.com: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