DOCS: Small clean up of Docker information. Move stuff to docs from R…

…EADMEs.
geodynamics · Dec 18, 2023 · 3236338 · 3236338
1 parent 19cb524
commit 3236338
Show file tree

Hide file tree

Showing 5 changed files with 80 additions and 159 deletions.
diff --git a/docker/README-developer.md b/docker/README-developer.md
diff --git a/docker/README.md b/docker/README.md
@@ -1,119 +1,38 @@
-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 will hold a directory where all your user data can be
-  stored for use with PyLith within Docker. 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
-
-  To enable use of GUI applications, like iceweasel (Firefox), use
-
-  Linux:
-    $ xhost +local:root
-  Darwin (using Terminal application):
-    $ xhost +YOUR_IP_ADDRESS; DISPLAY=YOUR_IP_ADDRESS:0
-  For Linux and Darwin, then continue with
-    $ XSOCK=/tmp/.X11-unix
-    $ docker run -ti --volumes-from pylith-data -e DISPLAY=$DISPLAY -v $XSOCK:$XSOCK geodynamics/pylith
-
-  The container includes the following useful utilities:
-    * iceweasel (Firefox) web-browser for use with pylith_paramviewer
-    * vim text editor
-    * matplotlib Python plotting package
-
-  We do not yet include ParaView due to difficulties associated with
-  rendering on the host display outside the container. 
-
-HINT: 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 "paused" or "running" container.
-    # Find the container id
-    $ docker ps
-    # Attach to the container
-    $ docker attach CONTAINER_ID
-
-  To restart an existing container after it exited.
-    # Get the container id
-    $ docker ps -a
-    # Start and then attach to the container.
-    $ docker start CONTAINER_ID
-    $ docker attach CONTAINER_ID
-
-
-======================================================================
-Copy data to/from persistent storage volume.
-=====================================================================
-
-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 CONTAINER_ID
-
-  Attach to stopped container with a different command
-    $ docker ps -a
-    $ docker commit CONTAINERID debug_container
-    $ docker run -ti --entrypoint=bash $IMAGE -s
-
-======================================================================
-Running GUI
-======================================================================
-
+# Building Docker containers
+
+This directory holds Docker container build instructions, aka Dockerfiles.
+The images are stored in the geodynamics GitHub container registry with the URL `ghcr.io/geodynamics/pylith_installer`.
+
+To set the visibility of container images, go to `github.com/geodynamics` -> `packages` (tab) -> `settings` (right side); the visibility setting is near the bottom.
+
+## Containers
+
+- **pylith-devenv**: Linux developer environment for PyLith (contains only dependencies)
+- **pylith-binaryenv**: Linux environment for creating Linux binary package
+- **Test environments**:
+  - **centos-7**: EOL June 2024
+  - **debian-stable**:
+  - **debian-testing**:
+  - **fedora-38**:
+  - **fedora-39**:
+  - **rockylinux-8**:
+  - **rockylinux-9**:
+  - **ubuntu-20.04**: LTS
+  - **ubuntu-22.04**: LTS
+  - **ubuntu-23.04**:
+  - **ubuntu-23.10**:
+
+## Building images
+
+```bash
+cd $SRC
+docker/build.py --dockerfile=docker/ubuntu-22.04 --build --build-env=certs-doi
+```
+
+## Push images
+
+```bash
+# Linux
+pass -c PATH_TO_TOKEN
+docker push IMAGE_URL
+```
diff --git a/docs/devenv/docker/index.md b/docs/devenv/docker/index.md
@@ -1,4 +1,18 @@
-# PyLith development environment Docker image
+# PyLith development environment using Docker
+
+## 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."
+
+# PyLith development Docker image
 
 The `pylith-devenv` Docker image provides all of the dependencies and defines the environment for PyLith development.
 It is built using the Ubuntu 22.04 Linux distribution.

diff --git a/docs/devenv/docker/quickref.md b/docs/devenv/docker/quickref.md
@@ -16,3 +16,29 @@ docker cp pylith-dev-workspace:/opt/pylith/src/myfile.txt .
 # Attach to running container `pylith-dev-workspace` as root
 docker exec -it -u root pylith-dev-workspace /bin/bash
 ```
+
+## Docker images
+
+```{code-block} bash
+# List local images
+docker images
+
+# Remove docker image using id
+docker rmi IMAGE_ID
+
+# Remove docker image using tag
+docker rmi IMAGE_TAG
+```
+
+## Docker containers
+
+```{code-block} bash
+# List all docker containers
+docker ps -a
+
+# List running docker containers
+docker ps
+
+# Remove docker container
+docker rm CONTAINER_ID
+```
diff --git a/docs/devenv/docker/update.md b/docs/devenv/docker/update.md
@@ -15,4 +15,4 @@ Pulling the PyLith development environment Docker image does not update Pythia,
 
 ## Updating PETSc or PyLith
 
-See [Rebuilding PETSc and PyLith in the PyLith Developer Guide](https://pylith.readthedocs.io/en/v3.0.3/developer/contributing/rebuilding.html) for how to update PETSc and PyLith.
+See [Rebuilding PETSc and PyLith in the PyLith Developer Guide](https://pylith.readthedocs.io/en/v4.0.0/developer/contributing/rebuilding.html) for how to update PETSc and PyLith.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -15,4 +15,4 @@ Pulling the PyLith development environment Docker image does not update Pythia,

		## Updating PETSc or PyLith

		See [Rebuilding PETSc and PyLith in the PyLith Developer Guide](https://pylith.readthedocs.io/en/v3.0.3/developer/contributing/rebuilding.html) for how to update PETSc and PyLith.
		See [Rebuilding PETSc and PyLith in the PyLith Developer Guide](https://pylith.readthedocs.io/en/v4.0.0/developer/contributing/rebuilding.html) for how to update PETSc and PyLith.