Merge pull request #70 from baagaard-usgs/update-test-containers

More updates to Docker information

Makefile.am

@@ -24,25 +24,24 @@ EXTRA_DIST = \
 	NEWS.md \
 	README.md \
 	configure.ac \
-	docker/README \
-	docker/README-developer \
+	docker/README.md \
 	docker/builder.py \
 	docker/centos-7 \
 	docker/rockylinux-8 \
 	docker/debian-stable \
 	docker/debian-testing \
-	docker/fedora-35 \
-	docker/fedora-36 \
-	docker/fedora-37 \
-	docker/ubuntu-18.04 \
+	docker/fedora-38 \
+	docker/fedora-39 \
 	docker/ubuntu-20.04 \
 	docker/ubuntu-22.04 \
-	docker/ubuntu-22.10 \
+	docker/ubuntu-23.04 \
+	docker/ubuntu-23.10 \
 	packager/build.py \
 	packager/setup_macos.sh \
 	packager/setup_linux.sh \
 	packager/build.py \
-	packager/make_petscdist.sh
+	packager/make_petscdist.sh \
+	packager/README.md
 
 
 dist_noinst_SCRIPTS = \

README.md

@@ -12,7 +12,7 @@ This installer builds the current PyLith release and its dependencies from sourc
 ## Documentation
 
 * [Development version](https://pylith-installer.readthedocs.io/en/latest/)
-* [Stable version](heeps://pylith-installer.readthedocs.io/en/v3.0.3-0)
+* [Stable version](heeps://pylith-installer.readthedocs.io/en/v4.0.0-0)
 * See the corresponding version of the PyLith manual for v2.2.2 and earlier
 
 ## Author

developer/release-announcement.md

@@ -1,14 +1,13 @@
-We are pleased to announce release of PyLith Installer version 3.0.3-0.
+We are pleased to announce release of PyLith Installer version 4.0.0-0.
 
 Please submit bug reports via GitHub issues:
     https://github.com/geodynamics/pylith_installer/issues
 
-PyLith Installer is free software.  See the file COPYING for copying
-conditions.
+PyLith Installer is free software.  See the file LICENSE.md for licensing information.
 
 PyLith Installer is a utility for building PyLith and its dependencies
 from source on Unix flavored operating systems.
 
 You can download the installer from https://geodynamics.org/resources/pylith.
 
-Instructions are online at https://pylith-installer.readthedocs.io/en/v3.0.3-0.
+Instructions are online at https://pylith-installer.readthedocs.io/en/v4.0.0-0.

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
+```

docs/conf.py

@@ -21,7 +21,7 @@
 author = 'Brad T. Aagaard'
 
 # The full version, including alpha/beta/rc tags
-release = 'v3.0.3-1'
+release = 'v4.0.0-0'
 
 
 # -- General configuration ---------------------------------------------------

docs/configs/macos.md

@@ -25,7 +25,7 @@ PREFIX=$HOME/pylith
 # Define PETSc options
 petsc_options="--download-chaco=1 --download-ml --download-f2cblaslapack --with-fc=0 --with-hwloc=0 --with-ssl=0 --with-x=0 --with-c2html=0 --with-lgrind=0"
 #
-${HOME}/src/pylith/pylith_installer-3.0.3-0/configure  \
+${HOME}/src/pylith/pylith_installer-4.0.0-0/configure  \
     --prefix=${PREFIX} \
     --enable-force-install \
     --with-fetch=curl \

docs/devenv/configs.md

@@ -52,7 +52,7 @@ We use the following directory structure:
 
 ```{code-block} console
 pylith-developer/
-├── pylith_installer-3.0.3-0 # source code for the installer
+├── pylith_installer-4.0.0-0 # source code for the installer
 ├── build-debug # top-level directory for building with debugging
 └── pylith-debug # directory where PyLith and other CIG code is installed by installer
 ```
@@ -96,7 +96,7 @@ mkdir -p $PYLITH_DIR
 cd $PYLITH_DIR
 
 # Place the installer source code tarball in $PYLITH_DIR and then unpack the tarball.
-tar -xf pylith_installer-3.0.3-0.tar.gz
+tar -xf pylith_installer-4.0.0-0.tar.gz
 ```
 
 ## Linux
@@ -126,7 +126,7 @@ Configure the installer.
 ```{code-block} bash
 mkdir $PYLITH_DIR/build-debug
 cd $PYLITH_DIR/build-debug
-$PYLITH_DIR/pylith_installer-3.0.3-0/configure \
+$PYLITH_DIR/pylith_installer-4.0.0-0/configure \
     --enable-developer \
     --with-debugging \
     --with-pylith-git=$PYLITH_BRANCH \
@@ -182,7 +182,7 @@ Configure the installer.
 ```{code-block} bash
 mkdir $PYLITH_DIR/build-debug
 cd $PYLITH_DIR/build-debug
-${HOME}/src/pylith/pylith_installer-3.0.3-0/configure  \
+${HOME}/src/pylith/pylith_installer-4.0.0-0/configure  \
     --enable-developer \
     --with-debugging \
     --with-pylith-git=$PYLITH_BRANCH \

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.

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
+```

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.

packager/README.md

@@ -1,9 +1,10 @@
+# Binary packaging
+
 Binary version is distributed via tarballs that are generated using
 the build.py script.
 
 `export SSL_CERT_FILE="$CERT_PATH/$CERT_FILE"  REQUESTS_CA_BUNDLE="$CERT_PATH/$CERT_FILE"`
 
-
 ## Linux
 
 1. `docker volume create pylith-binary`
@@ -21,4 +22,4 @@ the build.py script.
 1. `cd ~/scratch/build/pylith-binary`
 2. `mkdir src && pushd src && ln -s $HOME/src/pylith_installer && popd`
 3. x86_64: `src/pylith_installer/packager/build.py --base-dir=`pwd` --make-threads=8 --macos-target=10.15 --setup`
-3. arm64: `src/pylith_installer/packager/build.py --base-dir=`pwd` --make-threads=32 --macos-target=11.0 --setup`
+4. arm64: `src/pylith_installer/packager/build.py --base-dir=`pwd` --make-threads=32 --macos-target=11.0 --setup`