add example-beamline tutorial

Author: gilesknap

docs/images/example_beamline.png

@@ -9,6 +9,7 @@ Tutorials for installation and typical usage. New users start here.
 
 tutorials/intro
 tutorials/setup_workstation
+tutorials/launch_example
 tutorials/create_beamline
 tutorials/deploy_example
 tutorials/create_ioc

docs/tutorials.md

@@ -0,0 +1,87 @@
+
+# Launch A Simulation Beamline
+
+In this tutorial we will launch a simulation beamline using docker compose. This demonstrates that the a containerised beamline is portable and that the setup instructions from the previous tutorial have been successful.
+
+:::{note}
+This tutorial has been tested with the following versions of software. If you have issues then you may need to update your software to these versions or higher.
+
+- git 2.43.5
+- One of the following
+  - docker 20.10.0
+  - podman 4.9.4 and docker-compose 2.29.2
+
+See "Start the Podman system service" in [this article](https://www.redhat.com/sysadmin/podman-docker-compose) to set up podman and docker-compose
+
+If you have a choice, a recent docker version is the preferred option.
+:::
+
+The example beamline wiil launch the following set of containers:
+- a simulation Area Detector IOC
+- a simulation Motion IOC
+- a basic IOC with a sum record
+- a ca-gateway to expose the above to the host
+- a phoebus instance to view the beamline
+
+To launch simply run the following commands:
+
+```bash
+git clone https://github.com/epics-containers/example-services
+cd example-services
+# setup some environment variables
+source ./environment.sh
+# lauch the docker compose configuration (with dc alias for docker compose)
+dc up -d
+```
+
+If all is well you should see phoebus lauch with an overview of the beamline like the following:
+
+:::{figure} ../images/example_beamline.png
+The example beamline overview screen
+:::
+
+You can now try out the following commands to interact with the beamline:
+
+```bash
+# use caget/put locally
+export EPICS_CA_ADDR_LIST=127.0.0.1
+caget BL01T-DI-CAM-01:DET:Acquire_RBV
+
+# OR if you don't have caget/put locally then use one of the containers instead:
+# execute caget from inside one of the example IOCs
+dc exec bl01t-ea-test-01 caget BL01T-DI-CAM-01:DET:Acquire_RBV
+# or get a shell inside an example IOC and use caget
+dc exec bl01t-ea-test-01 bash
+caget BL01T-DI-CAM-01:DET:Acquire_RBV
+
+# attach to logs of a service (-f follows the logs, use ctrl-c to exit)
+dc logs bl01t-di-cam-01 -f
+# stop a service
+dc stop bl01t-di-cam-01
+# restart a service
+dc start bl01t-di-cam-01
+# attach to a service stdio
+dc attach bl01t-di-cam-01
+# exec a process in a service
+dc exec bl01t-di-cam-01 bash
+# delete a service (deletes the container)
+dc down bl01t-di-cam-01
+# create and launch a single service (plus its dependencies)
+dc up bl01t-di-cam-01 -d
+# close down and delete all the containers
+# volumes are not deleted to preserve the data
+dc down
+```
+
+This tutorial is a simple introduction to validate that the setup is working. In the following tutorials you will get to create your own beamline and start adding IOCs to it.
+
+::: {important}
+Before moving on to the next tutorial always make sure to stop and delete the containers from your current example as follows:
+
+```bash
+dc down
+```
+
+If you do not do this you will get name clashes when trying the next example. If this happens - return to the previous project directory and use `dc down`.
+
+This is a deliberate choice as we can only run a single ca-gateway on a given host port at a time. For more complex setups you could share one ca-gateway between multiple compose configurations, but we have chosen to keep things simple for these tutorials.

docs/tutorials/launch_example.md

@@ -128,8 +128,9 @@ sed -i ~/.config/containers/containers.conf -e '/label=false/d' -e '/^\[containe
 Next install docker or podman as your container platform. epics-containers
 has been tested with podman 4.4.1 and higher on RedHat 8, and Docker 24.0.5 and higher on for Ubuntu 22.04 and higher.
 
-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 podman version required is 4.0 or later. Any version of docker since 20.10 will also work.
+
+Because we use docker compose which is built in to later versions of docker, we recommend using docker if you have a choice.
 
 The links below have details of how to install your choice of container platform:
 
@@ -144,7 +145,7 @@ docker compose allows you to define and run multi-container Docker applications.
 
 If you installed docker using the above instructions then docker compose is already installed. If you installed podman then you will need to install docker compose separately. We prefer to use docker-compose instead of podman-compose because it is more widely used and avoids behaviour differences between the two tools. If you are at DLS you just need to run 'module load docker-compose' to get access to docker compose with podman as the back end.
 
-Other users of podman please see these instructions [rootless podman with docker-compose](https://connect.redhat.com/hydra/prm/v1/business/companies/0ed5e6899bce415b89d82cb334da214a/linked-resources/aa9ae6ada5f04000a66472cc0fc18160/content/public/view).
+Other users of podman please see these instructions [rootless podman with docker-compose](https://www.redhat.com/sysadmin/podman-docker-compose). You need only read the section titled "Start the Podman system service" (the rest of the page validates the setup).
 
 ### Important Notes Regarding docker and podman