Here's how you can set up a single-node OpenAppStack cluster. Support for multi-node clusters will come in the future.
## Prerequisites
* A virtual machine or bare metal server with:
* Ubuntu 18.04
* A public IP address
* 10GB of disk space and 4GB of RAM
* Root ssh access
### DNS entries
First, begin with creating DNS records for your cluster. It's important to start with configuring DNS because depending on your DNS setup/provider, it takes a while to propagate.
You need one dedicated subdomain entry and a wildcard entry for everything inside it. For example, create an A record for these domains:
- oas.example.org
-\*.oas.example.org
and make them point to your machine's public IP address. It is very important that you use the first address after the '\*' in the second address.
Copy `ansible/inventory.yml.example` to `ansible/inventory.yml` and edit it to reflect your cluster.
Also copy `ansible/group_vars/cluster/settings.yml.example` to `ansible/group_vars/cluster/settings.yml` and edit as you see fit.
### Prerequisites
* You need `ansible >= 2.6` installed on your workstation to run the bootstrap
scripts. Please install it using your system package manager.
In the case your system package manager doesn't provide `ansible >= 2.6` you
can install it via the python package manager like this:
```
pip3 install --user -r ansible/requirements.txt
```
Hint: if you have several python projects on your PC, consider using [virtualenv](https://virtualenv.pypa.io/en/stable/)
Hint: if you get a [segmentation fault](https://bitbucket.org/cffi/cffi/issues/272/segfault-while-installing-via-pip) using above command, you can add `--no-use-wheel` to it.
### Installation
The bootstrap process sets up a single-node kubernetes cluster on the machine
and installs the utility tools `helmfile`, `helm`, `kubectl` and `rke`.
To run the bootstrap process, you need to move into the `ansible/` directory,
then run
```
ansible-playbook bootstrap.yml
```
It will take approx. 5-10 mins to setup your cluster.
Please report any installation issue as described under [Troubleshooting](#troubleshooting).
### Usage
Right now, there's two applications pre-installed. One of them is [keycloak](https://www.keycloak.org/), an open source identity and access management application. It's used for [single-sign-on](https://en.wikipedia.org/wiki/Single_sign-on) to other application that can get installed later.
The admin console web interface should be reachable at https://auth.oas.example.org.
The other one is [traefik](https://traefik.io/), which acts as a reverse proxy and load balancer for other applications.
It also fetches [letsencrypt](https://letsencrypt.org/) certificates for securing https access to deployed apps. Its web interface is available at https://traefik.oas.example.org.
## Managing an existing cluster
Login to your cluster with:
ssh USER@oas.example.org
where `USER` the `ansible_user` you configured in `ansible/inventory.yml`.
Some programs that are installed on your cluster:
*`kubectl` is the Kubernetes control program.
For example, run `kubectl get pods -n oas` to see a list of pods that exist
in the `oas` namespace (system applications like traefik),
and `kubectl get pods -n oas-apps` for all other OpenAppStack applications
(currently keycloak).
Run `kubectl --help` for help.
*`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.
It's manual usage is a bit tricky since [current helmfile config depends on environmental variables to be present](https://code.greenhost.net/openappstack/bootstrap/issues/101).
## Troubleshooting
In case something goes wrong or you have any questions or comments please contact [get in contact with us otherwise](/contact.html).
The output of these commands is helpful to debug deployment errors:
