From c55030850880d1a78ce851e0b025618bbb8db853 Mon Sep 17 00:00:00 2001 From: Ulrik Kofoed Pedersen Date: Tue, 11 Oct 2022 13:11:35 +0100 Subject: [PATCH 1/2] MacOS: adding setup and installation instructions --- docs/tutorials/setup_k8s.rst | 8 ++++- docs/tutorials/useful_k8s.rst | 68 ++++++++++++++++++++++++++++++++++- 2 files changed, 74 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/setup_k8s.rst b/docs/tutorials/setup_k8s.rst index a36ff779..1d7bcecc 100644 --- a/docs/tutorials/setup_k8s.rst +++ b/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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/tutorials/useful_k8s.rst b/docs/tutorials/useful_k8s.rst index 0b7e7296..82e9af90 100644 --- a/docs/tutorials/useful_k8s.rst +++ b/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/ \ No newline at end of file +.. _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 `just` +install 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 From 2e2f5c737c6dd0aa8b74e20b31d66d50aaedf41d Mon Sep 17 00:00:00 2001 From: Ulrik Kofoed Pedersen Date: Tue, 11 Oct 2022 13:17:29 +0100 Subject: [PATCH 2/2] macos: fix sphinx build error --- docs/tutorials/useful_k8s.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/tutorials/useful_k8s.rst b/docs/tutorials/useful_k8s.rst index 82e9af90..edb4b2eb 100644 --- a/docs/tutorials/useful_k8s.rst +++ b/docs/tutorials/useful_k8s.rst @@ -161,8 +161,8 @@ 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 `just` -install the CLI tools with the following Terminal command:: +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