MacOS: adding setup and installation instructions

docs/tutorials/setup_k8s.rst

@@ -15,6 +15,8 @@ It has been tested on the following:
 Ubuntu 20.10               any modern linux distro should also work
 Raspberry Pi OS 2021-05-07 See `raspberry`
 Windows WSL2               See `wsl`
+MacOS 12.6 Monterey        See `macos`
+                           (Rancher Desktop provides K3S, kubectl and Helm so skip those installation steps below)
 ========================== ============================================
 
 Give it a try, K3S provides a good uninstaller that will clean up your system
@@ -25,6 +27,7 @@ If you prefer to investigate other implementations there are also:
   - kind https://kind.sigs.k8s.io/docs/user/quick-start/
   - microk8s https://microk8s.io/
   - minikube https://minikube.sigs.k8s.io/docs/start/
+  - Rancher Desktop https://docs.rancherdesktop.io/
 
 For k3s documentation see https://k3s.io/.
 
@@ -78,12 +81,15 @@ as is.
 Create an epics IOCs namespace and context
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-From the workstation execute the following::
+From the workstation execute the following*::
 
     kubectl create namespace epics-iocs
     kubectl config set-context epics-iocs --namespace=epics-iocs --user=default --cluster=default
     kubectl config use-context epics-iocs
 
+\* For Rancher Desktop (i.e. on MacOS) there is no "default" user and cluster. Instead the
+ready-made user and cluster is called "rancher-desktop" (so replace "default" with that)
+
 Create a service account to run the IOCs
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

docs/tutorials/useful_k8s.rst

@@ -150,4 +150,70 @@ cd to the root of the project you created in `deploy_example`, then::
 
 .. _WSL2 instructions: https://docs.microsoft.com/en-us/windows/wsl/install-win10
 .. _docker for WSL: https://docs.docker.com/docker-for-windows/wsl/
-.. _X11 Server for Windows: https://sourceforge.net/projects/vcxsrv/
+.. _X11 Server for Windows: https://sourceforge.net/projects/vcxsrv/
+
+.. _macos:
+
+Installing on MacOS
+-------------------
+
+These instructions have been developed and tested on MacOS version 12.6 Monterey. 
+
+A fundamental requirement is to have the XCode commandline tools installed. This is most easily done by
+installing the free XCode App from from the App Store.
+Since XCode is a major installation and includes far more that what is strictly required, you can install
+*just* the CLI tools with the following Terminal command::
+
+    xcode-select --install
+
+There will be a licece agreement prompt. When installation is complete, verify with ``xcode-select -p`` 
+which should return something like ``/Library/Developer/CommandLineTools``.
+
+The relevant tools including docker, K3S, Helm, and others can all be easily installed
+and maintained using the `Homebrew`_ package manager. Install ``brew`` with the following Terminal
+command::
+
+    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+
+The `Rancher Desktop`_ application is a free alternative to Docker Desktop which packages up
+docker and a kubernetes installation in one easy to install app. This also provides a
+convenient desktop dashboard where you can monitor and control your kubernetes environment.
+Rancher Desktop can be installed with ``brew``::
+
+    brew install --cask rancher
+
+After installation completes, run up the "Rancher Desktop" GUI app which has been installed
+into the ``Applications`` folder and MacOS Launchpad. When first starting up the app, you will
+be asked to select a "Container Engine" - select the "dockerd (moby)" option in order to use
+compatible docker CLI and kubectl commands from this tutorial.
+
+.. _Homebrew: https://brew.sh
+.. _Rancher Desktop: https://docs.rancherdesktop.io/
+
+Install other dependencies
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A few other dependencies are required in order to follow this tutorial. These are also best installed
+and managed by Homebrew::
+
+    brew install coreutils wget
+
+Run commands in bash
+~~~~~~~~~~~~~~~~~~~~
+
+The default shell in the Terminal app is ``zsh``. It is similar and largely compatible with ``bash``
+but there are some scripts referenced in this documentation that don't work directly in ``zsh``. 
+The recommendation for working through the rest of this tutorial/instructions is to start a Terminal
+and immidiately run ``bash`` or setup a Terminal profile that runs ``bash`` by default.
+
+A newer version of bash than the one supplied with MacOS can optionally be installed with ``brew install bash``
+
+X11 GUI applications on MacOS
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+X11 GUI applications like EDM can work on MacOS as well. The `XQuartz`_ project provides an X11 server
+for MacOS and can easily be installed with Homebrew::
+
+    brew install --cask xquartz
+
+.. _XQuartz: https://www.xquartz.org