Install OpenAppStack¶
This guide explains how to install OpenAppStack either on an existing Kubernetes cluster that you have setup entirely yourself, or on a cluster you created following the OpenAppStack Create a kubernetes cluster guide. Please choose one of the below options:
If you followed the Create a kubernetes cluster guide to setup a Kubernetes cluster using the OpenAppStack CLI tool you’re all set and can continue by following the steps below.
Note
Installation on an existing Kubernetes cluster ist still experiental and might not work depending on the setup of your cluster/cloud provider. We’ll be happy to recieve feedback from your experiences though altough we cannot guarrente !
Prerequisites:
A single-node Kubernetes cluster
A
kube_config.yml
file for API access
Configure DNS: Please follow Step 2: Configure DNS how to setup the DNS records for OpenAppStack.
Setup:
Create a directory containing your cluster configuration, i.e.
mkdir -p clusters/oas.example.org
Copy your
kube_config.yml
file inside your cluster config directory and rename it tokube_config_cluster.yml
:cp kube_config.yml clusters/oas.example.org/kube_config_cluster.yml
Continue by following the steps below.
Flux configuration¶
Prerequisites¶
kubectl
(installation instructions)flux version 0.14.2
Download flux_0.14.2_linux_amd64.tar.gz
Copy the file install/.flux.env.example
to your cluster dir
clusters/oas.example.org/.flux.env
. This file contains the last bit of
information you need to configure. You have to configure the following
values. The rest are optional.
ip_address
: The IP address of your clusterdomain
: The FQDN of your clusteradmin_email
: a valid email address for the system administrator of your cluster.
Outgoing email¶
If you want apps like Nextcloud, RocketChat and Prometheus to be able to send email notifications, you need to provide an email account.
Note
OpenAppStack does not set up an email server for you. In order to enable outgoing emails you need to provide an already existing email account.
OpenAppStack uses SMTP to send emails. Search your email provider’s helpdesk
for SMTP configuration details and enter them in the
clusters/oas.example.org/.flux.env
file as follows:
# Enable sending mails
outgoing_mail_enabled=true
# Email address that the cluster sends mails from. Needs to be an existing SMTP
# login
outgoing_mail_from_address=admin@example.org
# Same outgoing mail address, but only the part before the '@'
outgoing_mail_from_local_part=admin
# Same outgoing mail address, but only the part after the '@'
outgoing_mail_domain=example.org
# SMTP password for the outgoing mail address
outgoing_mail_smtp_password=CHANGEME
# SMTP username, often the same as the outgoing email address
outgoing_mail_smtp_user=admin@example.org
# SMTP login data.
outgoing_mail_smtp_host=smtp.greenhost.nl
outgoing_mail_smtp_authtype=LOGIN
outgoing_mail_smtp_port=587
Backups with Velero¶
You can enable Velero, a program that runs on your cluster and uploads backups of your cluster and user data to an S3 storage service of your choice.
If enabled, Velero will create a backup of your cluster once every night and upload it to the S3 storage you configure. This includes:
your cluster state. Technically speaking, it will back up all Kubernetes namespaces in your cluster, except
velero
itself; this includes things like which applications are installed, including their version number and installation-time settings;persistent data of all applications: for example, single sign-on users that you created, Nextcloud files and metadata, WordPress site data and comments, Rocket.Chat chat history, etc. A single exception to this is Prometheus data (statistics of system properties), which takes up a lot of space and we consider not valuable enough to back up.
It does not include anything on the VPS that you may have set up but is not
part of OpenAppStack, like programs installed via apt
, or data added to the
VPS disk not through OpenAppStack.
To configure Velero, edit the file clusters/oas.example.org/.flux.env
,
and configure the settings with the backup_s3_
prefix.
Then continue with the installation procedure as described below. At the end of
the installation procedure, you have to install the velero
application.
Step 1: Install core applications¶
Before you can start, you need to execute a few commands from the installation
directory on your provisioning machine. Don’t forget to replace
oas.example.org
with your domain.
export CLUSTER_DIR=clusters/oas.example.org
# Copy the installation kustomization to your cluster directory
cp install/kustomization.yaml $CLUSTER_DIR/
# Tell kubectl to use your cluster's kube_config
export KUBECONFIG=$CLUSTER_DIR/kube_config_cluster.yml
# Ensure flux-system namespace is created
kubectl get namespace flux-system 2>/dev/null || kubectl create namespace flux-system
# This inserts the configuration from .flux.env into your cluster as a "secret"
kubectl apply -k $CLUSTER_DIR
After you have executed that code, your terminal should show:
secret/oas-cluster-variables created
Next, run:
./install/install-openappstack.sh
This installs the core of OpenAppStack into your cluster. To see what’s
included, check the flux2/infrastructure
and the flux2/core
folders in
the git repository.
Step 2: Install additional applications¶
After the script completes, you can install applications by running the other
installation scripts in the install
folder. At the moment, we have scripts
to install:
Nextcloud and Onlyoffice with
./install/install-app.sh nextcloud
Rocket.Chat with
./install/install-app.sh rocketchat
Wekan with
./install/install-app.sh wekan
WordPress with
./install/install-app.sh wordpress
Velero with
./install/install-app.sh velero
(only if you have configured it in Backups with Velero).
When the installation scripts complete, the application installation may still
be running on the OpenAppStack cluster. You can monitor the progress by running
flux get kustomizations
(use watch flux get kustomizations
to get
updates). If all kustomizations have been applied correctly, you can monitor
specific application releases by running watch flux get helmreleases
--all-namespaces
.
Step 3: Validate setup¶
Because OpenAppStack is still under development, we would like you to follow our testing instructions to make sure that the setup process went well.
Step 4: Let us know!¶
We would love to hear about your experience installing OpenAppStack. If you encountered any problems, please create an issue in our issue tracker. If you didn’t please still reach out as described on our contact page and tell us how you like OpenAppStack so far. We want to be in communication with our users, and we want to help you if you run into problems.