.. _installation_overview:

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

.. warning::
  -  OpenAppStack 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 OpenAppStack and ask you to `report all issues
     you encounter <https://openappstack.net/contact.html>`__.
  -  When you install OpenAppStack 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.

 .. 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
    OpenAppStack, unless specified otherwise.

Setup
=====

Common prerequisites
--------------------

Wether you want to create a kubernetes cluster first or want to install
OpenAppStack on an existing cluster, these are the common prerequisites:

- You need Python 3 with its development files, Pip and Git installed
  (``apt install python3-pip python3-dev git`` on Debian)
- 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``.

Clone the OpenAppStack git repository
-------------------------------------

On your **provisioning machine**, clone the OpenAppStack git repository
and checkout the latest release branch (currently ``v0.6``):

::

    $ git clone -b v0.7 https://open.greenhost.net/openappstack/openappstack.git
    $ cd openappstack

Create a python virtual environment
-----------------------------------

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 requirements
--------------------

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

::

    $ pip3 install -r requirements.txt

OpenAppStack CLI client usage
-----------------------------

Now you can run the OpenAppStack CLI as follows:

::

    $ python -m openappstack 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
``oas.example.org`` as the cluster name. Try it out by running

::

    $ python -m openappstack oas.example.org --help


Installation options
====================

1. If you want to create a Kubernetes cluster from scratch on a dedicated server
   or virtual machine please start with :ref:`create_kubernetes_cluster` and
   then continue with :ref:`install_oas`.
#. If you want to install Openappstack on an existing Kubernetes cluster you can
   skip the above instructions and start with :ref:`install_oas`.