For development and testing environments, we recommend installing Rancher 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 Single Node Install with an External Load Balancer instead.

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…

Choose from the following options:

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 Linux host, and then run the minimum installation command below.

Air Gap User? Add your private registry URL before the rancher/rancher image.

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

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 SSL FAQ / 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.

  • Replace <CERT_DIRECTORY> with the directory path to your certificate file.
  • Replace <FULL_CHAIN.pem>,<PRIVATE_KEY.pem>, and <CA_CERTS> with your certificate names.

Air Gap User? Add your private registry URL before the rancher/rancher image.

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 \
	rancher/rancher:latest

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

Prerequisite: The certificate files must be in PEM format.

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.

    • Replace <CERT_DIRECTORY> with the directory path to your certificate file.
    • Replace <FULL_CHAIN.pem> and <PRIVATE_KEY.pem> with your certificate names.
  • Use the --no-cacerts as argument to the container to disable the default CA certificate generated by Rancher.

Air Gap User? Add your private registry URL before the rancher/rancher image.

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 \
	rancher/rancher:latest --no-cacerts

For production environments, you also have the options 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.

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. Replace <YOUR.DNS.NAME> with your your domain.

Air Gap User? Add your private registry URL before the rancher/rancher image.

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

Remember: 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.

What’s Next?


FAQ and Troubleshooting

How Do I Know if My Certificates are in PEM Format?

You can recognize the PEM format by the following traits:

  • The file begins with the following header:
    -----BEGIN CERTIFICATE-----
  • The header is followed by a long string of characters. Like, really long.
  • The file ends with a footer:
    -----END CERTIFICATE-----

PEM Certificate Example:

----BEGIN CERTIFICATE-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END CERTIFICATE-----

PEM Certificate Key Example:

-----BEGIN RSA PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END RSA PRIVATE KEY-----

If your key looks like the example below, see How Can I Convert My Certificate Key From PKCS8 to PKCS1?

-----BEGIN PRIVATE KEY-----
MIIGVDCCBDygAwIBAgIJAMiIrEm29kRLMA0GCSqGSIb3DQEBCwUAMHkxCzAJBgNV
... more lines
VWQqljhfacYPgp8KJUJENQ9h5hZ2nSCrI+W00Jcw4QcEdCI8HL5wmg==
-----END PRIVATE KEY-----

How Can I Convert My Certificate Key From PKCS8 to PKCS1?

If you are using a PKCS8 certificate key file, Rancher will log the following line:

ListenConfigController cli-config [listener] failed with : failed to read private key: asn1: structure error: tags don't match (2 vs {class:0 tag:16 length:13 isCompound:true})

To make this work, you will need to convert the key from PKCS8 to PKCS1 using the command below:

openssl rsa -in key.pem -out convertedkey.pem

You can now use convertedkey.pem as certificate key file for Rancher.

What is the Order of Certificates if I Want to Add My Intermediate(s)?

The order of adding certificates is as follows:

-----BEGIN CERTIFICATE-----
%YOUR_CERTIFICATE%
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
%YOUR_INTERMEDIATE_CERTIFICATE%
-----END CERTIFICATE-----

How Do I Validate My Certificate Chain?

You can validate the certificate chain by using the openssl binary. If the output of the command (see the command example below) ends with Verify return code: 0 (ok), your certificate chain is valid. The ca.pem file must be the same as you added to the rancher/rancher container. When using a certificate signed by a recognized Certificate Authority, you can omit the -CAfile parameter.

Command:
openssl s_client -CAfile ca.pem -connect rancher.yourdomain.com:443
...
    Verify return code: 0 (ok)

Advanced Options

Enable API Audit Log

The API Audit Log records all the user and system transactions made through Rancher server.

The API Audit Log writes to /var/log/auditlog inside the rancher container by default. Share that directory as a volume and set your AUDIT_LEVEL to enable the log.

See API Audit Log for more information and options.

docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /var/log/rancher/auditlog:/var/log/auditlog \
  -e AUDIT_LEVEL=1 \
  rancher/rancher:latest

Air Gap

If you are visiting this page to complete an Air Gap Installation, you must pre-pend your private registry URL to the server tag when running the installation command in the option that you choose. Add <REGISTRY.DOMAIN.COM:PORT> with your private registry URL in front of rancher/rancher:latest.

Example:

 <REGISTRY.DOMAIN.COM:PORT>/rancher/rancher:latest

Persistent Data

Rancher uses etcd as datastore. When using the Single Node Install, the embedded etcd is being used. The persistent data is at the following path in the container: /var/lib/rancher. You can bind mount a host volume to this location to preserve data on the host it is running on.

Command:
docker run -d --restart=unless-stopped \
  -p 80:80 -p 443:443 \
  -v /host/rancher:/var/lib/rancher \
  rancher/rancher:latest

Running rancher/rancher and rancher/rancher-agent on the Same Node

In the situation where you want to use a single node to run Rancher and to be able to add the same node to a cluster, you have to adjust the host ports mapped for the rancher/rancher container.

If a node is added to a cluster, it deploys the nginx ingress controller which will use port 80 and 443. This will conflict with the default ports we advice to expose for the rancher/rancher container.

Please note that this setup is not recommended for production use, but can be convenient for development/demo purposes.

To change the host ports mapping, replace the following part -p 80:80 -p 443:443 with -p 8080:80 -p 8443:443:

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