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 https://github.com/numenta/nupic/tree/master/coreos-vagrant 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:
docker run numenta/nupic python /usr/local/src/nupic/scripts/run_nupic_tests.py -u --coverage
Run the Python HTM Network API tests:
docker run numenta/nupic bash /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/hotgym.py"
sudo docker run -i -t numenta/nupic /bin/bash -c "python /usr/local/src/nupic/scripts/run_opf_experiment.py /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.
cd $NUPIC
git pull origin master
python setup.py 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 https://github.com/numenta/nupic.git
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: http://docs.docker.io/en/latest/
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 https://github.com/numenta/nupic/wiki/Running-Swarms#running-a-swarm-with-docker for complete instructions for running swarms in Docker.