update setup workstation and related pages

Author: gilesknap

docs/how-to/own_tools.md

@@ -17,6 +17,6 @@ epics-containers has been tested with
 - vscode
 - Github Codespaces
 
-If you prefer console based editors like vim or emacs, then you will get the best results by launching the development containers defined in the epics-containers using the devcontainer CLI as described here <https://containers.dev/supporting#devcontainer-cli>.
+If you prefer console based editors like neovim or emacs, then you will get the best results by launching the development containers defined in the epics-containers using the devcontainer CLI as described here <https://containers.dev/supporting#devcontainer-cli>.
 
 In addition you could install your editor inside the developer container by adding an apt-install command into the `epics-containers` user personalization file. See [details here](https://github.com/epics-containers/epics-containers.github.io/blob/3a87e808e1c7983430a30c5a4dcd0d0661895d60/.devcontainer/postCreateCommand#L23-L27)

docs/reference/cli.md

@@ -2,18 +2,18 @@
 
 # Command Line Interface for IOC Management
 
-The python project {any}`edge-containers-cli` is installed as part of the Python section of the initial tutorial {any}`../tutorials/setup_workstation`. It provides a command line function `ec` with support for:
+The python project {any}`edge-containers-cli` is installed as part of the Python section of the initial tutorial {any}`../tutorials/setup_workstation`. It provides a command line function `ec` with support for  managing and monitoring IOC instances.
 
-- deploying, managing and monitoring IOC and service instances
+This tool is only required if you are deploying to Kubernetes. Docker compose provides a very similar set of commands for local deployment. Also note that `ec` supports both ArgoCD and pure Helm deployments. The tutorials will use ArgoCD, for information on Helm based deployments see {any}`helm` .
 
 The CLI is just a thin wrapper around the underlying tools that do the real work:
 
 ```{eval-rst}
 
 :kubectl: the command line interface to the Kubernetes APIs
 :helm: the command line interface to the Kubernetes Helm package manager
-:podman/docker: CLIs for container engines
 :git: the git version control system client
+: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`.

docs/reference/docker.md

@@ -3,6 +3,12 @@ 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.
+
+Therefore:
+- 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.
 
 There are a few things to know if you are using `docker` in your developer containers:
@@ -12,7 +18,7 @@ There are a few things to know if you are using `docker` in your developer conta
     ```bash
     git config --global --add safe.directory <Git folder>
     ```
-1. you can use `sudo` if you are having permissions issues. In particular the following will reset permissions on a folder:
+1. you can use `sudo` if you are having permissions issues. In particular the following will reset permissions on all of the epics files inside the container filesystem:
     ```bash
-    sudo chown -r vscode <folder>
+    sudo chown -r vscode /epics
     ```

docs/reference/glossary.md

@@ -16,7 +16,7 @@ epics-containers supports two kinds of services repositories:
 
 A Python command line tool for the developer that runs *outside* of containers. It provides simple features for and monitoring and managing and IOC instances within a [](services-repo).
 
-So named 'edge' containers because these services all run close to the hardware. Uses the command line entry point `ec`.
+So named 'edge' containers because these services all run close to the hardware. Uses the command line entry point `ec`. See {any}`cli` for more details.
 
 (ibek)=
 ## ibek

docs/reference/helm.md

@@ -0,0 +1,15 @@
+(helm)=
+# Pure Helm Deployments
+
+At DLS we use helm charts in our services repos to describe our IOC instances. However we use ArgoCD continuous deployment to deploy them. ArgoCD is a Kubernetes native tool that knows how to keep a set of Helm charts in a git repository in sync with a set of Kubernetes resources.
+
+You are not required to use ArgoCD, you can use Helm directly if you prefer. This page discusses how to use the command line tool `ec` to deploy and manage IOC instances using Helm directly. `ec` adds some useful version management features to the workflow that to some extent replicates ArgoCD's ability to track versions.
+
+### TODO this is WIP
+
+If you set the `EC_CLI_BACKEND` environment variable to `K8S` then `ec` will use Helm directly to deploy and manage IOC instances. You can get a feel for the commands available with `ec --help`.
+
+```bash
+export EC_CLI_BACKEND=K8S
+ec --help
+```

docs/tutorials/setup_workstation.md

@@ -24,16 +24,18 @@ See these how-to pages for more information:
 
 ## Platform Support
 
-epics-containers can use Linux, Windows or MacOS as the host operating system for
-the developer workstation.
+The containers used in the tutorials are x86_64 Linux. The best way to experience the tutorials is to use an Intel Linux workstation or laptop. arm64 container images have been tested but are not yet widely used in the available images.
 
-If you are using Windows then you must first
-install WSL2 and then work within the Linux subsystem. see
-[WSL2 installation instructions].
-Ubuntu is recommended as the Linux distribution for WSL2.
+If you are using a Mac or Windows then the simplest approach is to use the Linux Virtual Machine with pre-installed software that we provide. First install [VirtualBox](https://www.virtualbox.org/wiki/Downloads) and then download the [Virtual Machine](https://drive.google.com/file/d/1ejJjiVDcODkiJsTShkCclQyod02f4Tex/view?usp=drive_link) TODO: currently hosted on giles Google Drive - find a better hosting solution. The downloaded file is an OVA file which can be imported into VirtualBox using ``File->Import Appliance ...``. During the import process you will be able to modify the resources that the VM uses, the defaults are recommended, but you may decrease them if your host machine has limited resources.
+
+If you are using Windows you could instead install WSL2 and then work within the Linux subsystem. see [WSL2 installation instructions]. Ubuntu is recommended as the Linux distribution for WSL2. This has not been tested with the tutorials recently so the VM above is the preferred option.
 
 ## Installation Steps
 
+If you are using the Virtual Machine, then you can skip to "Setup virtual environment", because the first three requirements are already installed.
+
+If you are using your own Linux machine then follow all the steps below to install the required software.
+
 ### Setup VSCode
 
 :::{Note}
@@ -61,7 +63,7 @@ devcontainer in the next tutorial.
 ### Setup Docker or Podman
 
 :::{Note}
-**DLS Users**: RHEL 8 Workstations at DLS have podman 4.6.1 installed by default.
+**DLS Users**: RHEL 8 Workstations at DLS have podman 4.9.4 installed by default.
 RHEL 7 Workstations are not supported.
 :::
 
@@ -70,21 +72,15 @@ has been tested with podman 4.4.1 and higher on RedHat 8, and Docker 24.0.5 and
 
 If you are using docker, simply replace `podman` with `docker` in the commands listed in these tutorials. `docker` users should also take a look at this page: [](../reference/docker.md)
 
-The podman version required is 4.0 or later. Any version of docker since 20.10
-will also work. Pick the tool that has the most recent version for your platform.
-RedHat 8 and above have recent podman versions. Debian platforms don't yet
-have recent podman versions available. If you have a choice then podman is
-preferred because it does not require root access and it is the tool with
-which epics-containers has had the most testing.
+The podman version required is 4.0 or later. Any version of docker since 20.10 will also work. Pick the tool that has the most recent version for your platform. RedHat 8 and above have recent podman versions. Older Debian platforms don't yet
+have recent podman versions available. If you have a choice then podman is slightly preferred because it does not require root access and it is the tool with which epics-containers has had the most testing. However, docker is the most widely used container platform and is also well supported.
 
 The links below have details of how to install your choice of container platform:
 
 - [Install docker]
 - [Install podman]
 
-The docker install page encourages you to install Docker Desktop. This is a paid
-for product and is not required for this tutorial. You can install the free linux
-CLI tools by clicking on the appropriate linux distribution link.
+The docker install page encourages you to install Docker Desktop. This is a paid for product and is not required for this tutorial. You can install the free linux CLI tools by clicking on the appropriate linux distribution link.
 
 (python-setup)=
 
@@ -94,16 +90,15 @@ CLI tools by clicking on the appropriate linux distribution link.
 **DLS Users**: for this step just use `module load python/3.11`
 :::
 
-Go ahead and install Python 3.10 or later. 3.11 is recommended as this is the
-highest version that epics-containers has been tested with.
+Go ahead and install Python 3.11 or later.
 
 There are instructions for installing Python on all platforms here:
 <https://docs.python-guide.org/starting/installation/>
 
 ### Setup virtual environment
 
 
-Once you have python set up a virtual environment for your epics-containers
+Once you have python, set up a virtual environment for your epics-containers
 work. In the examples we will use `$HOME/ec-venv` as the virtual environment
 but you can choose any folder.
 
@@ -117,34 +112,28 @@ source $HOME/ec-venv/bin/activate
 python -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 permanently).
+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 it in your .bashrc).
 
 (ec)=
 
 ### edge-containers-cli
 
