Quick Start Guide

Get Rancher up and running in minutes with this quick start guide

Get Started in Minutes

This quick start guide will help you deploy Rancher Server and create your first Kubernetes cluster. This is the fastest way to evaluate Rancher for development or testing.

This quick start guide is intended for development and testing purposes only. For production deployments, see the Installation Guide.

Prerequisites

Before you begin, ensure you have:

• A Linux server or VM with Docker installed
• At least 4GB of RAM
• A supported Linux distribution (see Support Matrix)
• Ports 80 and 443 open and available

For detailed system requirements, see the Installation Requirements.

Step 1: Install Rancher Server

1. Run the Rancher Docker Container

   Execute the following command to start Rancher Server:

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

   The --privileged flag is required for Rancher to function properly. The --restart=unless-stopped flag ensures Rancher automatically restarts if the container stops.

   This command will:

   • Download the latest Rancher image
   • Start Rancher on ports 80 (HTTP) and 443 (HTTPS)
   • Configure automatic restart on failure
2. Verify the Container is Running

   Check that the Rancher container is running:

   docker ps
   

   You should see output similar to:

   CONTAINER ID   IMAGE             COMMAND           CREATED          STATUS          PORTS
   abc123def456   rancher/rancher   "entrypoint.sh"   30 seconds ago   Up 29 seconds   0.0.0.0:80->80/tcp, 0.0.0.0:443->443/tcp
   
3. Wait for Rancher to Start

   Rancher may take a few minutes to fully initialize. You can check the logs:

   docker logs -f <container-id>
   

   Wait until you see messages indicating that Rancher is ready to serve requests.

Step 2: Access the Rancher UI

1. Open Rancher in Your Browser

   Navigate to:

   https://localhost
   

   You’ll see a certificate warning because Rancher uses a self-signed certificate by default. This is normal for development environments. Click through the warning to proceed.

2. Get the Bootstrap Password

   On first access, Rancher will prompt you for the bootstrap password. Retrieve it from the container logs:

   docker logs <container-id> 2>&1 | grep "Bootstrap Password:"
   

   Copy the password shown in the output.

3. Set Your Admin Password

   Enter the bootstrap password and set your own admin password. Make sure to choose a strong password.

   Save your admin password securely. You’ll need it to access Rancher in the future.

4. Configure the Rancher Server URL

   Set the Rancher Server URL. For local development, you can use:

   https://localhost
   

   For production or remote access, use your server’s hostname or IP address.

Step 3: Explore the Rancher Dashboard

Once logged in, you’ll see the Rancher dashboard with several key sections:

Cluster Management

View and manage all your Kubernetes clusters from a centralized location.

Continuous Delivery

Deploy applications using GitOps workflows with Fleet.

Apps & Marketplace

Browse and deploy applications from Helm charts.

User Settings

Configure authentication, API keys, and user preferences.

Step 4: Create Your First Cluster

1. Navigate to Cluster Management

   From the main dashboard, click on Cluster Management in the left sidebar.

2. Click 'Create' to Add a Cluster

   You’ll see several options for creating clusters:

   • Custom - Register existing Kubernetes clusters
   • RKE2/K3s - Provision new clusters
   • Cloud Providers - Create clusters on AKS, EKS, or GKE
   • Import - Import existing clusters
3. Choose Your Cluster Type

   For a quick start, select Custom to explore the local cluster that Rancher creates automatically:

   The “local” cluster is where Rancher Server itself runs. In development environments, you can use this cluster to deploy test workloads.

4. Explore the Cluster

   Click on the local cluster to explore:

   • View cluster resources (nodes, pods, services)
   • Deploy workloads
   • Configure monitoring and logging
   • Access kubectl shell
   • Download kubeconfig

Step 5: Deploy Your First Workload

1. Access the Cluster Explorer

   From the cluster view, click Explore to open the Cluster Explorer.

2. Create a Deployment

   1. Navigate to Workload > Deployments
   2. Click Create
   3. Choose a name (e.g., “nginx-demo”)
   4. Set the container image to nginx:latest
   5. Configure port 80
   6. Click Create
3. Expose the Deployment

   Create a service to access your deployment:

   1. Navigate to Service Discovery > Services
   2. Click Create
   3. Select your deployment
   4. Choose service type (e.g., NodePort)
   5. Click Create
4. Access Your Application

   Once the service is created, you can access your application using the NodePort or other configured method.

Next Steps

Congratulations! You’ve successfully deployed Rancher and created your first workload. Here’s what to explore next:

Production Installation

Learn how to deploy Rancher for production with high availability

Cluster Provisioning

Provision new Kubernetes clusters on various platforms

Authentication Setup

Configure external authentication providers

GitOps with Fleet

Deploy applications using GitOps workflows

Troubleshooting

Can't access Rancher UI

Check if the container is running:

docker ps

View container logs:

docker logs <container-id>

Verify ports are not in use:

sudo netstat -tulpn | grep -E ':80|:443'

Certificate warnings

Rancher uses self-signed certificates by default. For development, you can safely bypass the browser warning. For production, configure proper SSL/TLS certificates.

Forgot admin password

If you lose your admin password, you can reset it using the Rancher container:

docker exec -ti <container-id> reset-password

Performance issues

Ensure your system meets the minimum requirements:

• 4GB RAM minimum (8GB recommended)
• 2 CPU cores minimum
• Sufficient disk space for images and data

Clean Up

To remove Rancher and clean up:

# Stop the container
docker stop <container-id>

# Remove the container
docker rm <container-id>

# Remove the image (optional)
docker rmi rancher/rancher

Removing the container will delete all Rancher data unless you’ve configured persistent volumes.

Additional Resources

• Rancher Documentation
• Rancher Forums
• Rancher Slack
• GitHub Repository