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 Linux distribution (e.g. Ubuntu 24.04 LTS or later, Debian 12+, etc...), preferably freshly installed, with at the very least 2GB of RAM, 2vCPUs and 20 GB of disk storage as a sensible very minimum requirement. You can also install it locally on any Linux machine or a Linux VM inside a MacOS or Windows machine (e.g. Podman machines, VirtualBox, etc...).
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).

NOTE

You can actually use localhost as a Cluster domain for Clusters installed on your local machine if you intend to install and run the Cluster inside of a VM/microVM in your own machine an use it as a playground. In fact, there is already an GitHub repository that lets you install and run an Octelium Cluster inside of a GitHub Codespace and such Cluster use localhost as their domain. You can visit the repository here.

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

# IMPORTANT: Replace <DOMAIN> with your actual domain/subdomain to be used as the Cluster domain
./install-demo-cluster.sh --domain <DOMAIN>

If your VM/VPS is behind NAT (e.g. default EC2 and GCP VM configurations), you will need to use the --nat flag as follows:

./install-demo-cluster.sh --domain <DOMAIN> --nat

NOTE

If the VM/VPS is behind a firewall like in EC2 for example, you will need to open the TCP port 443 for Octelium ingress as well as the UDP port 53820 for WireGuard.

You can also install a specific Cluster version via the --version flag as follows:

./install-demo-cluster.sh --domain <DOMAIN> --version 0.1.2

The script should take a few minutes depending on your VM's capabilities to finish. At the end of the Cluster 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. For now, you need to add 2 DNS entries:

An A entry to resolve <DOMAIN> to that VM/VPS public IP address.
A CNAME entry resolving the wildcard domain *.<DOMAIN> to <DOMAIN>. This entry effectively resolves all the <DOMAIN> sub-domains to the VM/VPS public 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 DNS-01 challenge (read more in the LetsEncrypt docs):

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>" --manual --preferred-challenges dns
export KUBECONFIG="/etc/rancher/k3s/k3s.yaml"

# 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>

If you ever want to uninstall the Cluster later for whatever reason, including in order to re-install the Cluster, you can simply do that via the same installation script via the --uninstall flag as follows:

./install-demo-cluster.sh --uninstall

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.