Merge pull request #192 from epics-containers/quickstart

add quickstart for compose

Author: gilesknap

.vscode/settings.json

@@ -14,4 +14,7 @@
             "scheme": "file"
         }
     ],
+    "workbench.colorCustomizations": {
+        "titleBar.activeBackground": "#cc69b5",
+    },
 }

docs/how-to/compose-quickstart.md

@@ -0,0 +1,43 @@
+(quickstart)=
+# Docker Compose Quickstart
+
+Here are some minimal setup instructions to get you up and running with docker-compose and a container runtime on any platform. This is a pre-requisite for most of the tutorials in this documentation.
+
+## Docker Already Installed
+
+If have one of the following then you are good to go with no further setup:
+
+- Docker Desktop on Windows WSL2
+- Docker Desktop on MacOS
+- Any Linux distribution with Docker installed
+
+For WSL2 check: Settings → Resources → WSL integration → ENABLE ... Apply and Restart
+
+(linux-installation)=
+## Linux
+
+**Debian Distros**
+
+```bash
+sudo apt install podman docker-compose-v2
+```
+
+**RPM Distros**
+
+```bash
+sudo dnf config-manager --add-repo https://download.docker.com/linux/rhel/docker-ce.repo
+sudo dnf install docker-compose-plugin
+```
+
+**Podman Integration with Docker Compose**
+
+```bash
+systemctl enable --user podman.socket --now
+export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
+```
+
+## Windows or MacOS
+
+- Install podman desktop <https://podman-desktop.io/docs/installation>
+- Follow [](linux-installation) above in a WSL2 or Mac terminal
+- For Mac, add an X11 server like XQuartz

docs/tutorials/launch_example.md

@@ -4,15 +4,9 @@
 In this tutorial we will launch a simulation beamline using docker compose. This demonstrates that a containerised beamline is portable and that the setup instructions from the previous tutorial have been successful.
 
 :::{note}
-To run this demo you need docker-compose installed (not podman-compose) plus docker or podman. See {any}`podman-compose` for setup.
-
-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 27.2.0 and docker-compose 2.29.2
-  - podman 4.9.4 and docker-compose 2.29.2
+To run this demo you need docker-compose installed (not podman-compose) plus docker or podman.
 
+See [quickstart instructions](quickstart) for how to set these up on any platform.
 :::
 
 The example beamline will launch the following set of containers:
@@ -30,6 +24,7 @@ git clone https://github.com/epics-containers/example-services
 cd example-services
 # setup some environment variables
 source ./environment.sh
+# launch the example beamline and detach the logs
 docker compose up -d
 ```
 
@@ -73,7 +68,7 @@ docker compose down
 ```
 
 :::{note}
-Note that the above commands use `EPICS_CA_ADDR_LIST` to point channel access clients at the localhost because the containers are only exposing the Channel Access Ports to the loopback adapter.
+Note that the above commands use `EPICS_CA_ADDR_LIST` to point channel access clients at the localhost because the containers are only exposing the Channel Access Ports to the loopback adapter Via a ca-gateway.
 
 This means that the PVs are only accessible from the host running the containers. Which makes it ideal for tutorials.
 :::

docs/tutorials/setup_workstation.md

@@ -43,19 +43,20 @@ See these how-to pages for more information:
 
 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.
 
-Whatever your platform, if you can install virtualbox, then you can work using the applicance we provide.
+**UPDATE**: See the new [quickstart instructions](quickstart) for setting up the container runtime on any platform, therefore not requiring the virtualbox appliance unless that is your preferred option.
+
+Whatever your platform, if you can install virtualbox, then you can work using the appliance we provide.
 
 In all cases you will need an internet connection to download the software and the container images. (if you are at DLS you do not need access to DLS network resources, only the internet).
 
 | Platform | Requirements |
 |----------|--------------|
 | Any Linux | admin rights only: go to {ref}`installation-steps` |
-| Windows | Virtualbox: go to {ref}`appliance` |
-| Mac x86 | Virtualbox: go to {ref}`appliance` |
-| Mac M1 | ?? |
+| Windows | Virtualbox: go to {ref}`appliance`  or WSL2 and Podman Desktop |
+| Mac x86 | Virtualbox: go to {ref}`appliance` or Podman Desktop |
+| Mac M1 | Virtualbox: go to {ref}`appliance` or Podman Desktop |
 | DLS RHEL 8 | go to {ref}`installation-steps` |
 
-
 (appliance)=
 ## VirtualBox Appliance