Install NuPIC using Docker

go-bears edited this page Oct 1, 2015 · 36 revisions
Clone this wiki locally

One of the biggest challenges of getting NuPIC up and running is managing dependencies. By using Docker, we hope to streamline this as much as possible, and eliminate dependency hell. Docker is a virtualization method which leverages Linux containers (LXC) to create lightweight and portable environments for running code with all of the required dependencies. The nice thing about Docker is that it allows us to manage all the dependencies of the core NuPIC code with a Git-like interface. So, as the code base evolves and dependencies change, you can update the environmental dependencies in a similar way that you update your local code base.

Because Docker uses Linux containers, Docker will only run on Linux. However, other operating systems can create virtual machines to host Linux, which in turn will host the Docker container. We will show the steps for setting up NuPIC on Ubuntu and OSX below. Docker is only officially supported on Ubuntu, but Docker should also work on the following Linux distributions: Arch, Gentoo, Fedora, CentOS, and Amazon Linux (AWS).

Allan Costa, a member of the NuPIC community built a Dockerfile which we are currently using.

Install Docker

Furthermore, there is a Vagrant configuration with instructions at for running CoreOS, a linux distribution well-suited for running Docker containers. If you already have virtualbox and vagrant setup, this may be a good option for you.

For the commands below, you will need to enter these through your SSH client.

Pull the NuPIC Docker image

sudo docker pull numenta/nupic

Test it out

Run the Python unit tests:

sudo docker run numenta/nupic /usr/local/src/nupic/scripts/ -u --coverage

Run the Python HTM Network API tests:

sudo docker run numenta/nupic /usr/local/src/nupic/bin/py_region_test

You can similarly run the other tests, but it will fail the Python swarming tests, unless you install MySQL in your container.

Run the hotgym example:

sudo docker run -i -t numenta/nupic /bin/bash -c "python /usr/local/src/nupic/examples/opf/clients/hotgym/simple/"
sudo docker run -i -t numenta/nupic /bin/bash -c "python /usr/local/src/nupic/scripts/ /usr/local/src/nupic/examples/opf/experiments/multistep/hotgym/"

To access the Docker container via shell:

sudo docker run -i -t numenta/nupic /bin/bash

After running the command above, you will be inside the Docker container running numenta/nupic. You can navigate around, and edit the NuPIC code, which is located at /usr/local/src/nupic. To exit the Docker shell, type exit.

The NuPIC Trusted Builds are continuously updated as NuPIC is updated, so it's likely that your running container is already up to date. Should your running container fall behind, you can build NuPIC at any time following the usual build steps. Because the NuPIC Dockerfile builds completely from source, all of the necessary build tools are available and environment variables are set.

git pull origin master
python install

Build Your Own Docker Image

If you would like to build your own Docker image, you can do that too.

Assuming you have Vagrant installed already with a VM that has Docker installed, follow these steps:

vagrant up
vagrant ssh

Install Git to clone the NuPIC repo containing the Dockerfile:

git clone
cd nupic

Build the image:

sudo docker build -t numenta/nupic .

Docker should build the image from the Dockerfile at root. Note: you may need to increase the RAM for your VM in order for this to work. You can interact with your image in this way:

sudo docker run -i -t numenta/nupic /bin/bash

You will now be logged into the freshly built Docker image containing NuPIC and all of its dependencies. You will want to get up to speed on how to work with Docker, so be sure to read the documentation:

Update Your Docker Image

If you want to update your image, you can just rebuild it after pulling the latest NuPIC files. If you think it's worth the trouble, you can also update it from inside a container and then commit the changes to the image.

Running swarms

See for complete instructions for running swarms in Docker.