installation_instructions.md 13.4 KB
Newer Older
1
2
# OpenAppStack Tutorial

3
4
This document describes how you can set up a single-node OpenAppStack cluster.
Support for multi-node clusters will come in the future.
5

6
> **NOTE:** All commands in these installation instructions need to be run on a
7
8
9
> 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.
10
11

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

15
16
## Warnings

17
* OpenAppStack is still under heavy development and is not ready for
18
  production use! We anticipate major changes and do not guarantee a
19
20
21
  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).
22
23
24
25
26
27
28
* 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

* A virtual machine or bare metal server with:
29
30
  * Current Debian stable "buster";
  * A public IP address;
31
  * 6GB of RAM;
32
  * At least 20GB of disk space for installation, plus more for application
33
    data;
Ana Aviles's avatar
Dot    
Ana Aviles committed
34
  * root ssh access.
35
  * Python installed
36
* A trusted local machine to run the installer on:
37
38
39
40
  * 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`
41

42
## Install OpenAppStack command line tool
43

Varac's avatar
Varac committed
44
On your **provisioning machine**, clone the OpenAppStack git repository and
Mark's avatar
Mark committed
45
checkout the latest tagged version (currently `0.2.2`):
46

Mark's avatar
Mark committed
47
    $ git clone -b 0.2.2 https://open.greenhost.net/openappstack/openappstack.git
48
49
50
    $ cd openappstack


51
52
If you installed `virtualenv`, create a python virtual environment called "env"
that uses python 3. This makes sure we do not change any of your other python
Varac's avatar
Varac committed
53
projects. The second command "activates" the virtualenv.
54
55
56
57
58

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

60
61
    $ python3 -m venv env
    $ . env/bin/activate
62

Varac's avatar
Varac committed
63
Next, install the OpenAppStack CLI client by running the following commands:
64

65
    $ pip3 install -r requirements.txt
66

67
> *Hint:* if the `pip3 install` command results in a [segmentation
68
69
> fault](https://bitbucket.org/cffi/cffi/issues/272/segfault-while-installing-via-pip),
> you can add `--no-use-wheel` to it.
70

Varac's avatar
Varac committed
71
Now you can run the OpenAppStack CLI as follows:
72

73
    $ python -m openappstack CLUSTER_NAME <command>
74

75
The CLI *always* needs a `CLUSTER_NAME` argument. Even for getting subcommand
76
help messages. Be sure to run this command in the root directory of the git
77
78
repository. In this tutorial, we're using `my-cluster` as the cluster name. Try
it out by running
79
80

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

82
## Install OpenAppStack
83

Varac's avatar
Varac committed
84
Setting up OpenAppStack on your VPS happens in three steps:
85
86
87
88

1. **Set up cluster**

   Create configuration files, and optionally create VPS
89

90
91
92
93
94
2. **Install OpenAppStack**

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

96
97
98
99
100
101
102
103
3. **Validate setup**

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

### Set up cluster

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

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

Varac's avatar
Varac committed
109
There are two options to create a cluster:
110

111
112
113
114
#### Use a Greenhost VPS

- For this to work, you need to have an API key with Customer rights.
  1. In the Cosmos service centre, click your name on the top right corner
Varac's avatar
Varac committed
115
  2. Go to "User settings"
116
117
118
119
  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
120
121
122
123
     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.
124
  7. Copy the generated key and run export it to this variable in a terminal:
125

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

133
134
   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).
135

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

140
141
142
     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.
143

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

150
  If you use a subdomain (e.g. oas.yourdomain.com), use the `--subdomain`
Varac's avatar
Varac committed
151
  command as follows:
152

153
  ```
154
  $ python -m openappstack my-cluster create --subdomain oas example.org
155
  ```
156

157
- Here is an example of a complete creation command:
158

159
  ```
160
  $ python -m openappstack my-cluster create --create-droplet --hostname oas.example.org --ssh-key-id 112 --acme-live-environment --create-domain-records --subdomain oas example.org
161
  ```
162

163
164
165
166
  > **NOTE:** We use the `--acme-live-environment` argument. This ensures you
  > get real (instead of "staging") Let's Encrypt TLS certificates. This is
  > necessary for ONLYOFFICE integration to work.

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

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

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

177
#### Any other VPS or bare metal server
178

179
180
If you want to follow this step, we assume you already have a VPS. You'll need
its *hostname* and its *IP address*. Also check that your VPS meets our
Varac's avatar
Varac committed
181
[prerequisites](#prerequisites).
182
183
184
185
186

> **WARNING:** the OpenAppStack installation makes substantial changes to your
> whole VPS and needs root access. It is not advised to follow these
> instructions on a VPS that you are using for something else too.

Varac's avatar
Varac committed
187
Create the OpenAppStack settings for your VPS by running the following command:
188
189

```
190
$ python -m openappstack my-cluster create --ip-address IP_ADDRESS --hostname HOSTNAME --subdomain oas example.org --acme-live-environment
191
```
192

193
194
195
196
> **NOTE:** We use the `--acme-live-environment` argument. This ensures you get
> real (instead of "staging") Let's Encrypt TLS certificates. This is necessary
> for ONLYOFFICE integration to work.

197
### DNS entries
198

199
200
201
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
Varac's avatar
Varac committed
202
propagate.
203
204
205

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

207
- An `A` record `oas.example.org` pointing to the VPSs IP address,
208
- A `CNAME` record `*.oas.example.org` pointing to `oas.example.org`.
209
210
211
212
213

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

215
216
217
218
219
220
221
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.
222

223
### Installation
224

225
226
Before you start the installation, make sure your DNS is propagated. To do so,
make sure 'ping' shows your VPS's IP address:
227

228
    $ ping oas.example.org
229

230
The installation process sets up a single-node Kubernetes cluster on the machine
231
and installs the utility tools [helmfile](https://github.com/roboll/helmfile), [helm](https://helm.sh/), [kubectl](https://kubernetes.io/docs/reference/kubectl/overview/) and [rke](https://rancher.com/docs/rke/latest/en/).
232

233
To start the installation process, run:
234

235
    $ python -m openappstack my-cluster install
236

237
This will take between 5 and 20 minutes. It generates secrets that will be
238
added to the `clusters/my-cluster/secrets` directory. If you ever need any
239
240
241
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.
242
243

You can re-run the `install` command. Make sure you re-run it on a machine with
244
245
246
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.
247
248
249

## Usage

250
When the installation is completed, you will have access to these applications:
251
252
253
254
255

* [Nextcloud](https://nextcloud.com/), a file sharing and communication
  platform;
* [ONLYOFFICE](https://www.onlyoffice.com/connectors-nextcloud.aspx), an online
  document editing suite.
256
257
258
* [Grafana](https://grafana.com) that shows you information about the status of
  your cluster. Read more about Grafana in the [monitoring chapter
  below](#monitoring)
259

260
You can access Nextcloud via https://files.example.org. Use the username
261
`admin` with the automatically generated Nextcloud password that you can find in
262
`clusters/my-cluster/secrets/nextcloud_admin_password` on your local machine.
263
264
ONLYOFFICE is already integrated in your Nextcloud installation which allows you
to create and share ONLYOFFICE documents within Nextcloud. ONLYOFFICE runs on
Varac's avatar
Varac committed
265
https://office.oas.example.org.
266

267
268
### Known limitations of Nextcloud & ONLYOFFICE

269
270
271
- Nextcloud does not send emails yet. You can configure sending emails by going
  to Settings -> Basic settings -> Email server and entering SMTP email
  credentials.
272
273
274
275
276
277
278

### Monitoring

You should be able to access the visual interface to the monitoring system,
Prometheus, at `https://grafana.oas.example.org/`. A user `admin` is created at
installation time; the password that was generated during installation is stored
in the file `clusters/my-clusters/secrets/prometheus_grafana_admin_password` on
279
your provisioning machine.
280
281
282

### Other applications installed into the cluster

283
Besides these applications, some other auxiliary components are installed:
284

285
286
287
288
289
290
291
292
* `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 is a webserver that functions as a so-called ingress controller,
  routing web traffic that enters the cluster to the various applications;
* `cert-manager` acquires and stores [Let's Encrypt](https://letsencrypt.org/)
  certificates, enabling encrypted web traffic to all applications running in
  the cluster;

293
## Managing an existing cluster
294

295
You can use `kubectl`, the Kubernetes control program, to find and manipulate
296
your Kubernetes cluster. Once you have installed `kubectl`, to get access to your
Varac's avatar
Varac committed
297
cluster with the OAS CLI:
298

299
300
    $ python -m openappstack my-cluster info

Varac's avatar
Varac committed
301
Look for these lines:
302

303
    To use kubectl with this cluster, copy-paste this in your terminal:
Varac's avatar
Varac committed
304

305
    export KUBECONFIG=/home/you/projects/openappstack/clusters/my-cluster/secrets/kube_config_cluster.yml
306

307
Copy the whole `export` line into your terminal. In *that* terminal, kubectl
Varac's avatar
Varac committed
308
will connect to your cluster.
309
310

> **NOTE:** you have to repeat this step in new terminals and terminal tabs.
311

312
### SSH access
313

314
Alternatively, you can SSH login to your VPS. Some programs that are
315
available to the root user on the VPS:
316

317
318
* `kubectl`, the Kubernetes control program. The root user is connected to the
  cluster automatically.
319
320
321
322
323
324
* `helm` is the "Kubernetes package manager". Use `helm ls` to see what apps are
  installed in your cluster. You can also use it to perform manual upgrades;
  see `helm --help`.
* `helmfile` is a high-level tool to manage your app installations.
  Its manual usage is a bit tricky since [current helmfile config depends on
  environmental variables to be
325
326
327
  present](https://open.greenhost.net/openappstack/openappstack/issues/101). It
  is recommended you use the `openappstack` CLI instead of manually running
  `helmfile`.