Merge branch 'main' into k8s-tutorials

Author: gilesknap

docs/tutorials/create_beamline.md

@@ -42,7 +42,7 @@ NOTE: for these tutorials we will use your personal GitHub Account to store ever
 
 ## Steps
 
-1. Make sure you have activated the python virtual environment and that `copier` is installed. See instructions here: {any}`ec`.
+1. Make sure you have activated the python virtual environment and that `copier` is installed. See instructions here: {any}`copier`.
 
 1. Use copier to copy the services template repository to a new repository named `t01-services`. Note that there are two services templates, one for local deployments (using docker compose) and one for deployments to Kubernetes. We will use the local deployment template here.
 

docs/tutorials/create_ioc.md

@@ -126,7 +126,7 @@ The config folder can contain a variety of different files [as listed here](http
 
 Each `entity` listed in the *IOC yaml* file will create an instance of the support module `entity_model` that it refers to. It will pass a number of arguments to the `entity_model` that will be used to generate the startup script entries and EPICS Database entries for that entity. The `entity_model` is responsible for declaring the parameters it expects and how they are used in the script and DB entries it generates. It supplies types and descriptions for each of these parameters, plus may supply default values.
 
-We will be creating a simulation detector from the `ioc-adsimdetector` Generic IOC. The following *Support yaml* for the simulation detector is baked into the container. Once you have your container up and running you can use `ec exec bl01t-ea-cam-01 bash` to get a shell inside and see this file at **/epics/ibek_defs/ADSimDetector.ibek.support.yaml**.
+We will be creating a simulation detector from the `ioc-adsimdetector` Generic IOC. The following *Support yaml* for the simulation detector is baked into the container. Once you have your container up and running you can use `dc exec bl01t-ea-cam-01 bash` to get a shell inside and see this file at **/epics/ibek_defs/ADSimDetector.ibek.support.yaml**.
 
 ```yaml
 # yaml-language-server: $schema=https://github.com/epics-containers/ibek/releases/download/3.0.1/ibek.support.schema.json
@@ -299,7 +299,7 @@ We can launch all the services in the beamline as we did in the earlier tutorial
 ```bash
 cd t01-services
 source ./environment.sh
-ec up -d
+dc up -d
 ```
 
 The new screen will allow you to hit 'Acquire' on the CAMERA pane, and 'Enable' on the Standard Array pane. You should see the moving image from the simulation detector in the right hand image pane.
@@ -384,7 +384,7 @@ Fill out the rest of your NDProcess entity as follows:
 Now restart your simulation detector IOC:
 
 ```bash
-ec restart bl01t-ea-cam-01
+dc restart bl01t-ea-cam-01
 ```
 
 Once it is back up you can click on the bl01t-ea-cam-01 button in the 'Autogenerated Engineering Screens' pane and you will see a new 'NDProcess' entity. If you know about wiring up AreaDetector you can now wire this plugin into your pipeline and make modifications to the image data as it passes through.
@@ -400,7 +400,7 @@ folder. Or alternatively you could override behaviour completely by placing
 To see what ibek generated you can go and look inside the IOC container:
 
 ```bash
-ec exec bl01t-ea-test-02
+dc exec bl01t-ea-test-02
 cd /epics/runtime/
 cat ioc.subst
 cat st.cmd
@@ -431,7 +431,7 @@ Your IOC Instance will now be using the raw startup script and database. But sho
 
 Restart the IOC to see it operating as before (except that engineering screen generation will no longer happen):
 ```bash
-ec restart bl01t-ea-cam-01
+dc restart bl01t-ea-cam-01
 ```
 
 :::{note}

docs/tutorials/debug_generic_ioc.md

@@ -34,7 +34,7 @@ Comment out the apt-install line like this:
 ```
 
 Now rebuild the container - do this command from a new terminal *outside* of
-the devcontainer (make sure you have `ec` installed):
+the devcontainer:
 
 ```bash
 # for docker users - builkit complicates debugging at present
@@ -61,8 +61,7 @@ compilation terminated.
 
 When a container build fails the container image is created up to the point
 where the last successful Dockerfile command was run. This means that we can
-investigate the build failure by running a shell in the container. `ec`
-provides us with the following convenience command to do this:
+investigate the build failure by running a shell in the container.
 
 - scroll up the page until you see the last successful build step e.g.
 

docs/tutorials/deploy_example.md

@@ -41,7 +41,7 @@ have followed the instructions in the previous tutorial correctly.
 
 Make sure you have a terminal open and the current working directory is your `t01-services` project root folder.
 
-The standard way to set up your environment for any ec services repository is to source the environment.sh script from the root of the services repo. i.e.
+The standard way to set up your environment for any epics-containers services repository is to source the environment.sh script from the root of the services repo. i.e.
 
 ```bash
 source ./environment.sh
@@ -80,23 +80,23 @@ You can see the status of the services by running the following command:
 docker compose ps
 ```
 
-In environment.sh we created an alias for `docker compose` named `ec` from now on we'll shorten the commands to use `ec` instead of `docker compose`.
+In environment.sh we created an alias for `docker compose` named `dc` from now on we'll shorten the commands to use `dc` instead of `docker compose`.
 
 ## Managing the Example IOC Instance
 
 ### Starting and Stopping IOCs
 
-To stop / start the example IOC try the following commands. Note that `ec ps -a` shows you all IOCs including stopped ones.
+To stop / start the example IOC try the following commands. Note that `dc ps -a` shows you all IOCs including stopped ones.
 
 Also note that tab completion should allow you to complete the names of your commands and services. e.g.
-`ec star <tab> ex <tab>`, should complete to `ec start example-test-01`.
+`dc star <tab> ex <tab>`, should complete to `dc start example-test-01`.
 
 ```bash
-ec ps -a
-ec stop example-test-01
-ec ps -a
-ec start example-test-01
-ec ps
+dc ps -a
+dc stop example-test-01
+dc ps -a
+dc start example-test-01
+dc ps
 ```
 
 :::{Note}
@@ -112,7 +112,7 @@ This is a Generic IOC image and all IOC Instances must be based upon one of thes
 To run a bash shell inside the IOC container:
 
 ```bash
-ec exec example-test-01 bash
+dc exec example-test-01 bash
 caget EXAMPLE:SUM
 ```
 
@@ -138,13 +138,13 @@ In the Virtual Machine supplied for testing epics-containers we do not install E
 To get the current logs for the example IOC:
 
 ```bash
-ec logs example-test-01
+dc logs example-test-01
 ```
 
 Or follow the IOC log until you hit ctrl-C:
 
 ```bash
-ec logs example-test-01 -f
+dc logs example-test-01 -f
 ```
 
 You should see the log of ibek loading and generating the IOC startup assets and then the ioc shell startup script log. Ibek is the tool that runs inside of the IOC container and generates the ioc shell script and database file by interpreting the /epics/ioc/config/ioc.yaml at launch time.
@@ -154,7 +154,7 @@ You should see the log of ibek loading and generating the IOC startup assets and
 You can stop all the services with the following command.
 
 ```bash
-ec stop
+dc stop
 ```
 
 This will stop all the currently running containers described in the `compose.yml` file.
@@ -166,7 +166,7 @@ However this will leave the resources themselves in place:
 To take down the services and remove all of their resources use the following command:
 
 ```bash
-ec down
+dc down
 ```
 
 ### Monitoring and interacting with an IOC shell
@@ -177,7 +177,7 @@ shell. In the next tutorial we will use this command to interact with
 iocShell.
 
 ```bash
-ec attach example-test-01
+dc attach example-test-01
 dbl
 # ctrl-p ctrl-q to detach
 ```

docs/tutorials/dev_container.md

@@ -23,7 +23,7 @@ This means making changes to the IOC instance folders which appear in the `servi
 To make a change like this requires:
 
 - change the IOC instance ioc.yaml or other configuration files in the services repository
-- re-launch the IOC with `ec restart <ioc-name>`
+- re-launch the IOC with `dc restart <ioc-name>`
 - that's it. No compilation required because we are only changing instance configuration here, not the IOC binary or dbd.
 
 (changes_2)=
@@ -43,7 +43,7 @@ To make a change like this requires:
 - make changes to the Generic IOC Dockerfile (which holds the build instructions for a Generic IOC - we will discuss this in {any}`generic_ioc`)
 - push the changes and tag the repo - this will build and publish a new container image using CI
 - change the IOC instance in the services repo to point at the new container image
-- redeploy the IOC with `ec restart <ioc-name>`
+- redeploy the IOC with `dc restart <ioc-name>`
 
 
 (changes_3)=
@@ -130,7 +130,7 @@ Before continuing this tutorial make sure you have not left any IOCs running fro
 ```bash
 cd t01-services
 . ./environment.sh
-ec down
+dc down
 ```
 :::
 

docs/tutorials/dev_container2.md

@@ -51,7 +51,7 @@ IMPORTANT: the commands we are about to run must be executed on the host, not in
 ```bash
 cd /workspaces/ioc-adsimdetector/compose
 . ./environment.sh
-ec up -d
+dc up -d
 ```
 
 Phoebus will be launched and attempt to load the bob file called **opi/ioc/index.bob**. The **opi** folder is a place where the author of this generic IOC could place some screens. The subfolder **ioc** is not committed to git and is where the IOC instance will place its autogenerated engineering screens. The autogenerated screens always include and index.bob which is the entry point to all other autogenerated screens.

docs/tutorials/generic_ioc.md

@@ -708,6 +708,6 @@ https://github.com/orgs/YOUR_GITHUB_ACCOUNT/packages?repo_name=ioc-lakeshore340
 
 ## EXERCISE
 
-Now you have a published Generic IOC container image for ioc-lakeshore340. See if you can add an IOC instance that uses this into your `bl01t` beamline. You should then be able to run up your IOC instance with `ec deploy-local`. You could also run a local version of the simulator and see if you can get the IOC to talk to it.
+Now you have a published Generic IOC container image for ioc-lakeshore340. See if you can add an IOC instance that uses this into your `bl01t` beamline. You should then be able to run up your IOC instance with `dc deploy-local`. You could also run a local version of the simulator and see if you can get the IOC to talk to it.
 
 

docs/tutorials/ioc_changes1.md

@@ -63,7 +63,7 @@ git tag 2024.8.2
 git push origin 2024.8.2
 ```
 
-If you like working entirely from the vscode window you can open a terminal in vscode *outside* of the devcontainer. To do so, press `Ctrl-Shift-P` and choose the commnd `Terminal: Create New Integrated Terminal (Local)`. This will open a terminal to the host. You can then run `ec` from there.
+If you like working entirely from the vscode window you can open a terminal in vscode *outside* of the devcontainer. To do so, press `Ctrl-Shift-P` and choose the commnd `Terminal: Create New Integrated Terminal (Local)`. This will open a terminal to the host. You can then run docker compose from there.
 
 ## Launching the Test Beamline
 
@@ -76,20 +76,20 @@ Make sure the ca-gateway from the previous tutorial is stopped before launching
 # IMPORTANT: do this in a terminal outside of the devcontainer
 cd ioc-adsimdetector/compose
 . ./environment.sh
-ec down
+dc down
 ```
 
-Now you can launch your test beamline and it will have picked up the new extras.db.
+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`.
 
 ```bash
 # IMPORTANT: do this in a terminal outside of the devcontainer
 cd t01-services
 . ./environment.sh
-ec up -d
-caget BL01T-EA-CAM-01:TEST
+dc up -d
+dc exec example-test-01 caget BL01T-EA-CAM-01:TEST
 
 # Now shut down the beamline again so we can continue with further developer container tutorials
-ec down
+dc down
 ```
 
 ## Raw Startup Assets

docs/tutorials/ioc_changes2.md

@@ -73,7 +73,7 @@ From *outside of the developer container* start up phoebus and the ca-gateway as
 ```bash
 cd ioc-adsimdetector/compose
 . ./environment.sh
-ec up -d
+dc up -d
 ```
 
 Phoebus should now be up and running and showing the auto generated **index.bob**, In phoebus do the following steps:

docs/tutorials/setup_workstation.md

@@ -200,14 +200,15 @@ python3 -m pip install --upgrade pip
 
 Note that each time you open a new shell you will need to activate the virtual environment again. (Or place its bin folder in your path by adding `PATH=$HOME/ec-venv/bin:$PATH` in your .bashrc).
 
-(ec)=
+(copier)=
 
 ### copier
 
-Above we set up a python virtual environment. Now we will install `copier` which is used to copy the templates for the services repositories and generic IOCs.
+Above we set up a python virtual environment. Now we will install `copier` which is used to copy the templates for the services repositories and generic IOCs. Also you could take this opportunity to install the `ec` tool that we will use later when we get to the Kubernetes tutorials.
 
 ```bash
 pip install copier
+pip install ec-cli
 ```
 
 ### Git