== 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).

{{{
$ docker create --name pylith-data geodynamics/pylith-data
}}}

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

{{{
$ docker run -ti --volumes-from pylith-data geodynamics/pylith
}}}

'''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.

{{{
$ cp -R ~/pylith-VERSION/examples ~/data
}}}

  * 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 ====

{{{
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: ".
}}}

  * 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
{{{
$ docker cp pylith-data:/data/pylith-user/PATH/FILENAME LOCAL_PATH
}}}
  * Copy data FROM local host TO persistent storage volume
{{{
$ docker cp LOCAL_PATH pylith-data:/data/pylith-user/PATH/
}}}

=== 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}}}