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

1. Install Docker
2. Install Docker on your host system:
3. Ubuntu/Debian:
4. curl https://releases.rancher.com/install-docker/20.10.sh | sh
   

5. RHEL/CentOS/Rocky:
6. curl https://releases.rancher.com/install-docker/20.10.sh | sh
   sudo systemctl enable docker
   sudo systemctl start docker
   

7. Verify Docker installation:
8. sudo docker version
   

9. Run Rancher Container
10. Run Rancher in a Docker container:
11. sudo docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      rancher/rancher:latest
    

12. Command breakdown:
14. Access Rancher UI
15. Wait a few minutes for Rancher to start, then access the UI:
16. https://<SERVER_IP>
    

17. For local testing:
18. https://localhost
    

19. Get Bootstrap Password
20. Retrieve the initial bootstrap password:
21. sudo docker logs <container_id> 2>&1 | grep "Bootstrap Password:"
    

22. Or get the container ID first:
23. sudo docker ps
    sudo docker logs <container_id> 2>&1 | grep "Bootstrap Password:"
    

24. Complete Initial Setup

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

1. Create a Backup
2. Back up the Rancher data directory:
3. sudo docker stop <container_id>
   sudo tar czf rancher-backup-$(date +%Y%m%d).tar.gz /var/lib/rancher
   sudo docker start <container_id>
   

4. Pull New Version
5. Download the new Rancher version:
6. sudo docker pull rancher/rancher:v2.13.3
   

7. Stop and Remove Old Container
8. sudo docker stop <container_id>
   sudo docker rm <container_id>
   

9. Run New Version
10. sudo docker run -d --restart=unless-stopped \
      -p 80:80 -p 443:443 \
      --privileged \
      -v /opt/rancher:/var/lib/rancher \
      rancher/rancher:v2.13.3
    

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