-Above we set up a python virtual environment. Now we will install
-the {any}`edge-containers-cli` python tool into that environment.
+Above we set up a python virtual environment. Now we will install the {any}`edge-containers-cli` python tool into that environment. This tool is used to manage the IOC instances in Kubernetes and is only required for the later tutorials.
 
 ```bash
 pip install edge-containers-cli
 ```
 
-This is the developer's 'outside of the container' helper tool. The command
-line entry point is `ec`. We will be using many `ec` command line
-functions in the next tutorial.
-
 See {any}`CLI` for more details.
 
 :::{note}
-DLS Users: `ec` is already installed for you on `dls_sw` just do the
-following to make sure it is always available:
+DLS Users: `ec` is already installed for you on `dls_sw` just do the following to make sure it is always available:
 
 ```bash
-# use the ec version from dls_sw/work/python3
+# use the ec version from /dls_sw/work/python3
 mkdir -p $HOME/.local/bin
 ln -fs /dls_sw/work/python3/ec-venv/bin/ec $HOME/.local/bin/ec
+# log out and back in again to make sure the new path is available
 ```
 :::
 
@@ -161,24 +150,9 @@ You don't need Kubernetes yet.
 The following tutorials will take you through creating, deploying and
 debugging IOC instances, generic IOCs and support modules.
 
-For simplicity we don't encourage using Kubernetes at this stage. Instead we
-will deploy containers to the local workstation's docker or podman instance.
-
-However, everything in these tutorials would also work with Kubernetes. If you
-are particularly interested in Kubernetes then you can jump to
-{any}`setup-kubernetes` and follow the instructions there. Then come back to this
-point and continue with the tutorials. If you do this just be aware that
-we use the beamline name `bl01t` for local deployment examples and
-`bl46p` for Kubernetes examples so you will need to substitute the
-appropriate beamline name for your environment. All the local deployment
-examples should also deploy to a Kubernetes cluster.
-
-If you are planning not to use Kubernetes at all then now might be
-a good time to install an alternative container management platform such
-as [Portainer](https://www.portainer.io/). Such tools will help you
-visualise and manage your local containers. They are not required and you
-could just manage everything from epics-containers command line interface
-if you prefer.
+For simplicity we don't encourage using Kubernetes at this stage. Instead we will deploy containers to the local workstation's docker or podman instance.
+
+If you are planning not to use Kubernetes at all then now might be a good time to install an alternative container management platform such as [Portainer](https://www.portainer.io/). Such tools will help you visualise and manage your containers across a number of servers. These are not required and you could just manage everything from the docker compose command line if you prefer.
 
 [download visual studio code]: https://code.visualstudio.com/download
 [how to use wsl2 and visual studio code]: https://code.visualstudio.com/blogs/2019/09/03/wsl2