.. _installation_overview:

=====================
Installation overview
=====================

.. warning::
   - Stackspin is still under heavy development and is not ready for production use!
     We anticipate major changes
     and do not guarantee a data-preserving upgrade path from current installations.
     However, we encourage you to try Stackspin
     and ask you to `report all issues you encounter <https://stackspin.net/contact.html>`__.
   - When you install Stackspin on a server,
     the installation process will make some substantial changes to the server's configuration,
     so please do not use a server that functions as anything other than a testing ground.

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.

Preparing the provisioning machine
----------------------------------

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$``

The following software setup is required **on your provisioning machine**:

- You need Python 3 with its development files, Pip and Git installed.
  On Debian/Ubuntu: ``apt install python3-pip python3-dev git``
- We recommend using a `python virtualenv <https://docs.python.org/3/tutorial/venv.html>`__
  to make sure Stackspin does not change any of your other python 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.31.3 (`Download flux_0.31.3_linux_amd64.tar.gz
  <https://github.com/fluxcd/flux2/releases/download/v0.31.3/flux_0.31.3_linux_amd64.tar.gz>`_
  or use the official installation script:
  ``curl -s https://fluxcd.io/install.sh | sudo FLUX_VERSION=0.31.3 bash``)

Then you can clone the Stackspin git repository
and checkout the latest release branch (currently ``v0.8``):

.. code:: console

   $ git clone -b v0.8 https://open.greenhost.net/stackspin/stackspin.git
   $ cd stackspin

Apart from the previously installed software,
Stackspin will only modify in the ``clusters`` subdirectory of the repository.
So multiple provisioning machines can administer the same instance
so long as that subdirectory is synced between them.

Create a python virtual environment (Optional)
----------------------------------------------

Create a python virtual environment called "env" that uses python 3.
This makes sure we do not change any of your other python projects. The
second command "activates" the virtualenv.

.. note::

  Activating the virtualenv means you will use that environment to install
  and run python programs instead of your global environment.
  If you close your terminal or open a new one,
  you need to activate the virtualenv again.

.. code:: console

   $ python3 -m venv env
   $ . env/bin/activate

Install the requirements
------------------------

Next, install the Stackspin CLI client by running the following
commands:

.. code:: console

   $ pip3 install -r requirements.txt

Stackspin CLI client usage
-----------------------------

Now you can run the Stackspin CLI as follows:

.. code:: console

   $ python -m stackspin CLUSTER_NAME <command>

The CLI *always* needs a ``CLUSTER_NAME`` argument.
Even for getting subcommand help messages.
Be sure to run this command in the root directory of the git repository.
In this tutorial, we're using ``stackspin.example.org`` as the cluster name.
Try it out by running:

.. code:: console

   $ python -m stackspin stackspin.example.org --help

The next chapter, :ref:`create_kubernetes_cluster`
will explain setting up and/or configuring a Kubernetes cluster
to install Stackspin on.