====== Running PyLith in a portable, Linux environment via Docker ======

**See the PyLith User Manual (v2.2.0) for the latest instructions.** The instructions here do not include how to use applications with graphical-user interfaces within the container.

===== What is Docker? =====


From https://www.docker.com/what-docker:

> "Docker containers wrap a piece of software in a complete filesystem that contains everything needed to run: code, runtime, system tools, system libraries – anything that can be installed on a server. This guarantees that the software will always run the same, regardless of its environment.
>
> LIGHTWEIGHT
>
> Containers running on a single machine share the same operating system kernel; they start instantly and use less RAM. Images are constructed from layered filesystems and share common files, making disk usage and image downloads much more efficient."

===== Setup (first time only) =====

==== Install Docker ====

https://www.docker.com/products/docker

==== Create container to store persistent user data ====

This container, called pylith-data,  will hold a directory where all your user data can be stored for use with PyLith within Docker. The data can persist for different versions of PyLith; that is, you can update to a newer version of PyLith and your user data will still be available. This directory is not directly accessible from your host computer. However, you can copy files to/from your host filesystem using "docker cp" (see below).

<code>
$ docker create --name pylith-data geodynamics/pylith-data
</code>


===== Run Unix shell within Docker to use PyLith. =====

<code>
$ docker run -ti --volumes-from pylith-data geodynamics/pylith
</code>

**HINT**: Within the container, you will probably want to copy the examples from the pylith-VERSION directory to the data directory, which is the persistent storage.

<code>
$ cp -R ~/pylith-VERSION/examples ~/data
</code>

  * To "pause" the container. ''Control-p Control-q''
  * To attach to a "paused" or "running" container. 
    - Get container id ''$ docker ps''
    - Attach to container ''$ docker attach CONTAINER_ID''

==== Troubleshooting ====

<code>
docker: Error response from daemon: oci runtime error: process_linux.go:330: running prestart hook 0 caused "fork/exec /usr/bin/dockerd (deleted): no such file or directory: ".
</code>

  * Restart docker.  ''$ sudo service docker restart''
  * Run docker image. ''$ docker run -ti --volumes-from pylith-data geodynamics/pylith''

===== Copy data to/from persistent storage volume. =====

These commands are run on the local host outside the container, not inside the Docker container.

  * Copy data FROM persistent storage volume TO local host
<code>
$ docker cp pylith-data:/data/pylith-user/PATH/FILENAME LOCAL_PATH
</code>
  * Copy data FROM local host TO persistent storage volume
<code>
$ docker cp LOCAL_PATH pylith-data:/data/pylith-user/PATH/
</code>

===== Docker Quick Reference =====

  * List local docker images ''$ docker images''
  * List all docker containers ''$ docker ps -a''
  * List running docker containers ''$ docker ps''
  * Remove docker container ''$ docker rm CONTAINER_ID''
  * Remove docker image ''$ docker rmi IMAGE_ID''