Quick Installation Guide

This is quick guide for you to install a single-node Octelium Cluster which is good enough for development, personal or undemanding use cases.

NOTE

To install a production, scalable multi-node Cluster over a typical cloud-based or on-prem Kubernetes installation, we recommend to refer to this guide here.

This guide only needs 2 requirements:

Having a cheap cloud server/VM instance (e.g. DigitalOcean Droplet, Hetzner server, AWS EC2, etc...) that's running a recent Ubuntu or any Debian-based distribution, preferably a freshly installed one with at the very least 2GB of RAM even though we strongly recommend an instance with 4GB of RAM and 2vCPUs as a sensible very minimum requirement.
Having a domain or a subdomain of a domain name for the Cluster that you actually own (e.g. example.com, octelium.example.com, sub.sub.example.com, etc...). This domain is the Cluster's domain since an Octelium Cluster is defined and addressed by its domain once installed (e.g. via the octelium and octeliumctl commands).

Once you SSH into your VPS/VM and log in as the root user, you install the Cluster by running the following command:

curl -o install-demo-cluster.sh https://octelium.com/install-demo-cluster.sh
chmod +x install-demo-cluster.sh

# Replace <DOMAIN> with your actual domain
./install-demo-cluster.sh --domain <DOMAIN>

NOTE

You might want to read the script to understand or modify what it does. The script first installs a single-node Kubernetes cluster, then it installs a few open source dependencies for your Octelium Cluster (namely PostgreSQL, Redis, Cilium and Multus) and deploy them in the Kubernetes cluster, then it simply installs the Octelium Cluster itself.

The script should take a few minutes depending on your VM's capabilities to finish. At the end of th installation, you will be shown the following command:

octelium login --domain <DOMAIN> --auth-token <AUTHENTICATION_TOKEN>

You can now copy that command in order to use it later from within your own machine to log in to the Cluster and actually start using it.

Post-Installation

To complete the installation and start interacting with the Cluster, there are 2 final steps that must be done:

Setting the public DNS for the Cluster domain You can do that by simply getting the newly installed cloud instance public IP from your cloud provider dashboard and then using the IP value in your DNS provider (e.g. Cloudflare, Namecheap, GoDaddy, etc...) to set a DNS entry that denotes to your Cluster domain. You can read more here. Make sure to, at least for now, add entries for both the <DOMAIN> domain as well as *.<DOMAIN> wildcard domain (mainly via a CNAME entry) to resolve to that IP address.
Setting the Cluster domain certificate in order for the Cluster, its API Server as well as its public Services to be able to communicate over HTTPS. For example, you can use Let's Encrypt via Certbot for example to issue a certificate for your Cluster domain (you can read more here) and then feed the issued certificate to the Cluster. Here is an example of certbot issuing a certificate via the http challenge:

apt-get update
apt install certbot

# Replace <DOMAIN> with your own domain
certbot certonly --email <YOUR_EMAIL> --agree-tos --cert-name <DOMAIN> -d "<DOMAIN>,*.<DOMAIN>,*.local.<DOMAIN>" --standalone --preferred-challenges http
export KUBECONFIG="/etc/kubernetes/admin.conf"

# Replace <DOMAIN> with your own domain
kubectl create secret tls cert-cluster -n octelium --key /etc/letsencrypt/live/<DOMAIN>/privkey.pem --cert /etc/letsencrypt/live/<DOMAIN>/fullchain.pem

The Octelium Cluster automatically watches for the changes of that Kubernetes secret and automatically synchronizes with it whenever it updates.

Now that we use the octelium login command that we copied to connect to the Cluster from our local machine as follows:

octelium login --domain <DOMAIN> --auth-token <AUTHENTICATION_TOKEN>

NOTE

If you try to interact with the Cluster via octelium or octeliumctl commands before setting your actual domain's certificate, you will be met with an authentication handshake failed error due to the initial self-signed certificate created by the Cluster during installation. You can skip that error by setting the OCTELIUM_DEV environment variable to true. Here is an example:

OCTELIUM_DEV=true octelium login --domain <DOMAIN> --auth-token <AUTHENTICATION_TOKEN>

What Now?

Now our Cluster has been successfully installed and is now running. You can learn more about how to manage and use the Cluster in the following guides:

First Steps Managing the Cluster here.
Managing Services here.
Access control and Policies here.
Adding IdentityProviders here.