From 3236338f0b26f8d755b7482c7174a72dccbf166f Mon Sep 17 00:00:00 2001 From: Brad Aagaard Date: Thu, 14 Dec 2023 15:01:40 -0700 Subject: [PATCH] DOCS: Small clean up of Docker information. Move stuff to docs from READMEs. --- docker/README-developer.md | 38 -------- docker/README.md | 157 ++++++++------------------------- docs/devenv/docker/index.md | 16 +++- docs/devenv/docker/quickref.md | 26 ++++++ docs/devenv/docker/update.md | 2 +- 5 files changed, 80 insertions(+), 159 deletions(-) delete mode 100644 docker/README-developer.md diff --git a/docker/README-developer.md b/docker/README-developer.md deleted file mode 100644 index 1b359a6..0000000 --- a/docker/README-developer.md +++ /dev/null @@ -1,38 +0,0 @@ -# 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/docker/README.md b/docker/README.md index f9485b0..c1ba747 100644 --- 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 index a652e20..7ad497d 100644 --- 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 index 4cac8bd..b573e12 100644 --- 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 index fdc5ca8..d88b560 100644 --- 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.