Installing HNN on CentOS (Docker install)

This guide describes installing HNN on CentOS using Docker. This method will automatically download the HNN Docker container image when HNN is started for the first time. If you would prefer to install HNN without Docker, please see the instructions below.

Verify that your OS supports Docker CE

Prerequisite: install Docker

  1. To install docker, type the following commands in a terminal (x86_64 only). They are from Docker’s CentOS install instructions for installing docker-ce from Docker’s official repository.

     # get prerequisites for docker
     sudo yum install -y yum-utils device-mapper-persistent-data lvm2
     # add the repository
     sudo yum-config-manager --add-repo \
     https://download.docker.com/linux/centos/docker-ce.repo
     # install docker-ce
     sudo yum install -y docker-ce docker-ce-cli containerd.io
     # start docker
     sudo systemctl start docker
     # automatically start docker on boot
     sudo systemctl enable docker
     # verify that docker runs
     sudo docker run hello-world
    
  2. Add your user to the docker group to avoid having to run docker commands with “sudo”

     $ sudo usermod -a -G docker [username]
    
  3. Log out and back in (may need to reboot) for the group change to take effect

Prerequisite: install Docker Compose

Open a bash terminal and run these commands (from Docker Compose installation):

  $ bash -c 'sudo curl -L "https://github.com/docker/compose/releases/download/1.23.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose'
  $ sudo chmod +x /usr/local/bin/docker-compose
  $ docker-compose --version

Start HNN

  1. Clone the HNN repo using git from a terminal window. If you already have a previous version of the repository, bring it up to date with the command git pull origin master instead of the git clone command below.

     git clone https://github.com/jonescompneurolab/hnn.git
     cd hnn
    
  2. Start the Docker container using the hnn_docker.sh script. For the first time, we will pass the -u option in case there were any previous versions of the docker image on your computer. You can omit the -u option later

     ./hnn_docker.sh -u start
    
  3. The HNN GUI should show up. Make sure that you can run simulations by clicking the ‘Run Simulation’ button. This will run a simulation with the default configuration. After it completes, graphs should be displayed in the main window.
    • If the GUI doesn’t show up, check the Docker troubleshooting section (also links the bottom of this page). It may be necessary to run the xhost +local:docker command to open up permissions to display the GUI on your local machine.
  4. You can now proceed to running the tutorials at https://hnn.brown.edu/index.php/tutorials/ . Some things to note:
    • A subdirectory called “hnn_out” is created in your home directory and is where simulation results and parameter files will be saved.
  5. To quit HNN and shut down container, first press ‘Quit’ within the GUI. Then run ./hnn_docker.sh stop.

     ./hnn_docker.sh stop
    

Upgrading to a new version of HNN

To just pull the latest docker image from Docker Hub:

./hnn_docker.sh upgrade

Instead to upgrade and start the newest GUI:

./hnn_docker.sh -u start

Editing files within HNN container

You may want run commands or edit files within the container. To access a command shell in the container, start the container using ./hnn_docker.sh start in one terminal window to start hnn in the background and then run docker exec in another terminal window:

$ docker exec -ti hnn_container bash
hnn_user@hnn-container:/home/hnn_user/hnn_source_code$

If you’d like to be able to copy files from the host OS without using the shared directory, you can do so directly with docker cp.

Uninstalling HNN

If you want to remove the container and 1.6 GB HNN image, run the following commands from a terminal window.

./hnn_docker.sh uninstall

You can then remove Docker CE

sudo yum remove docker-ce

To remove all containers and images (should take minimal space after the uninstall command above):

sudo rm -rf /var/lib/docker

Troubleshooting

For errors related to Docker, please see the Docker troubleshooting section

If you run into other issues with the installation, please open an issue on our GitHub. Our team monitors these issues and will be able to suggest possible fixes.

For other HNN software issues, please visit the HNN bulletin board