Single Node Installation

Install Rancher on a single Docker node for development and testing

For development, testing, or proof-of-concept environments, Rancher can be installed on a single node using Docker. This simplified installation method runs Rancher directly in a Docker container without requiring a Kubernetes cluster.

Single-node installations are NOT recommended for production use. Use high availability deployment for production workloads.

Quick Start

The fastest way to get Rancher running:

sudo docker run -d --restart=unless-stopped -p 80:80 -p 443:443 --privileged rancher/rancher

Open your browser to https://localhost to access Rancher.

Prerequisites

Operating System Requirements

Supported operating systems:

• Ubuntu 20.04+, 22.04+
• RHEL/CentOS 7.x, 8.x, 9.x
• SLES 15 SP2+
• Debian 10+, 11+
• Rocky Linux 8+, 9+
• Oracle Linux 7.x, 8.x, 9.x

Refer to the Support Matrix for specific OS versions for each Rancher version.

Hardware Requirements

Minimum requirements:

• 2 vCPUs
• 4 GB RAM
• 20 GB disk space

Recommended for testing:

• 4 vCPUs
• 8 GB RAM
• 50 GB disk space

Software Requirements

• Docker 20.10+ or higher
• Internet connectivity (for image downloads and updates)

Installation

Advanced Configuration

Using a Specific Version

Specify a particular Rancher version:

sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:v2.13.3

Persistent Data Storage

Mount a volume to persist Rancher data:

sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  -v /opt/rancher:/var/lib/rancher \
  rancher/rancher:latest

This ensures data survives container restarts and upgrades.

Custom SSL Certificates

Use your own SSL certificates:

sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  -v /etc/rancher/ssl/cert.pem:/etc/rancher/ssl/cert.pem \
  -v /etc/rancher/ssl/key.pem:/etc/rancher/ssl/key.pem \
  rancher/rancher:latest \
  --no-cacerts

Private CA Certificates

If using certificates from a private CA:

sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  -v /etc/rancher/ssl/cacerts.pem:/etc/rancher/ssl/cacerts.pem \
  rancher/rancher:latest

Behind a Proxy

Configure proxy settings:

sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  -e HTTP_PROXY="http://proxy.example.com:8080" \
  -e HTTPS_PROXY="http://proxy.example.com:8080" \
  -e NO_PROXY="localhost,127.0.0.1,10.0.0.0/8" \
  rancher/rancher:latest

Air-Gapped Installation

For environments without internet access:

# Save Rancher image
sudo docker pull rancher/rancher:v2.13.3
sudo docker save rancher/rancher:v2.13.3 > rancher-image.tar

# Transfer to air-gapped host and load
sudo docker load < rancher-image.tar

# Run Rancher
sudo docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:v2.13.3

Container Management

View Logs

View Rancher container logs:

sudo docker logs -f <container_id>

Stop Rancher

Stop the Rancher container:

sudo docker stop <container_id>

Start Rancher

Restart a stopped container:

sudo docker start <container_id>

Remove Rancher

Completely remove Rancher:

sudo docker stop <container_id>
sudo docker rm <container_id>

To also remove data:

sudo rm -rf /var/lib/rancher

Upgrading Single-Node Installation

Limitations

Single-node Docker installations have several limitations:

• No high availability - Single point of failure
• No automatic failover - Downtime during host failures
• Limited scalability - Cannot scale beyond one node
• Manual upgrades - No rolling updates
• No Kubernetes integration - Does not leverage Kubernetes features
• Not production-ready - Not covered under Rancher Support SLA

For production use, migrate to a Kubernetes-based installation with high availability.

Resource Requirements by Use Case

Development/Testing

• Managing 1-5 clusters
• 2 vCPUs, 4 GB RAM, 20 GB disk

Demo/POC

• Managing 5-15 clusters
• 4 vCPUs, 8 GB RAM, 50 GB disk

Small Production (Not Recommended)

• Managing 15-50 clusters
• 8 vCPUs, 16 GB RAM, 100 GB disk
• Consider migrating to HA deployment

Troubleshooting

Container Won’t Start

Check logs for errors:

sudo docker logs <container_id>

Common issues:

• Port conflicts (80/443 already in use)
• Insufficient permissions
• Docker daemon not running

Cannot Access UI

Verify container is running:

sudo docker ps | grep rancher

Check firewall rules:

# Ubuntu/Debian
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# RHEL/CentOS
sudo firewall-cmd --add-port=80/tcp --permanent
sudo firewall-cmd --add-port=443/tcp --permanent
sudo firewall-cmd --reload

Performance Issues

Check container resource usage:

sudo docker stats <container_id>

Increase host resources if CPU or memory is constrained.

Best Practices

• Use persistent volumes (-v /opt/rancher:/var/lib/rancher) to preserve data
• Set --restart=unless-stopped to survive reboots
• Regularly backup the /var/lib/rancher directory
• Pin to a specific version tag for reproducibility
• Use SSL certificates from a trusted CA for production-like testing
• Monitor resource usage and scale host resources as needed
• Test upgrades in a separate environment first

Next Steps

• Import existing Kubernetes clusters
• Create new downstream clusters
• Explore Rancher features and capabilities
• Plan migration to high availability deployment for production use
• Review backup and restore procedures