Skip to main content
Version: 1.10.0

Installing Epinio on Rancher Desktop (RD)

This How-to uses the following versions:

Rancher Desktop prerequisites

  • Running on Windows needs Windows Subsystem for Linux (WSL). It's installed by RD as a prerequisite.
  • Epinio currently only supports x86 so won't work with RD for Mac on the M1 chip.

Install Rancher Desktop

Install the latest version of RD for your operating system.

Setup Kubernetes

When running RD for the first time, wait until the initialization is complete. It may take some time to download and install the necessary components.

Check that Kubernetes is enabled in RD and a supported version is selected. Look under Kubernetes Settings in RD (Epinio has been tested on v1.22.7, v1.21.10 and v1.20.15).

Ensure Traefik is enabled, or you are using a different Ingress controller.

Install epinio

Make sure Rancher Desktop is running.

RD can report Kubernetes as running when some pods aren't ready yet. You can check this by running the command kubectl get pods -A in a terminal session. Check that all pods report either a Running or Completed status.

RD configures its own load-balancer which exposes Traefik on Use this with a wildcard DNS to get a system domain of

The Epinio installation is similar on Linux, macOS and Windows:

  1. Start a shell. Use cmd or powershell on Windows and your preferred shell on Linux/MacOS.

  2. Install the Epinio CLI.

  3. Follow the Epinio installation process. It uses:

    kubectl apply -f

    # Wait for cert-manager to stabilize

    helm repo add epinio
    helm install epinio -n epinio --create-namespace epinio/epinio --set

    epinio login -u admin


    For RD on Linux, you need to be able to open ports from 80 (and above). This allows access to the URL set in global.domain (that is, You need to set the start port of the unprivileged list to a lower number.

    The RD installation needs ports open from 80 so:

    # [Optional] Check the current unprivileged port start
    sysctl -n net.ipv4.ip_unprivileged_port_start

    # Temporary modification of the unprivileged port start
    sudo sysctl -w net.ipv4.ip_unprivileged_port_start=80

    # Permanent modification of the unprivileged port start can be done
    # with something like this
    sudo sh -c 'echo "net.ipv4.ip_unprivileged_port_start=80" >> /etc/sysctl.d/50-unprivileged-ports.conf'

    # Check the current unprivileged port start
    sysctl -n net.ipv4.ip_unprivileged_port_start

    You can find more information in this issue.