README.md

# OpenAppStack bootstrap script

This collection of scripts allows you to easily set up a new OpenAppStack cluster.

As part of the bootstrap process a special control shell is installed (in the form of
a Docker image) which contains utilities to manage your cluster.

## Prerequisites

* You need to have ssh access (either as root, or as another user that can
  `sudo`) to the machines that will make up your cluster.
* You need ansible installed on your workstation to run the bootstrap scripts.

## Bootstrapping a new cluster

### Configure your cluster

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.

### Install

To run the bootstrap process, move into the `ansible` directory, then run

```
./ansible-playbook -i inventory.yml bootstrap.yml
```

## Managing an existing cluster

The OpenAppStack project has created a special "control shell", a Docker
container that you can run to perform administrative tasks on your cluster.
Some programs that you can run from this shell:
* `kubectl` is the Kubernetes control program. For example, run
  `kubectl get pod` to see a list of pods that currently exist in your cluster.
  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. For example,
  run `helmfile -e oas diff` to view the differences between what's currently
  installed and what should be installed according to the OpenAppStack
  installation plan.

To start the control shell, run

```
./manage $SERVER
```

where `$SERVER` is the address of the master machine of your cluster.