Merge branch '1161-installation-try-out' into 'main'

Resolve "Installation try out"

See merge request stackspin/stackspin!860

docs/installation/install_cli.rst

@@ -19,27 +19,30 @@ This page will guide you through the installation of the "Stackspin CLI". The
 CLI can be used to set up Stackspin on a different machine that is connected to
 the internet. It also functions as a starting point for running tests.
 
-Common prerequisites
---------------------
+Requirements
+------------
+
+You should have a trusted machine to run the installer on, this can be your
+laptop or pc. In this guide, we call it the *provisioning machine*.  All
+commands in these installation instructions need to be run the provisioning
+machine, except when a command starts with ``cluster$``
 
-Whether you want to create a Kubernetes cluster first or want to install
-Stackspin on an existing cluster, these are the common prerequisites:
+Before you can start, you need this software installed **on your provisioning
+machine**:
 
 - You need Python 3 with its development files, Pip and Git installed
-  (``apt install python3-pip python3-dev git`` on Debian)
+  (``apt install python3-pip python3-dev git`` on Debian/Ubuntu)
 - We recommend using a `python
   virtualenv <https://docs.python.org/3/tutorial/venv.html>`__ to make
   sure we do not change any of your other projects. Install virtualenv
   by running ``pip3 install --user venv`` or ``apt install python3-venv``.
 - You need a recent version of Pip. If you run into problems during ``pip
   install`` you might need to run ``pip install --upgrade pip``.
+- ``kubectl`` (`installation instructions
+  <https://kubernetes.io/docs/tasks/tools/#kubectl>`__)
+- ``flux version 0.25.3`` (`Download flux_0.25.3_linux_amd64.tar.gz
+  <https://github.com/fluxcd/flux2/releases/download/v0.25.3/flux_0.25.3_linux_amd64.tar.gz>`_)
 
-.. note::
-   You should also have a trusted machine to run the installer on, i.e. your
-   laptop. We call this the ``provisioning machine``.
-   All commands in these installation instructions need to be
-   run this provisioning machine that is *not* the server that will run
-   Stackspin, unless specified otherwise.
 
 Clone the Stackspin git repository
 -------------------------------------

docs/installation/install_stackspin.rst

@@ -16,14 +16,6 @@ Flux will run inside your Stackspin cluster to install and upgrade applications.
 It needs to be configured once, using the ``flux`` command line tool and scripts
 provided by us in the Stackspin repository.
 
-.. _flux_prerequisites:
-
-Prerequisites
--------------
-
-- ``kubectl`` (`installation instructions <https://kubernetes.io/docs/tasks/tools/#kubectl>`__)
-- ``flux version 0.25.3`` (`Download flux_0.25.3_linux_amd64.tar.gz <https://github.com/fluxcd/flux2/releases/download/v0.25.3/flux_0.25.3_linux_amd64.tar.gz>`_)
-
 Configuration
 -------------
 
@@ -119,20 +111,41 @@ Before you can start, you need to execute a few commands from the installation
 directory **on your provisioning machine**. Don't forget to replace
 ``stackspin.example.org`` with your domain.
 
+We will use this variable in the following commands, set it to your cluster
+directory.
+
 .. code:: bash
 
-   export CLUSTER_DIR=clusters/stackspin.example.org
+   export CLUSTER_DIR=$PWD/clusters/stackspin.example.org
+
+Make sure your ``virtualenv`` is activated.
+
+.. code:: bash
+
+   . venv/bin/activate
+
+Copy the installation kustomization to your cluster directory.
+
+.. code:: bash
 
-   # Copy the installation kustomization to your cluster directory
    cp install/kustomization.yaml $CLUSTER_DIR/
 
-   # Tell kubectl to use your cluster's kube_config
+Tell kubectl to use your cluster's kube_config.
+
+.. code:: bash
+
    export KUBECONFIG=$CLUSTER_DIR/kube_config_cluster.yml
 
-   # Ensure flux-system namespace is created
+Ensure flux-system namespace is created.
+
+.. code:: bash
+
    kubectl get namespace flux-system 2>/dev/null || kubectl create namespace flux-system
 
-   # This inserts the configuration from .flux.env into your cluster as a "secret"
+This inserts the configuration from .flux.env into your cluster as a "secret".
+
+.. code:: bash
+
    kubectl apply -k $CLUSTER_DIR
 
 After you have executed that code, your terminal should show: