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.
COMPACT
ROW_FORMAT
is Dynamic
Note: Currently, Docker for Windows and Docker for Mac are not supported.
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.
On the Linux machine with Docker installed, the command to start Rancher is simple.
$ sudo docker run -d --restart=unless-stopped -p 8080:8080 rancher/server
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.
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.
$ sudo docker run -d --restart=unless-stopped -p 8080:8080 \
-v /dir_that_contains_the_cert/cert.crt:/ca.crt rancher/server
You can check that the ca.crt
was passed to Rancher server container successfully by checking the logs of the rancher server container.
$ docker logs <server_container_id>
In the beginning of the logs, there will be confirmation that the ldap.crt
was added correctly.
DEFAULT_CATTLE_RANCHER_COMPOSE_WINDOWS_URL=https://releases.rancher.com/compose/beta/latest/rancher-compose-windows-386.zip
Adding ca.crt to Certs.
Updating certificates in /etc/ssl/certs... 1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d....
done.
done.
[BOOTSTRAP] Starting Cattle
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.
$ sudo docker run -d -v <host_vol>:/var/lib/mysql --restart=unless-stopped -p 8080:8080 rancher/server
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.
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.
hostname or IP of MySQL instance
3306
Name of Database
Username
Password
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.
> CREATE DATABASE IF NOT EXISTS cattle COLLATE = 'utf8_general_ci' CHARACTER SET = 'utf8';
> GRANT ALL ON cattle.* TO 'cattle'@'%' IDENTIFIED BY 'cattle';
> GRANT ALL ON cattle.* TO 'cattle'@'localhost' IDENTIFIED BY 'cattle';
After the database and user is created, launch rancher server with the environment variables.
$ sudo docker run -d --restart=unless-stopped -p 8080:8080 \
-e CATTLE_DB_CATTLE_MYSQL_HOST=<hostname or IP of MySQL instance> \
-e CATTLE_DB_CATTLE_MYSQL_PORT=<port> \
-e CATTLE_DB_CATTLE_MYSQL_NAME=<Name of Database> \
-e CATTLE_DB_CATTLE_USERNAME=<Username> \
-e CATTLE_DB_CATTLE_PASSWORD=<Password> \
rancher/server
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.
$ sudo vi /etc/default/docker
In the file, edit the #export http_proxy="http://127.0.0.1:3128/"
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.
$ sudo docker run -d \
-e http_proxy=<proxyURL> \
-e https_proxy=<proxyURL> \
-e no_proxy="localhost,127.0.0.1" \
-e NO_PROXY="localhost,127.0.0.1" \
--restart=unless-stopped -p 8080:8080 rancher/server
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.