Installing Rancher on a Single Node Using Docker

danger

Docker installs are not supported in production environments. These instructions are provided for testing and development purposes only. Please don’t use this method to install Rancher in production environments.

Rancher can be installed by running a single Docker container.

In this installation scenario, you’ll install Docker on a single Linux host, and then deploy Rancher on your host using a single Docker container.

Want to use an external load balancer?

See Docker Install with an External Load Balancer instead.

A Docker installation of Rancher is recommended only for development and testing purposes. The ability to migrate Rancher to a high-availability cluster depends on the Rancher version:

The Rancher backup operator can be used to migrate Rancher from the single Docker container install to an installation on a high-availability Kubernetes cluster. For details, refer to the documentation on migrating Rancher to a new cluster.

Privileged Access for Rancher

When the Rancher server is deployed in the Docker container, a local Kubernetes cluster is installed within the container for Rancher to use. Because many features of Rancher run as deployments, and privileged mode is required to run containers within containers, you will need to install Rancher with the --privileged option.

Requirements for OS, Docker, Hardware, and Networking

Make sure that your node fulfills the general installation requirements.

1. Provision Linux Host

Provision a single Linux host according to our Requirements to launch your Rancher server.

2. Choose an SSL Option and Install Rancher

For security purposes, SSL (Secure Sockets Layer) is required when using Rancher. SSL secures all Rancher network communication, like when you login or interact with a cluster.

Do you want to..

• Use a proxy? See HTTP Proxy Configuration
• Configure custom CA root certificate to access your services? See Custom CA root certificate
• Complete an Air Gap Installation? See Air Gap: Docker Install
• Record all transactions with the Rancher API? See API Auditing

Choose from the following options:

• Option A: Default Rancher-generated Self-signed Certificate
• Option B: Bring Your Own Certificate, Self-signed
• Option C: Bring Your Own Certificate, Signed by a Recognized CA
• Option D: Let’s Encrypt Certificate
• Option E: Localhost tunneling, no Certificate

Option A: Default Rancher-generated Self-signed Certificate

If you are installing Rancher in a development or testing environment where identity verification isn’t a concern, install Rancher using the self-signed certificate that it generates. This installation option omits the hassle of generating a certificate yourself.

Log into your host, and run the command below:

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

Option B: Bring Your Own Certificate, Self-signed

In development or testing environments where your team will access your Rancher server, create a self-signed certificate for use with your install so that your team can verify they’re connecting to your instance of Rancher.

Prerequisites:

Create a self-signed certificate using OpenSSL or another method of your choice.

• The certificate files must be in PEM format.
• In your certificate file, include all intermediate certificates in the chain. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

After creating your certificate, run the Docker command below to install Rancher. Use the -v flag and provide the path to your certificates to mount them in your container.

Log into your host, and run the command below:

docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /<CERT_DIRECTORY>/<FULL_CHAIN.pem>:/etc/rancher/ssl/cert.pem \
  -v /<CERT_DIRECTORY>/<PRIVATE_KEY.pem>:/etc/rancher/ssl/key.pem \
  -v /<CERT_DIRECTORY>/<CA_CERTS.pem>:/etc/rancher/ssl/cacerts.pem \
  --privileged \
  rancher/rancher:latest

Option C: Bring Your Own Certificate, Signed by a Recognized CA

In production environments where you’re exposing an app publicly, you would use a certificate signed by a recognized CA so that your user base doesn’t encounter security warnings.

The Docker install is not recommended for production. These instructions are provided for testing and development purposes only.

Prerequisites:

• The certificate files must be in PEM format.
• In your certificate file, include all intermediate certificates provided by the recognized CA. Order your certificates with your certificate first, followed by the intermediates. For an example, see Certificate Troubleshooting.

After obtaining your certificate, run the Docker command below.

• Use the -v flag and provide the path to your certificates to mount them in your container. Because your certificate is signed by a recognized CA, mounting an additional CA certificate file is unnecessary.
• Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.

Log into your host, and run the command below:

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

Option D: Let’s Encrypt Certificate

caution

Let’s Encrypt provides rate limits for requesting new certificates. Therefore, limit how often you create or destroy the container. For more information, see Let’s Encrypt documentation on rate limits.

For production environments, you also have the option of using Let’s Encrypt certificates. Let’s Encrypt uses an http-01 challenge to verify that you have control over your domain. You can confirm that you control the domain by pointing the hostname that you want to use for Rancher access (for example, rancher.mydomain.com) to the IP of the machine it is running on. You can bind the hostname to the IP address by creating an A record in DNS.

The Docker install is not recommended for production. These instructions are provided for testing and development purposes only.

Prerequisites:

• Let’s Encrypt is an Internet service. Therefore, this option cannot be used in an internal/air gapped network.
• Create a record in your DNS that binds your Linux host IP address to the hostname that you want to use for Rancher access (rancher.mydomain.com for example).
• Open port TCP/80 on your Linux host. The Let’s Encrypt http-01 challenge can come from any source IP address, so port TCP/80 must be open to all IP addresses.

After you fulfill the prerequisites, you can install Rancher using a Let’s Encrypt certificate by running the following command.

Log into your host, and run the command below:

docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:latest \
  --acme-domain <YOUR.DNS.NAME>

Option E: Localhost tunneling, no Certificate

If you are installing Rancher in a development or testing environment where you have a localhost tunneling solution running, such as ngrok, avoid generating a certificate. This installation option doesn’t require a certificate.

• You will use --no-cacerts in the argument to disable the default CA certificate generated by Rancher.

Log into your host, and run the command below:

docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  --privileged \
  rancher/rancher:latest \
  --no-cacerts

Advanced Options

When installing Rancher on a single node with Docker, there are several advanced options that can be enabled:

• Custom CA Certificate
• API Audit Log
• TLS Settings
• Air Gap
• Persistent Data
• Running rancher/rancher and rancher/rancher-agent on the Same Node

Refer to this page for details.

Troubleshooting

Refer to this page for frequently asked questions and troubleshooting tips.

What’s Next?

• Recommended: Review Single Node Backup and Restore. Although you don’t have any data you need to back up right now, we recommend creating backups after regular Rancher use.
• Create a Kubernetes cluster: Provisioning Kubernetes Clusters.