Install Rancher Docker

/ Comments off
These docs are for Rancher v1.1, for the current 1.6 docs, see here. If you are looking for Rancher 2.x docs, see here.

Installing Rancher Server (Single Node)

Rancher is deployed as a set of Docker containers. Running Rancher is a simple as launching two containers. One container as the management server and another container on a node as an agent.

I like Rancher OS because it is minimal and designed exactly with docker in mind. Rancher OS is quick and even offers a special proxmox ISO with the proxmox agent preinstalled (which among other things, lets you see the VMs IP address from the proxmox GUI). From Rancher’s Booting from ISO docs, install the Proxmox VE ISO (latest download). Rancher is deployed as a set of Docker containers. Running Rancher is a simple as launching two containers. One container as the management server and another container on a node as an agent. Any modern Linux distribution that supports Docker 1.10.3. RancherOS, Ubuntu, RHEL/CentOS 7 are more heavily tested. Rancher docker install scripts are not working anymore on RHEL 7.x #31132. Closed brutus333 opened this issue Feb 4, 2021 15 comments Closed.


Install Rancher Docker
  • Any modern Linux distribution that supports Docker 1.10.3. RancherOS, Ubuntu, RHEL/CentOS 7 are more heavily tested.
    • For RHEL/CentOS, the default storage driver, i.e. devicemapper using loopback, is not recommended by Docker. Please refer to the Docker documentation on how to change it.
  • 1GB RAM
  • MySQL server should have a max_connections setting > 150
    • MYSQL Configuration Requirements
      • Option 1: Run with Antelope with default of COMPACT
      • Option 2: Run MySQL 5.7 with Barracuda where the default ROW_FORMAT is Dynamic

Note: Currently, Docker for Windows and Docker for Mac are not supported.

Rancher Server Tags

The rancher/server:latest tag will be our stable release builds, which Rancher recommends for deployment in production. For each minor release tag, we will provide documentation for the specific version.

If you are interested in trying one of our latest development builds which will have been validated through our CI automation framework, please check our releases page to find the latest development release tag. These releases are not meant for deployment in production. All development builds will be appended with a *-pre{n} suffix to denote that it’s a development release.

Launching Rancher Server

On the Linux machine with Docker installed, the command to start Rancher is simple.

Rancher UI

The UI and API will be available on the exposed port 8080. After the docker image is downloaded, it will take a minute or two before Rancher has successfully started and is available to view.

Navigate to the following URL: http://<SERVER_IP>:8080. The <SERVER_IP is the public IP address of the host that is running Rancher server.

Once the UI is up and running, you can start adding hosts in the Default Cattle environment. After the hosts are added into Rancher, you can start adding services or launch templates from the Rancher catalog.

Enabling Active Directory or OpenLDAP for TLS

In order to enable Active Directory or OpenLDAP for Rancher server with TLS, the Rancher server container will need to be started with the ldap certificate. On the Linux machine that you want to launch Rancher server on, save the certificate.

Start Rancher by bind mounting the volume that has the certificate. The certificate must be called ca.crt inside the container.

You can check that the ca.crt was passed to Rancher server container successfully by checking the logs of the rancher server container.

In the beginning of the logs, there will be confirmation that the ldap.crt was added correctly.

Bind Mount MySQL Volume

If you would like to persist the database inside your container to a volume on your host, launch Rancher server by bind mounting the MySQL volume.

Rancher install docker script

With this command, the database will persist on the host. If you have an existing Rancher container and would like to bind mount the MySQL volume, the instructions are located in our upgrading documentation.

Using an external Database

If you would prefer to use an external database to run Rancher server, please follow these instructions to connect Rancher server to the database. Your database will already need to be created, but does not need any schemas created. Rancher will automatically create all the schemas related to Rancher.

The following environment variables will need to be passed within the docker run command to launch Rancher server using your external database.

  • CATTLE_DB_CATTLE_MYSQL_HOST: hostname or IP of MySQL instance

Note: The name and user of the database must already exist in order for Rancher to be able to create the database schema. Rancher will not create the database.

Here is an example of a SQL command to create a database and users.

Install Rancher Docker

After the database and user is created, launch rancher server with the environment variables.

Launching Rancher Server behind a HTTP proxy

In order to set up a HTTP proxy, the Docker daemon will need to be modified to point to the proxy. Before starting Rancher server, edit the /etc/default/docker file to point to your proxy and restart Docker.

In the file, edit the #export http_proxy='' to have it point to your proxy. Save your changes and then restart docker. Restarting Docker is different on every OS.

Note: If you are running Docker with systemd, please follow Docker’s instructions on how to configure the HTTP proxy.

In order for the Rancher catalog to load, the proxy will need to be configured and Rancher server will need to be launched with environment variables to pass in the proxy information.

If the Rancher catalog will not be used, run the Rancher server command as you normally would.

When adding hosts to Rancher, there is no additional requirements behind a HTTP proxy.

In this guide, we shall be installing Rancher across Ubuntu 18.04 LTS servers. Rancher is a Docker management utility. It is built on top Docker itself, meaning that there’s a docker container inside which Rancher runs. But there’s more to it than just that. Rancher can manage your containers not on just one node but across multiple nodes thanks to its excellent support for Kubernetes.

To follow along you will be required to have the following:

Install Rancher Docker
  • Two Ubuntu 16.04 servers with a public IP addresses one to act as Rancher admin server and the second one will be a node or a host where our application with be running.
  • Root privileges to both the servers.
  • A Free or Enterprise GitHub Account

Here’s the list of our VPS servers with their names and public IP. Yours will differ from these and to follow along just substitute the IP addresses as they appear.

The Rancher server would run on rancher-admin node and the rancher-node-01 will be controlled via this admin. Of course, for large-scale applications, there will be more than one node as a part of your infrastructure.

Step 1: Installing Docker and Rancher

Since we are using Ubuntu 16.04 LTS for our server OS, installing docker is as simple as running:

You must install docker on all the nodes not just on the Rancher admin server.

Once docker is installed everywhere, it is time to install Rancher on your chosen admin server. On your chosen server, and on that server only, pull the rancher/server image by running the following command:

This creates the Rancher container. We can now visit the public IP address at port 8080 to use the Rancher WebUI.

In our case, this address was your IP address might differ and you can also use a different port number if you like (just replace the first 8080 to the desired value.)

Step 2: Securing the Installation

The next immediate step is to secure your installation. On visiting the IP address of your Rancher server (on the specified port number as described in step 1) you will notice a warning sign beside Admin menu.

Hover your cursor over on Admin and go to Access Control option that appears under it. Once you are in Access Control menu you will be shown several options to configure your access control. These include Active Directory, LDAP, Local passwords but we will be using GitHub as it presents a much more succinct and practical use case.

If you select GitHub, then Rancher will guide you through the setting up access control via GitHub’s OAuth service. You can follow those steps or feel free to just click here and log in to GitHub account if you haven’t already, and click on Register a new application.

Fill out the application details as show in Rancher menu onto the GitHub application registration form, as shown below

Once your application is registered it will provide you with a Client ID and Client Secret. Copy them to the respective fields in your Rancher Access Control Set up and Save. After that, a new pop-up window will ask you whether or not is it okay to grant Rancher a read access to your GitHub account. Go ahead and authorize the app and our Rancher setup is now secure. Now you can log in to your Rancher UI via GitHub.

Step 3: Adding a Host

As mentioned before, Rancher is built to handle distributed systems like Kubernetes. This means a lot of nodes (virtual machines or physical servers) become the cattle and Rancher handles them. These nodes will have Docker installed on them and containers would be replicated and load balanced across multiple nodes to offer better scalability and availability.

We will be adding just one node on which we will be running our containers. Rancher comes with multiple options for automating this process for cloud providers like AWS, DigitalOcean, Azure and Packet we will be going to use the custom option as it has the most generic approach which would work on any of these platforms as well.

Go to Infrastructure → Hosts → Add Host and Select Custom as your choice.

Since we have already created a second VPS, which will be our cattle node with Docker installed on it, we can enter this node’s public IP in the Rancher Add Host form up as shown below:

Install Rancher Docker Container

That will generate a command with credentials that you are supposed to run on your worker node to connect it to your Rancher server. The command will fetch a few docker images to run to make administration easier.

Install Rancher Docker Command

Once that is done, you have your new host added and listed in your Rancher UI.

Step 4: Running containers

Containers are our fundamental unit of deployment here. Rancher treats docker containers as first-class citizens. Even its own components are segregated into different containerized apps.

If you go to Infrastructure → Containers → Add Container, you can see that it has a pretty UI to configure your container according to your application or microservice’s need. For example, if I need a web server for my Front-End UI I can do so by using Ubuntu 16.04’s docker image and mapping port 80 on the host to port 80 on the container and later installing your front-end app in it.

Rancher Install Docker Script

Furthermore, if you scroll down you will get more options on Networking, Storage, Security, etc. We encourage you to tweak these settings and to experiment with them. We will, however, do just one thing, ensure that interactive terminal is available so we can start a user session inside the container.

And now click create and you are done with the deployment.

This is where the real exploration would begin. Rancher will monitor resource utilization for you, and present it to you in a visually intuitive way.

You can click on the 3 vertical ellipses (shown by the arrow) you get the option to start, stop or delete the container along with a really useful option of executing the shell. Yes, you can open up a terminal straight into the container from your Web UI!


It is really hard to use Rancher and not get addicted to it. If you are an aspiring DevOps or if you are a small team trying to handle a massive application, Rancher offers an easy to use and intuitive UI to better understand and manage your infrastructure.