This is quick guide for you to install a single-node Octelium Cluster which is good enough for development, personal or undemanding use cases.
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 theoctelium
andocteliumctl
commands). You can actually uselocalhost
as a Cluster domain for Clusters installed on your local machine.
If the VM/VPS is behind a firewall like in EC2 for example, you will need to open the TCP ports 443
for Octelium ingress as well as the UDP port 53820
for WireGuard.
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.shchmod +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
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 updateapt install certbot# Replace <DOMAIN> with your own domaincertbot certonly --email <YOUR_EMAIL> --agree-tos --cert-name <DOMAIN> -d "<DOMAIN>,*.<DOMAIN>,*.local.<DOMAIN>" --manual --preferred-challenges dnsexport KUBECONFIG="/etc/rancher/k3s/k3s.yaml"# Replace <DOMAIN> with your own domainkubectl 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>
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: