Install Rancher on Ubuntu: Step-by-Step Guide

To install Rancher on Ubuntu, you deploy it as a set of containers using Docker or a Kubernetes cluster, then access the web UI to manage your Kubernetes clusters. The quickest path is running a single Docker container with docker run -d --restart=unless-stopped -p 80:80 -p 443:443 rancher/rancher:latest, which gives you a working Rancher server in minutes. This guide covers both the Docker single-node method and the more robust Helm-based installation on an existing Kubernetes cluster, plus what to do after the server is up.

What Rancher Is and Why You’d Use It

Rancher is an open-source platform that manages Kubernetes clusters from one central interface. Instead of installing and configuring Kubernetes on each server manually, Rancher lets you create, import, and operate clusters through a web dashboard. It handles authentication, role-based access control, monitoring, logging, and application deployment across multiple clusters, whether they run on bare metal, in a public cloud, or on a virtual machine.

For an Ubuntu administrator, Rancher is useful when you manage more than one Kubernetes cluster or want a simpler way to deploy and upgrade clusters without memorizing kubectl commands. It also provides a catalog of Helm charts, so you can install common services like ingress controllers, monitoring stacks, or CI/CD tools with a few clicks.

Prerequisites Before You Start

Before installing, ensure your Ubuntu server meets these requirements:

Ubuntu version: 20.04 LTS or newer (22.04 and 24.04 work well).
Hardware: At least 4 GB of RAM and 2 CPU cores for a small test environment; production setups need more.
Docker: If using the single-node method, install Docker Engine 20.10 or later.
Kubernetes: If using Helm, you need a Kubernetes cluster (version 1.24 or newer) and kubectl configured.
Networking: Ports 80 and 443 must be reachable for the web UI; port 6443 is used for Kubernetes API access.
DNS: A hostname that resolves to the server’s IP, because Rancher uses TLS certificates tied to a domain.

You also need sudo privileges on the Ubuntu machine. If you plan to use a self-signed certificate for testing, that works, but a real domain with a valid certificate is required for production.

Method 1: Install Rancher with Docker (Single Node)

This is the fastest way to get Rancher running on Ubuntu. It installs Rancher as a single container that includes its own embedded Kubernetes cluster for storing configuration data.

Install Docker Engine if not already present: sudo apt update && sudo apt install docker.io.
Start and enable Docker: sudo systemctl enable --now docker.
Run the Rancher container: sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --name rancher rancher/rancher:latest.
Wait a minute or two for the container to start. Check logs with sudo docker logs rancher to see when it’s ready.
Open a browser to https://<your-server-ip>. You’ll see a warning about the self-signed certificate—accept it for now.
Follow the on-screen prompts to set the admin password and the Rancher server URL.

This method is ideal for testing, small deployments, or when you want a quick proof-of-concept. However, the single container is a single point of failure—if it crashes, your management plane goes down. For production, use the Helm method below.

Method 2: Install Rancher with Helm on Kubernetes

For a highly available setup, install Rancher on an existing Kubernetes cluster using Helm. This requires a cluster with at least three nodes (or one large node for testing) and a load balancer that routes traffic to ports 80 and 443.

Install Helm on your Ubuntu machine: curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash.
Add the Rancher Helm repository: helm repo add rancher-latest https://releases.rancher.com/server-charts/latest.
Create a namespace: kubectl create namespace cattle-system.
Install cert-manager (required for Rancher’s certificates): kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.yaml.
Install Rancher with Helm, replacing your.domain.com with your actual hostname: helm install rancher rancher-latest/rancher --namespace cattle-system --set hostname=your.domain.com.
Wait for the pods to start: kubectl -n cattle-system get pods. When all are running, access https://your.domain.com.

This setup gives you multiple replicas of the Rancher server, so if one node fails, another takes over. It also integrates with your existing Kubernetes monitoring and logging.

Post-Installation: Set Up Your First Cluster

Once Rancher is running, you need to create or import a Kubernetes cluster. From the dashboard, click Create to launch a new cluster on a cloud provider, or Import Existing to connect a cluster you already have. For a quick test, you can create a custom cluster and add a node by running the provided command on your Ubuntu server.

Rancher will install the necessary Kubernetes components on the node, which takes a few minutes. After that, you can deploy workloads, manage namespaces, and set up role-based access for your team. The UI also shows cluster health, resource usage, and events.

Common Problems and How to Fix Them

Several issues appear frequently when installing Rancher on Ubuntu:

Port 80 or 443 already in use: If Apache or Nginx is running, stop it or change Rancher’s ports. For Docker, use -p 8080:80 -p 8443:443 and access via https://<ip>:8443.
Certificate warning in browser: This is normal with self-signed certificates. For production, configure Let’s Encrypt or bring your own certificate via the Rancher settings.
Rancher container restarts repeatedly: Check logs with sudo docker logs rancher. Often it’s a DNS issue or the hostname not resolving. Ensure your /etc/hosts file maps the hostname to the server IP.
Helm install fails due to cert-manager not ready: Wait for cert-manager pods to be fully running before installing Rancher. Use kubectl get pods -n cert-manager to verify.
Cannot access the UI after install: Check firewall rules. On Ubuntu, run sudo ufw allow 80/tcp && sudo ufw allow 443/tcp if UFW is active.

If you’re stuck, the Rancher documentation and community forums are the best resources. The official troubleshooting guide covers most common scenarios.

Security and Backup Considerations

Rancher stores its configuration in a Kubernetes cluster (either embedded or the one you installed on). For the Docker method, you must back up the /var/lib/rancher directory on the host. For Helm, back up the cattle-system namespace resources and any persistent volumes.

Security-wise, always change the default admin password immediately. Use strong passwords and enable two-factor authentication for admin users. Restrict access to the Rancher server IP to trusted networks, and consider using a reverse proxy with SSL termination if you need extra control. Rancher also supports integration with LDAP or SAML for enterprise authentication.

Rancher vs. Other Kubernetes Management Tools

Rancher competes with tools like OpenShift, KubeSphere, and managed services like EKS or GKE. The main difference is that Rancher is distribution-agnostic—it can manage clusters from any provider, including on-premises. OpenShift is more integrated but heavier and tied to Red Hat. KubeSphere is lighter but less feature-rich. If you already use AWS or Google Cloud, their managed Kubernetes services may be simpler, but they lock you into that cloud. Rancher gives you a consistent interface across multiple clouds and on-premises environments.

For a small Ubuntu lab, Rancher is overkill if you only have one cluster. But if you plan to grow or need a GUI for your team, it’s worth the setup effort.

Frequently Asked Questions

Do I need Kubernetes to run Rancher?

No. The Docker method runs Rancher as a single container with an embedded Kubernetes cluster, so you don’t need to install Kubernetes separately. The Helm method requires an existing cluster, but that’s optional.

Can I install Rancher on Ubuntu 24.04?

Yes. Rancher supports Ubuntu 20.04, 22.04, and 24.04. As long as Docker or Kubernetes runs, Rancher works. Always check the latest compatibility matrix on the Rancher website for exact versions.

How long does the installation take?

With Docker, you can have Rancher running in under 5 minutes, including the container pull. The Helm method takes longer because you need to set up cert-manager and wait for all pods to start—typically 10-15 minutes.

Can I use Rancher for free?

Yes, Rancher is open-source under the Apache 2.0 license. SUSE, the company behind Rancher, offers paid support and enterprise features, but the core platform is free to use.

What is the default admin password for Rancher?

There is no default password. On first access, Rancher asks you to set the admin password. If you miss that step, you can reset it by running sudo docker exec rancher reset-password (for Docker installs) or using the kubectl command for Helm installs.

Can I upgrade Rancher after installation?

Yes. For Docker, pull the new image and recreate the container with the same volumes. For Helm, run helm upgrade rancher rancher-latest/rancher --namespace cattle-system. Always back up before upgrading.

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →