Install Rancher on CentOS 8: A Quick, No‑Frills Guide
If you’re running a CentOS 8 server and want Rancher to spin up Kubernetes clusters, this walk‑through gets you there in about fifteen minutes. We’ll keep the Docker runtime lean, skip over unnecessary bells and whistles, and explain why each command matters.
1. Prerequisites
- Root or sudo access – Rancher runs as root inside its container, so you need to be able to run privileged commands.
- At least 2 GB RAM – The Rancher UI plus the Kubernetes control plane can eat memory fast; keep an eye on your swap settings.
- Network connectivity – Docker pulls images from Docker Hub; make sure firewalls or proxies aren’t blocking outbound HTTPS traffic.
2. Install Docker (or Podman)
CentOS 8 ships with docker-ce in the AppStream repo, but it’s older than the version Rancher expects. I’ve seen newer Kubernetes clusters break when the container runtime is out of date, so let’s install the latest community edition.
sudo dnf -y install dnf-plugins-core sudo dnf config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo sudo dnf install -y docker-ce docker-ce-cli containerd.io
Why this matters: The docker-ce repo delivers the latest stable Docker binaries, and containerd.io provides a lightweight runtime that Rancher can hook into. Skipping this step will leave you with a broken image pull later.
Start and enable Docker:
sudo systemctl start docker sudo systemctl enable docker
Check the version to be sure:
docker --version # Expected output: Docker version 20.xx.x, build …
3. Disable SELinux for Compatibility (Optional but Recommended)
CentOS 8 defaults to enforcing SELinux, which can interfere with Rancher’s ability to write to /var/lib/rancher. If you hit permission errors later, a quick switch to permissive mode solves them.
sudo setenforce 0 # Temporarily put SELinux in permissive mode sudo sed -i 's/^SELINUX=enforcing/SELINUX=permissive/' /etc/sysconfig/selinux
Why this matters: Rancher expects to mount volumes inside the container without SELinux complaining. Leaving it enforced often results in “permission denied” errors when you try to access the UI.
4. Pull the Latest Rancher Image
Pulling the image ahead of time prevents Rancher from trying to fetch during startup, which can be painfully slow on a flaky network.
sudo docker pull rancher/rancher:latest
Why this matters: If you let Rancher pull automatically, a hiccup in your internet connection could leave the container stuck in Pulling status for hours. Explicitly pulling it ensures the image is cached locally.
5. Run Rancher Inside Docker
Now launch the container with the recommended flags:
sudo docker run -d --restart=unless-stopped \
-p 80:80 -p 443:443 \
-v /var/lib/rancher:/var/lib/rancher \
rancher/rancher:latest
What each flag does:
- --restart=unless-stopped keeps Rancher alive after reboots.
- -p 80:80 -p 443:443 exposes the UI on standard HTTP/HTTPS ports (no need to remember a random port).
- -v /var/lib/rancher:/var/lib/rancher persists data across container restarts, so your cluster state sticks.
Why this matters: Without those volumes, every time you restart Rancher you lose all cluster registrations and settings. The --restart option means you can safely reboot the host without pulling a fresh image.
6. Verify the Container is Healthy
A quick health check shows whether Rancher started properly:
sudo docker ps | grep rancher # Should show STATUS like "Up X seconds"
If it’s still pulling or stuck, inspect logs:
sudo docker logs <container_id>
Typical errors: “could not open /var/lib/rancher/...” – usually a permissions glitch. If that happens, double‑check the volume mount and SELinux setting.
7. Access Rancher UI
Open a browser on https://<your-server-ip>/. The first time you hit it, Rancher will walk you through an admin password setup. After that:
1. Create or import a Kubernetes cluster.
2. Manage workloads, monitor health, and add nodes as needed.
If HTTPS warns about an untrusted certificate (it does by default), just accept the risk or set up Let’s Encrypt later.
8. Keep Rancher Updated
When new releases come out:
sudo docker pull rancher/rancher:latest sudo docker stop $(docker ps -qf "ancestor=rancher/rancher") sudo docker rm $(docker ps -a -qf "ancestor=rancher/rancher") sudo docker run … # same command as above
Why this matters: Rancher releases security patches regularly. Sticking with an old image could expose your cluster to known vulnerabilities.
That’s it – a lean, functional Rancher installation on CentOS 8. No fluff, just the commands that work, and a quick note about why each step is necessary so you’re not left scratching your head when something breaks.
