Skip to content
Snippets Groups Projects
Verified Commit 2462cd33 authored by Arie Peterson's avatar Arie Peterson
Browse files

Add Velero install instructions, rewriting to rst in the process

parent 841abfa9
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
docs/installation_instructions.md deleted 100644 → 0
+ 0
− 291
View file @ 841abfa9
# 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/).
We will 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 create 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` installed. On a debian based system:
`apt install python3`
* 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 with it's development files, Pip and Git installed
(`apt install python3-pip python3-dev 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.1`):
$ git clone -b 0.3.1 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 usually takes 10-20 minutes
to complete, but can also take longer depending on your machine's compute and/or
network resources.
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.
docs/installation_instructions.rst 0 → 100644
+ 362
− 0
View file @ 2462cd33
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/>`__.
We will 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 create 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`` installed. On a debian based system:
``apt install python3``
- 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 with its development files, Pip and Git installed
(``apt install python3-pip python3-dev 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.1``):
::
$ git clone -b 0.3.1 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
- There are two ways to let the installation program know which VPS to use:
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.
In that case, 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
~~~~~~~~~~~~~~~~~~~~
.. Tip::
At this point you can enable `Velero <https://velero.io>`__, a program that
runs on your cluster and uploads backups of your cluster and user data to an
S3 storage service of your choice.
To do so:
- edit the file ``clusters/my-cluster/group_vars/all/settings.yml``,
reviewing all settings under the ``backup`` field and entering the data
specific to your backup storage location;
- create the directory ``clusters/my-cluster/secrets``;
- create the file ``clusters/my-cluster/secrets/s3_access_key``, with as
only contents your S3 access key;
- create the file ``clusters/my-cluster/secrets/s3_secret_key``, with as
only contents your S3 secret key.
Then continue with the installation procedure as described below.
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
usually takes 10-20 minutes to complete, but can also take longer
depending on your machine's compute and/or network resources.
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.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment