Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
Running Rancher locally (with two hosts) using MacOS Docker and VirtualBox


Rancher is an open source project that provides a complete platform for operating Docker in production. It provides infrastructure services such as multi-host networking, global and local load balancing, and volume snapshots.

This documentation describes how to run Rancher localy for development and evaluation propuses.

I'm using Docker for OSX (native) but even for this to work you will need to install VirtualBox.

Launching Management Rancher Server

To start the Rancher server simply type the followig command

$ docker run -d --restart=unless-stopped -p 8080:8080 rancher/server

Start monitoring the Rancher Server logs

The Rancher Server will take a while to statup you can monitor the progress by seeing whats happening in the logs.

$ docker logs <replace with rancher server run id>

Connection to the Rancher Server

Open your browser and connect to http://localhost:8080


If can't connect to Rancher probably it's still booting up, check the logs or wait a few seconds before trying to reload the page.

Adding hosts

Rancher server connects and controls hosts, for that you will need to install the rancher agent on each one of the hosts.

For this example we will be using Virtual Box to provide the two hosts that will be controlled by our Rancher Server.

Get local machine IP

$ sudo ipconfig getifaddr en0

Launching the hosts

Let's start two hosts, one called rancher01 and the other called rancher02

$ docker-machine create -d virtualbox --virtualbox-boot2docker-url rancher01

$ docker-machine create -d virtualbox --virtualbox-boot2docker-url rancher02

Rancher web interface: Add Host

Go to the Web interface and click Infrastructure -> Hosts and copy the line bellow bullet point 5 that says:

sudo docker run -e CATTLE_AGENT_IP=""  -d --privileged -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/rancher:/var/lib/rancher rancher/agent:v1.1.0 http://localhost:8080/v1/scripts/F3261934FB124468FE54:1481284800000:w5J8IhAGj4cHQ8ejCXx52dDBF0

In the copied code snippet replace any mention of localhost with your local IP, for my case is so I will get something like:

sudo docker run -e CATTLE_AGENT_IP=""  -d --privileged -v /var/run/docker.sock:/var/run/docker.sock -v /var/lib/rancher:/var/lib/rancher rancher/agent:v1.1.0

Running Rancher Agent in the new Hosts

On each host paste the agent code snippet that you modified with your IP:

$ docker-machine ssh rancher01
$ docker-machine ssh rancher02


If you don't see the new Hosts appearing on the Rancher Server > Hosts page use docker logs <id of the running machine> to inspect that happend to the agent, and see if he was able to connect to Rancher Server.

Here is the example of an error:

INFO: Running Agent Registration Process, CATTLE_URL=
INFO: Attempting to connect to:
INFO: is accessible
INFO: Inspecting host capabilities
INFO: Boot2Docker: false
INFO: Host writable: true
INFO: Token: xxxxxxxx
INFO: Running registration
Traceback (most recent call last):
  File "./", line 11, in <module>
  File "/usr/local/lib/python2.7/dist-packages/", line 45, in from_env
    return gdapi.from_env(prefix=prefix, factory=Client, **kw)
  File "/usr/local/lib/python2.7/dist-packages/", line 613, in from_env
    return _from_env(prefix=prefix, factory=factory, **args)
  File "/usr/local/lib/python2.7/dist-packages/", line 632, in _from_env
    return factory(**result)
  File "/usr/local/lib/python2.7/dist-packages/", line 12, in __init__
    super(Client, self).__init__(*args, **kw)
  File "/usr/local/lib/python2.7/dist-packages/", line 197, in __init__
  File "/usr/local/lib/python2.7/dist-packages/", line 315, in _load_schemas
    response = self._get_response(self._url)
  File "/usr/local/lib/python2.7/dist-packages/", line 264, in _get_response
  File "/usr/local/lib/python2.7/dist-packages/requests/", line 501, in get
    return self.request('GET', url, **kwargs)
  File "/usr/local/lib/python2.7/dist-packages/requests/", line 488, in request
    resp = self.send(prep, **send_kwargs)
  File "/usr/local/lib/python2.7/dist-packages/requests/", line 609, in send
    r = adapter.send(request, **kwargs)
  File "/usr/local/lib/python2.7/dist-packages/requests/", line 487, in send
    raise ConnectionError(e, request=request)
requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8080): Max retries exceeded with url: /v1 (Caused by NewConnectionError('<requests.packages.urllib3.connection.HTTPConnection object at 0x7fa3bfc08810>: Failed to establish a new connection: [Errno 111] Connection refused',))

You can see that the agent tried to connect to found the server but when tried to register if failed.

The solution is go to Rancher Server (https://localhost:8080) Admin -> Settings and there change the Host Registration URL.

Select Something else and type replace your local machines IP address.


This comment has been minimized.

Copy link

@DirtyyDogg95 DirtyyDogg95 commented Jun 14, 2019

nice man thanks


This comment has been minimized.

Copy link

@seshun seshun commented Aug 23, 2020

works on my catalina, thanks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.