Revision ab66cee09a0467852bf057938d068c7d7636b67e authored by Hunter Gabbard on 30 June 2017, 12:50:02 UTC, committed by Alex Nitz on 30 June 2017, 12:50:02 UTC
1 parent aab69db
docker.rst
==========================
Running PyCBC under Docker
==========================
The easiest way to start using PyCBC is to install one of our `Docker containers <https://hub.docker.com/u/pycbc/>`_. First, install the `Docker Community Edition <https://www.docker.com/community-edition>`_ for your `Mac <https://store.docker.com/editions/community/docker-ce-desktop-mac?tab=description>`_ or `Windows <https://store.docker.com/editions/community/docker-ce-desktop-windows?tab=description>`_ desktop. Docker CE installations for `Linux platforms <https://www.docker.com/community-edition#/download>`_ are also available.
To start a Docker container with no graphics, type the commands::
docker pull pycbc/pycbc-el7:latest
docker run -it pycbc/pycbc-el7:latest /bin/bash -l
This example downloads current version of the code from the `GitHub master branch. <https://github.com/ligo-cbc/pycbc>`_ Replace the string ``latest`` with one of the `PyCBC release tags <https://github.com/ligo-cbc/pycbc/releases>`_ (e.g. ``v1.7.0``) to install a container containing a released version of PyCBC. The container includes all of the required software and dependencies to run PyCBC, including a compatible version of LALSuite.
--------------------
Graphics on Mac OS X
--------------------
To start a Docker container on Mac OS X that can display graphics on Mac OS X, you must be running `XQuartz <https://www.xquartz.org/>`_ version 2.7.11 or higher. To start an X11 server, run the command::
open -a Xquartz
In the Xquartz preferences, make sure that ``Allow connections from network clients`` is checked, as shown below:
.. image:: resources/xquartz_pref.png
:width: 400 px
:align: center
Next, enable Docker to connect to your X11 server by running the commands::
ip=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}')
xhost + $ip
Finally, start the Docker container with::
docker run -e DISPLAY=${ip}:0 -it pycbc/pycbc-el7:latest /bin/bash -l
-----------------
Graphics on Linux
-----------------
To start a Docker container on Linux that can display graphics, run the commands::
docker run -e DISPLAY=${DISPLAY} -v /tmp/.X11-unix:/tmp/.X11-unix/ -it pycbc/pycbc-el7:latest /bin/bash -l
If you are having problems with this method, try `Using ssh to display graphics`_.
-------------------------------
Sharing user files and SSH keys
-------------------------------
It can be useful to share your SSH public/private key with the Docker container, for example to allow you to git push and pull from your repository on GitHub. To do this, add the argument ``-v ${HOME}/.ssh:/home/pycbc/.ssh`` to the ``docker run`` commands. You can also create e.g. a ``scratch`` directory and use the ``-v`` option to mount it in the container. This directory can be used to transfer files between the container and the host computer. The command below will start a Docker container with graphics on a Mac and share ssh keys and a ``scratch`` directory::
mkdir -p scratch
docker run -e DISPLAY=$(ifconfig en0 | grep inet | awk '$1=="inet" {print $2}'):0 -v `pwd`/scratch:/home/pycbc/scratch -v ${HOME}/.ssh:/home/pycbc/.ssh -it pycbc/pycbc-el7:latest /bin/bash -l
-----------------------------
Using SSH to display graphics
-----------------------------
If you do not have a recent version of Xquartz, or you are encountering other X11 issues, another way to run a docker container with graphics is to start a container that runs an SSH daemon and connect to that. This is also useful for trabsfering files to and from the Docker container using ``scp`` from your host computer.
If do not already have a personal ssh public/private key, first create one with the command::
ssh-keygen -t rsa
cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
Now start the docker container with::
docker run --name pycbc -d -P -v ${HOME}/.ssh:/home/pycbc/.ssh -t pycbc/pycbc-el7 tail -f /dev/null i
docker exec -u root -it pycbc /usr/bin/pycbc-sshd
And then you can connect to it with the command::
ssh -Y pycbc@127.0.0.1 -p `docker port pycbc 22 | awk -F: '{print $NF}'`
Computing file changes ...