switch to docker in instructions

Author: gilesknap

docs/explanations/introduction.md

@@ -23,7 +23,7 @@ and their APIs such that container images can be interchanged between
 different frameworks.
 
 Thus, in this project we develop, build and test our container images
-using docker or podman but the images can be run under Kubernetes' own
+using docker or docker but the images can be run under Kubernetes' own
 container runtime.
 
 This article does a good job of explaining the relationship between docker /
@@ -94,9 +94,9 @@ implementing these features:
 - debug an IOC by starting a bash shell inside it's container
 
 ### Kubernetes Alternatives
-If you do not wish to maintain a Kubernetes cluster then you could simply install IOCs directly into the local docker or podman instance on each server. Instead of using Kubernetes and Helm, you can use docker compose to manage such IOC instances. But this is just an example, epics-containers is intended to be modular so that you can make use of any parts of it without adopting the whole framework as used at DLS.
+If you do not wish to maintain a Kubernetes cluster then you could simply install IOCs directly into the local docker or docker instance on each server. Instead of using Kubernetes and Helm, you can use docker compose to manage such IOC instances. But this is just an example, epics-containers is intended to be modular so that you can make use of any parts of it without adopting the whole framework as used at DLS.
 
-We provide a template services project that uses docker compose with docker or podman as the runtime engine. Docker compose allows us to describe a set of IOCs and other services for each beamline server, similar to the way Helm does. Where a beamline has multiple servers, the distribution of IOCs across those servers could be managed by maintaining a separate docker-compose file for each server in the root of the services repository.
+We provide a template services project that uses docker compose with docker or docker as the runtime engine. Docker compose allows us to describe a set of IOCs and other services for each beamline server, similar to the way Helm does. Where a beamline has multiple servers, the distribution of IOCs across those servers could be managed by maintaining a separate docker-compose file for each server in the root of the services repository.
 
 If you choose to use this approach then you may find it useful to have another tool for viewing and managing the set of containers you have deployed across your beamline servers. There are various solutions for this, one that has been tested with **epics-containers** is Portainer <https://www.portainer.io/>. Portainer is a paid for product that provides excellent visibility and control of your containers through a web interface. Such a tool could allow you to centrally manage the containers on all your servers.
 

docs/how-to/debug.md

@@ -26,7 +26,7 @@ Add the phrase 'deliberate_error' to the top of the `ioc.yaml` file. Then try to
 ec -v deploy-local services/bl01t-ea-test-02
 ```
 
-You should see something like this (for docker users - podman users will see something similar):
+You should see something like this (for docker users - docker users will see something similar):
 
 <pre>$ ec -v deploy-local services/bl01t-ea-test-02
 <font color="#5F8787">docker --version</font>

docs/images/bl01t-actions.png

@@ -16,7 +16,7 @@ The CLI is just a thin wrapper around the underlying tools that do the real work
 :argocd: the ArgoCD command line interface
 ```
 
-`ec` is useful because it saves typing and provides a consistent interface when working on multiple {any}`services-repo` s. This is because it uses the environment setup by the beamline repo's `environment.sh` script. See {any}`environment`.
+`ec` is useful because it saves typing and provides a consistent interface when working on multiple {any}`services-repo`s. This is because it uses the environment setup by the beamline repo's `environment.sh` script. See {any}`environment`.
 
 To see the available commands, run `ec --help`.
 

docs/reference/cli.md

@@ -3,11 +3,11 @@ Working with Docker
 
 DLS is a `podman` shop and therefore more testing is done with `podman` than `docker` as the container CLI used with developer containers. `podman` works extremely well with developer containers, but `docker` needs a little more work sometimes.
 
-The primary difference is that `podman` does not require root access and `docker` does. When inside a podman container you appear to be root but you are running as your own host user id. When you write to any host mounted files you will be doing so with your host user permissions. In a docker container any host files written will be owned by the user id that the container is running as.
+The primary difference is that `podman` does not require root access and `docker` does. When inside a `podman` container you appear to be root but you are running as your own host user id. When you write to any host mounted files you will be doing so with your host user permissions. In a docker container any host files written will be owned by the user id that the container is running as.
 
 Therefore:
-- It is better not to run docker containers as root.
-- It is easiest to run podman containers as root for simplicity.
+- It is better not to run `docker` containers as root.
+- It is easiest to run `podman` containers as root for simplicity.
 
 We do fully support `docker`, please report any issues you find.
 

docs/reference/docker.md

@@ -39,7 +39,7 @@ be adjusted to suit your domain. The variables are as follows:
   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_K8S_NAMESPACE=local` and this will deploy IOC Instances to the local server's
-  docker or podman instance.
+  docker or docker instance.
 
 - **EC_SERVICES_REPO**: this is a link back to the repository that defines this
   domain. For example the bl38p reference beamline repository uses

docs/reference/environment.md

@@ -364,12 +364,12 @@ 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
-your IOC Instance config folder like this (replace podman with
+your IOC Instance config folder like this (replace docker with
 docker if that is what you are using):
 
 ```bash
