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.

  • 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 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)

  • flux version 0.30.2 (Download flux_0.30.2_linux_amd64.tar.gz or use the official installation script: curl -s https://fluxcd.io/install.sh | sudo FLUX_VERSION=0.30.2 bash)

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

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

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

Install the requirements

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

$ pip3 install -r requirements.txt

Stackspin CLI client usage

Now you can run the Stackspin CLI as follows:

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

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

The next chapter, Create and configure a kubernetes cluster will explain setting up and/or configuring a Kubernetes cluster to install Stackspin on.