installation_instructions.md

# OpenAppStack installation instructions

This document describes how you can install OpenAppStack on a VPS. The
installation process wil set up a "Kubernetes cluster" which runs several open
source applications. More information about the applications can be found on the
[OpenAppStack website](https://openappstack.net/).

This document describes how you can set up a "single-node" OpenAppStack cluster.
This means everything runs on the same VPS.  Support for "multi-node" clusters
(a Kubernetes cluster on more than one VPS) will come in the future.

> **NOTE:** All commands in these installation instructions need to be run on a
> trusted provisioning machine (i.e., your laptop) that is *not* the VPS that
> will run OpenAppStack. The installation process will generate some secrets
> that will be saved to this machine.

If you encounter any difficulties while following these instructions, please
[open an issue following our contact
guide][https://openappstack.net/contact.html).

## Warnings

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

## Prerequisites

* During these instructions, you are asked to make a VPS, or have a bare metal
  server ready. The server should meet these requirements:
  * Current Debian stable "buster"
  * A public IP address
  * The ability to create DNS records for this IP
  * 8GB of RAM
  * At least 25GB of disk space for installation, plus more for application
    data. We recommend starting with 30GB.
  * Root ssh access
  * `python3-pip` installed. On a debian based system:

    `apt install python3-pip`

* A trusted machine to run the installer on (we call this the `provisioning
  machine`). All the commands listed in these instructions should be run on the
  provisioning machine, unless specified otherwise.
  * You need Python 3 and Git installed (`apt install python3 git`)
  * 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`
  * `ssh-agent` to give you access to your VPS

## Getting the installation script

On your **provisioning machine**, clone the OpenAppStack git repository and
checkout the latest tagged version (currently `0.3.0`):

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

> **NOTE:** Git will display a warning after you use the `git` command
> saying that you are in a *detached HEAD* state. This is perfectly normal
> and you can proceed without any further actions.


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

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

    $ pip3 install -r requirements-stable.txt

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 `my-cluster` as the cluster name. Try
it out by running

    $ python -m openappstack my-cluster --help

## Install OpenAppStack

Setting up OpenAppStack happens in three steps:

1. **Set up cluster**

   Create configuration files, and optionally create VPS

2. **Install OpenAppStack**

   Install Kubernetes and all the other software that comes with OpenAppStack.
   See [Usage](#usage) for more information on which applications are installed.

3. **Validate setup**

   This runs a test in the browser to validate that the installation was
   successful.

### Step 1: Set up cluster

To set up your cluster, use the `create` subcommand of the OpenAppStack CLI.
First, choose a name (we chose `my-cluster`) for your cluster. Then run the following command to get
information about the `create` subcommand:

    $ python -m openappstack my-cluster create --help

There are two options to create a cluster, [using the Greenhost
API](#option-1--setup-with-the-greenhost-api) or [using any other
machine](#option-2--setup-any-vps-or-bare-metal-server). Choose one of these
options, and skip to the "[Installation](#installation)" subchapter afterwards.

#### Option A: Setup with the Greenhost API

- Before you can start, you need to have an API key with Customer rights.
  1. In the Cosmos service centre, click your webmaster account name on the top
     right corner
  2. Go to "User settings"
  3. Click "API keys"
  4. Click "New API key"
  5. Click "Generate new key"
  6. Give the key "Customer", "CloudCustomer" or "API" access rights. You will
     need "Customer" rights if you want to automatically generate DNS rules. If
     you do not have this right, you have to [manually set the right DNS
     rules](http://docs.openappstack.net/en/latest/installation_instructions.html#dns-entries)
     later.
  7. Copy the generated key and run export it to this variable in a terminal:

     ```
     $ export COSMOS_API_TOKEN=<paste your API key here>
     ```
  8. In *the same terminal*, you can now use the `create` subcommand
1. Based on an already existing [Greenhost](https://greenhost.net) VPS, using
   the `--droplet-id` argument.

   Find the ID of your VPS either in the Greenhost Cosmos interface
   (it is the numeric part of the URL in the "Manage VPS" screen).

2. By creating a new VPS through the API, using the `--create-droplet`
   argument
   - Make sure to also provide the `--create-hostname` and `--ssh-key-id` arguments.

     You can find your SSH key ID by going to VPS Cloud -> SSH keys and
     checking the link under "Show key". The numerical part is your SSH key
     ID.

     *Note: You can also use the API to list ssh keys and find it there. Read
     the [Greenhost API
     documentation](https://service.greenhost.net/cloud/ApiDoc#/default) for
     more information*
- In both cases you need to provide the `DOMAIN_NAME` positional argument.

  If you use a subdomain (e.g. `oas.yourdomain.com`), use the `--subdomain`
  command as follows:

  ```
  $ python -m openappstack my-cluster create --subdomain oas example.org
  ```

- Here is an example of a complete creation command:

  ```
  $ python -m openappstack my-cluster create --create-droplet --create-hostname oas.example.org --ssh-key-id 112 --create-domain-records --subdomain oas example.org
  ```

  > **NOTE:** You can use the `--acme-staging` argument for testing purposes
  > This ensures you use "staging" certificates from Let's Encrypt, to reduce
  > the stress on their servers. However, ONLYOFFICE integration requires valid
  > (live) certificates to work.

  This will create configuration files for a cluster named `my-cluster`. It
  will also create a Greenhost VPS with the hostname `oas.example.org` and on
  which you can log in with SSH key with ID `112`.

  These DNS records will also be created by Greenhost (assuming you own the
  domain `example.org` at Greenhost):

  - An `A` record `oas.example.org` pointing to the VPSs IP address
  - A `CNAME` record `*.oas.example.org` pointing to `oas.example.org`.

#### Option B: Setup any VPS or bare metal server

Skip this step and continue to [Installation](#installation) if you already set
up a Greenhost VPS.

If you want to install OpenAppStack on a non-Greenhost VPS, we assume you
already have a machine with a world-facing IP address. Make sure that your VPS
meets our [prerequisites](#prerequisites).  You'll need its *hostname* and its
*IP address*.

> **NOTE:** You can use the `--acme-staging` argument for testing purposes. If
> you are automating this, please use this to ensure you use "staging"
> certificates from Let's Encrypt, to reduce the stress on their servers.
> However, ONLYOFFICE and single sign-on integration require valid (live)
> certificates to work properly so please don't use this option by default. 

If you want your cluster to be reachable under the fully qualified domain name
(`FQDN`) `oas.example.org`, the corresponding parameters would be:

* `--subdomain`: `oas`
* the `DOMAIN` positional argument: `example.org`

Create the OpenAppStack settings for your VPS by running the following command:

```
$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --subdomain oas example.org --create-hostname my-clusters-hostname
```

##### DNS entries

Before you continue, if you have not made DNS entries with the CLI tool, you
need to make them now. It is important to start with configuring DNS because
depending on your DNS setup/provider, it takes a while (sometimes hours) to
propagate.

You need one dedicated (sub)domain entry and a wildcard entry for everything
inside it. For example, create an A record for these domains:

- An `A` record `oas.example.org` pointing to the VPSs IP address,
- A `CNAME` record `*.oas.example.org` pointing to `oas.example.org`.

> **NOTE:** It is also possible to host openappstack on a domain (with no
> dedicated subdomain). In that case, make these DNS records instead:
> - An `A` record `example.org` pointing to the VPSs IP address,
> - A `CNAME` record `*.example.org` pointing to `example.org`.

OpenAppStack will fetch https certificates with [Let's
Encrypt](https://letsencrypt.org) by default. In order to do this DNS entries
need to be created.  If you don't need https certificates for your cluster while
testing you can skip this step. Please be aware of the limitations of this:

- Onlyoffice won't work since it requires a valid certificate connecting to Nextcloud.
- You need to be able to resolve the domain names locally.

### Step 2: Installation

You're almost ready to start the OpenAppStack installation script.  First, make
sure your DNS configuration is propagated. To do so, make sure 'ping' shows your
VPS's IP address:

    $ ping oas.example.org

The `install` command will try to log into your machine as the `root`user using
SSH.

To start the installation process, run:

    $ python -m openappstack my-cluster install

This will take between 5 and 20 minutes. It generates secrets that will be
added to the `clusters/my-cluster/secrets` directory. If you ever need any
credentials after this installation, you can probably find them there. **Make
sure this directory stays safe.** Feel free to encrypt it when you are not using
the `openappstack` CLI tool.

OpenAppStack uses [Flux](https://fluxcd.io) to install applications. After the
installation process has compleded, Flux has not necessarily finished installing
and integrating all the applications. This process can take up to a few hours to
complete.

In the future, we will add commands that show you the status of the application
installation. For now, just wait half an hour for everything to settle, and then
continue to the Usage section.

> **NOTE:** It is possible to re-run the `install` command. Make sure you re-run
> it on a machine with the same `secrets` as generated the first time. You can
> achieve this by making sure you have the `clusters/my-cluster` directory and
> it contains the same `secrets` directory before you run the installation
> command.

### Step 3: Validate setup

Because OpenAppStack is still under development, we would like you to follow our
[testing instructions](testing_instructions) to make sure that the setup process
went well.

## Usage

After all the applications are installed, the first thing to do is log into
admin.oas.example.org. Here you can find the "user panel", a place where you can
create, edit and delete users. You can log in with the user "admin". The
password can be found in
`clusters/my-cluster/secrets/userbackend_admin_password`. After logging in, you
will see an overview of all the applications your user has access to. For more
information, take a look at the [user panel
documentation](https://docs.openappstack.net/projects/user-panel/en/latest/).

> **NOTE:** at the moment none of the applications are available at
> `oas.example.org`, we only provide applications in subdomains. In the future
> this might change.

These applications should be available after the installation is completed:

* [OAS User panel](https://open.greenhost.net/openappstack/user-panel/), our
  user panel can be used to create and edit users. These users can be used to
  log into the applications listed below
* [Nextcloud](https://nextcloud.com/), a file sharing and communication
  platform;
  - Your Nextcloud is available at https://files.oas.example.org
* [ONLYOFFICE](https://www.onlyoffice.com/connectors-nextcloud.aspx), an online
  document editing suite;
  - Your documents saved in Nextcloud will be opened in ONLYOFFICE
* [Rocket.Chat](https://rocket.chat/), a team chat application;
  - Rocket.Chat is available at https://chat.oas.example.org. Single sign-on is
    not implemented yet for Rocket.Chat. You need to log in with the `admin`
    user. Its password can be found in
    `clusters/my-cluster/secrets/rocketchat_admin_password`.
* [WordPress](https://wordpress.com), a website content management system.
  - WordPress is available at https://www.oas.example.org. Click the "Log in"
    button and then click "Login with OpenID Connect" to use the single sign-on
    server. Note that if you log in with the single sign-on server, you will not
    have "admin" rights within WordPress. For that, use the admin credentials in
    the `secrets` folder.
* [Grafana](https://grafana.com) that shows you information about the status of
  your cluster.
  - Read more about Grafana in the [monitoring chapter below](#monitoring)

### Known limitations

- Single sign-on is still in an experimental phase. We are still working on
  transferring "roles" from users in the central database to applications, so
  your SSO's admin user gets admin permissions in all the applications. Some
  applications do not support logging out, currently.
- Nextcloud does not send emails yet. You can configure sending emails by going
  to Settings -> Basic settings -> Email server and entering SMTP email
  credentials.
- Rocket.Chat does not send emails yet either
- Rocket.Chat is not integrated with the single sign-on system. This will be
  implemented soon in a new release.

### Monitoring

You should be able to access the visual interface to the monitoring system,
Prometheus, at `https://grafana.oas.example.org/`. Admin users can log into
Grafana. You can create and add admin users through the User panel.

### Other applications installed into the cluster

Besides these applications, some other auxiliary components are installed:

* [OAS local-storage](https://open.greenhost.net/openappstack/local-storage) provides an easy way for the cluster to use a directory on
  the node (by default `/var/lib/OpenAppStack/local-storage`) for storage;
* [NGINX](https://www.nginx.com) is a webserver that functions as a so-called ingress controller,
  routing web traffic that enters the cluster to the various applications;
* [cert-manager](https://cert-manager.io) acquires and stores [Let's
  Encrypt](https://letsencrypt.org/) certificates, enabling encrypted web
  traffic to all applications running in the cluster;
* [Flux](https://fluxcd.io) checks for application updates approved by the
  OpenAppStack team and installs them automatically.