-podman cp bl01t-ea-test-02:/epics/runtime/st.cmd services/bl01t-ea-test-02/config
-podman cp bl01t-ea-test-02:/epics/runtime/ioc.subst services/bl01t-ea-test-02/config/ioc.subst
+docker cp bl01t-ea-test-02:/epics/runtime/st.cmd services/bl01t-ea-test-02/config
+docker 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
 ```
@@ -388,7 +388,7 @@ ec deploy-local services/bl01t-ea-test-02
 ```
 
 :::{note}
-We used some raw podman / docker commands in the above script. If you
+We used some raw docker / docker commands in the above script. If you
 want to know what commands `ec` is running under the hood then you can
 use the `-v` option to see them.
 

docs/tutorials/create_ioc.md

@@ -72,7 +72,7 @@ STEP 15/19: RUN StreamDevice/install.sh 2.8.24
 ```
 
 - copy the hash of the step you want to debug e.g. `631291db1751` in this case
-- podman run -it --entrypoint /bin/bash 631291db1751 # (the hash you copied)
+- docker run -it --entrypoint /bin/bash 631291db1751 # (the hash you copied)
 
 Now we have a prompt inside the part-built container and can retry the failed
 command.

docs/tutorials/debug_generic_ioc.md

@@ -2,15 +2,9 @@
 
 ## Introduction
 
-This tutorial will show you how to deploy and manage the example IOC Instance
-that came with the template beamline repository.
-You will need to have your own `bl01t` beamline repository
-from the previous tutorial.
+This tutorial will show you how to deploy and manage the example IOC Instance that came with the template beamline repository. You will need to have your own `t01-services` beamline repository from the previous tutorial.
 
-For these early tutorials we are not using Kubernetes and instead are deploying
-IOCs to the local docker or podman instance. So for these tutorials we
-shall pretend that your workstation is one of the IOC servers on the fictitious
-beamline `BL01T`.
+For these early tutorials we are not using Kubernetes and instead are deploying IOCs to the local docker or docker instance. These kind of deployments are ideal for testing and development on a developer workstation. They could also potentially be used for production deployments to beamline servers where Kubernetes is not available.
 
 ## Continuous Integration
 
@@ -43,7 +37,19 @@ For the moment just check that your CI passed and if not review that you
 have followed the instructions in the previous tutorial correctly.
 
 (setup-beamline-bl01t)=
-## Set up Environment for BL01T Beamline
+## Set up Environment for the t01 Beamline
+
+It is much easier to investigate the commands available to you with command line completion enabled. You need only do the following steps once to permanently enable this feature.
+
+```bash
+# these steps will make cli completion work for bash
+mkdir -p ~/.local/share/bash-completion/completions
+docker completion bash > ~/.local/share/bash-completion/completions/docker
+
+# these steps will make cli completion work for zsh
+mkdir -p ~/.oh-my-zsh/completions
+docker completion zsh > ~/.oh-my-zsh/completions/_docker
+```
 
 The standard way to set up your environment for any ec services repository is to get the environment.sh script from the domain repository and source it.
 
@@ -53,30 +59,9 @@ First make sure you have the local binaries folder in your path by adding
 the following to the end of your `$HOME/.bash_profile` file:
 
 ```bash
-export PATH="$PATH:~/.local/bin"
+source ./environment.sh
 ```
 
-Then follow these steps (make sure you insert your GitHub account name
-where indicated):
-
-```bash
-# make sure we have the path setup from the bash_profile
-source ~/.bash_profile
-
-mkdir -p ~/.local/bin
-# make a copy of the environment.sh script named after the beamline
-cp environment.sh ~/.local/bin/bl01t
-source bl01t
-```
-
-Once you have done this and logged out and back in again to pick up your new
-profile you should be able to enable the `bl01t` environment as follows:
-
-```bash
-# first make sure you have loaded your virtual environment for the ec tool
-source $HOME/ec-venv/bin/activate # DLS users don't need this step
-source bl01t
-```
 
 (deploy-example-instance)=
 ## Deploy the Example IOC Instance

docs/tutorials/deploy_example.md

@@ -107,7 +107,7 @@ DLS Users and Redhat Users:
 
 There is a
 [bug in VSCode devcontainers extension](https://github.com/microsoft/vscode-remote-release/issues/8557)
-at the time of writing that makes it incompatible with podman and an SELinux
+at the time of writing that makes it incompatible with docker and an SELinux
 enabled /tmp directory. This will affect most Redhat users and you will see an
 error regarding permissions on the /tmp folder when VSCode is building your
 devcontainer.
@@ -270,7 +270,7 @@ 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 tutorials. This error should only
-be seen on first launch. podman users will have no such problem because they
+be seen on first launch. docker users will have no such problem because they
 will be root inside the container and root built the container.
 
 To mitigate this problem you can tell vscode not to look for git repos in subfolders, see [](scm_settings).