Merge pull request #8794 from tdonohue/update_postgres_docker

Update Postgres Docker scripts to build/tag image automatically
2025-10-07 18:14:26 +00:00 · 2023-04-24 17:14:10 -05:00
parent fea4067464 f1f4fe4cdf
commit 74e3d10326
11 changed files with 320 additions and 73 deletions
--- a/.github/workflows/docker.yml
+++ b/.github/workflows/docker.yml
@@ -196,3 +196,60 @@ jobs:
          # Use tags / labels provided by 'docker/metadata-action' above
          tags: ${{ steps.meta_build_solr.outputs.tags }}
          labels: ${{ steps.meta_build_solr.outputs.labels }}
+
+      ###########################################################
+      # Build/Push the 'dspace/dspace-postgres-pgcrypto' image
+      ###########################################################
+      # Get Metadata for docker_build_postgres step below
+      - name: Sync metadata (tags, labels) from GitHub to Docker for 'dspace-postgres-pgcrypto' image
+        id: meta_build_postgres
+        uses: docker/metadata-action@v4
+        with:
+          images: dspace/dspace-postgres-pgcrypto
+          tags: ${{ env.IMAGE_TAGS }}
+          flavor: ${{ env.TAGS_FLAVOR }}
+
+      - name: Build and push 'dspace-postgres-pgcrypto' image
+        id: docker_build_postgres
+        uses: docker/build-push-action@v3
+        with:
+          # Must build out of subdirectory to have access to install script for pgcrypto
+          context: ./dspace/src/main/docker/dspace-postgres-pgcrypto/
+          dockerfile: Dockerfile
+          platforms: ${{ env.PLATFORMS }}
+          # For pull requests, we run the Docker build (to ensure no PR changes break the build),
+          # but we ONLY do an image push to DockerHub if it's NOT a PR
+          push: ${{ github.event_name != 'pull_request' }}
+          # Use tags / labels provided by 'docker/metadata-action' above
+          tags: ${{ steps.meta_build_postgres.outputs.tags }}
+          labels: ${{ steps.meta_build_postgres.outputs.labels }}
+
+      ###########################################################
+      # Build/Push the 'dspace/dspace-postgres-pgcrypto' image ('-loadsql' tag)
+      ###########################################################
+      # Get Metadata for docker_build_postgres_loadsql step below
+      - name: Sync metadata (tags, labels) from GitHub to Docker for 'dspace-postgres-pgcrypto-loadsql' image
+        id: meta_build_postgres_loadsql
+        uses: docker/metadata-action@v4
+        with:
+          images: dspace/dspace-postgres-pgcrypto
+          tags: ${{ env.IMAGE_TAGS }}
+          # Suffix all tags with "-loadsql". Otherwise, it uses the same
+          # tagging logic as the primary 'dspace/dspace-postgres-pgcrypto' image above.
+          flavor: ${{ env.TAGS_FLAVOR }}
+            suffix=-loadsql
+
+      - name: Build and push 'dspace-postgres-pgcrypto-loadsql' image
+        id: docker_build_postgres_loadsql
+        uses: docker/build-push-action@v3
+        with:
+          # Must build out of subdirectory to have access to install script for pgcrypto
+          context: ./dspace/src/main/docker/dspace-postgres-pgcrypto-curl/
+          dockerfile: Dockerfile
+          platforms: ${{ env.PLATFORMS }}
+          # For pull requests, we run the Docker build (to ensure no PR changes break the build),
+          # but we ONLY do an image push to DockerHub if it's NOT a PR
+          push: ${{ github.event_name != 'pull_request' }}
+          # Use tags / labels provided by 'docker/metadata-action' above
+          tags: ${{ steps.meta_build_postgres_loadsql.outputs.tags }}
+          labels: ${{ steps.meta_build_postgres_loadsql.outputs.labels }}
--- a/2
+++ b/2
@@ -31,7 +31,7 @@ ARG TARGET_DIR=dspace-installer
 COPY --from=build /install /dspace-src
 WORKDIR /dspace-src
 # Create the initial install deployment using ANT
-ENV ANT_VERSION 1.10.12
+ENV ANT_VERSION 1.10.13
 ENV ANT_HOME /tmp/ant-$ANT_VERSION
 ENV PATH $ANT_HOME/bin:$PATH
 # Need wget to install ant
--- a/Dockerfile.cli
+++ b/Dockerfile.cli
@@ -30,7 +30,7 @@ ARG TARGET_DIR=dspace-installer
 COPY --from=build /install /dspace-src
 WORKDIR /dspace-src
 # Create the initial install deployment using ANT
-ENV ANT_VERSION 1.10.12
+ENV ANT_VERSION 1.10.13
 ENV ANT_HOME /tmp/ant-$ANT_VERSION
 ENV PATH $ANT_HOME/bin:$PATH
 # Need wget to install ant
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -62,13 +62,17 @@ services:
      while (!</dev/tcp/dspacedb/5432) > /dev/null 2>&1; do sleep 1; done;
      /dspace/bin/dspace database migrate
      catalina.sh run
-  # DSpace database container
+  # DSpace PostgreSQL database container
  dspacedb:
    container_name: dspacedb
+    # Uses a custom Postgres image with pgcrypto installed
+    image: "${DOCKER_OWNER:-dspace}/dspace-postgres-pgcrypto:${DSPACE_VER:-dspace-7_x}"
+    build:
+      # Must build out of subdirectory to have access to install script for pgcrypto
+      context: ./dspace/src/main/docker/dspace-postgres-pgcrypto/
    environment:
      PGDATA: /pgdata
-    # Uses a custom Postgres image with pgcrypto installed
-    image: dspace/dspace-postgres-pgcrypto
+      POSTGRES_PASSWORD: dspace
    networks:
      dspacenet:
    ports:
@@ -77,6 +81,7 @@ services:
    stdin_open: true
    tty: true
    volumes:
+    # Keep Postgres data directory between reboots
    - pgdata:/pgdata
  # DSpace Solr container
  dspacesolr:
--- a/dspace/src/main/docker-compose/README.md
+++ b/dspace/src/main/docker-compose/README.md
@@ -1,4 +1,4 @@
-# Docker Compose Resources
+# Docker Compose files for DSpace Backend

 ***
 :warning: **THESE IMAGES ARE NOT PRODUCTION READY**  The below Docker Compose images/resources were built for development/testing only.  Therefore, they may not be fully secured or up-to-date, and should not be used in production.
@@ -6,27 +6,51 @@
 If you wish to run DSpace on Docker in production, we recommend building your own Docker images. You are welcome to borrow ideas/concepts from the below images in doing so. But, the below images should not be used "as is" in any production scenario.
 ***

-## root directory Resources
- docker-compose.yml
-  - Docker compose file to orchestrate DSpace 7 REST components
- docker-compose-cli
-  - Docker compose file to run DSpace CLI tasks within a running DSpace instance in Docker

-## dspace/src/main/docker-compose resources
+## Overview
+The scripts in this directory can be used to start the DSpace REST API (backend) in Docker.
+Optionally, the DSpace User Interface (frontend) may also be started in Docker.
+
+For additional options/settings in starting the User Interface (frontend) in Docker, see the Docker Compose
+documentation for the frontend: https://github.com/DSpace/dspace-angular/blob/main/docker/README.md
+
+## Primary Docker Compose Scripts (in root directory)
+The root directory of this project contains the primary Dockerfiles & Docker Compose scripts
+which are used to start the backend.
+
+- docker-compose.yml
+    - Docker compose file to orchestrate DSpace REST API (backend) components.
+    - Uses the `Dockerfile` in the same directory.
+- docker-compose-cli.yml
+    - Docker compose file to run DSpace CLI (Command Line Interface) tasks within a running DSpace instance in Docker. See instructions below.
+    - Uses the `Dockerfile.cli` in the same directory.
+
+Documentation for all Dockerfiles used by these compose scripts can be found in the ["docker" folder README](../docker/README.md)
+
+## Additional Docker Compose tools (in ./dspace/src/main/docker-compose)

 - cli.assetstore.yml
  - Docker compose file that will download and install a default assetstore.
+  - The default assetstore is the configurable entities test dataset. Useful for [testing/demos of Entities](#Ingest Option 2 Ingest Entities Test Data).
 - cli.ingest.yml
-  - Docker compose file that will run an AIP ingest into DSpace 7.
+  - Docker compose file that will run an AIP ingest into DSpace 7. Useful for testing/demos with basic Items.
 - db.entities.yml
-  - Docker compose file that pre-populate a database instance using a SQL dump.  The default dataset is the configurable entities test dataset.
- local.cfg
-  - Sets the environment used across containers run with docker-compose
+  - Docker compose file that pre-populate a database instance using a downloaded SQL dump.
+  - The default dataset is the configurable entities test dataset. Useful for [testing/demos of Entities](#Ingest Option 2 Ingest Entities Test Data).
+- db.restore.yml
+  - Docker compose file that pre-populate a database instance using a *local* SQL dump (hardcoded to `./pgdump.sql`)
+  - Useful for restoring data from a local backup, or [Upgrading PostgreSQL in Docker](#Upgrading PostgreSQL in Docker)
 - docker-compose-angular.yml
-  - Docker compose file that will start a published DSpace angular container that interacts with the branch.
+  - Docker compose file that will start a published DSpace User Interface container that interacts with the branch.
 - docker-compose-shibboleth.yml
  - Docker compose file that will start a *test/demo* Shibboleth SP container (in Apache) that proxies requests to the DSpace container
  - ONLY useful for testing/development. NOT production ready.
+- docker-compose-iiif.yml
+    - Docker compose file that will start a *test/demo* Cantaloupe image server container required for enabling IIIF support.
+    - ONLY useful for testing/development. NOT production ready.
+
+Documentation for all Dockerfiles used by these compose scripts can be found in the ["docker" folder README](../docker/README.md)
+

 ## To refresh / pull DSpace images from Dockerhub
 ```
@@ -55,6 +79,12 @@ docker-compose -p d7 up -d
 docker-compose -p d7 -f docker-compose.yml -f dspace/src/main/docker-compose/docker-compose-angular.yml up -d
 ```

+## Run DSpace REST and DSpace Angular from local branches
+
+*Allows you to run the backend from the "DSpace/DSpace" codebase while also running the frontend from the "DSpace/dspace-angular" codebase.*
+
+See documentation in [DSpace User Interface Docker instructions](https://github.com/DSpace/dspace-angular/blob/main/docker/README.md#run-dspace-rest-and-dspace-angular-from-local-branches).
+
 ## Run DSpace 7 REST with a IIIF Image Server from your branch
 *Only useful for testing IIIF support in a development environment*

@@ -67,7 +97,6 @@ docker-compose -p d7 -f docker-compose.yml -f dspace/src/main/docker-compose/doc
 ```

 ## Run DSpace 7 REST and Shibboleth SP (in Apache) from your branch
-
 *Only useful for testing Shibboleth in a development environment*

 This Shibboleth container uses https://samltest.id/ as an IdP (see `../docker/dspace-shibboleth/`).
@@ -143,21 +172,11 @@ The remainder of these instructions assume you are using ngrok (though other pro
        DSPACE_HOSTNAME=[subdomain].ngrok.io docker-compose -p d7 -f docker-compose.yml -f dspace/src/main/docker-compose/docker-compose-angular.yml -f dspace/src/main/docker-compose/docker-compose-shibboleth.yml up -d
        ```

-## Run DSpace 7 REST and Angular from local branches
+## Sample Test Data

-_The system will be started in 2 steps. Each step shares the same docker network._
+### Ingesting test content from AIP files

-From DSpace/DSpace
-```
-docker-compose -p d7 up -d
-```
-
-From DSpace/DSpace-angular (build as needed)
-```
-docker-compose -p d7 -f docker/docker-compose.yml up -d
-```
-
-## Ingest Option 1: Ingesting test content from AIP files into a running DSpace 7 instance
+*Allows you to ingest a set of AIPs into your DSpace instance for testing/demo purposes.* These AIPs represent basic Communities, Collections and Items.

 Prerequisites
 - Start DSpace 7 using one of the options listed above
@@ -173,8 +192,14 @@ Download a Zip file of AIP content and ingest test data
 docker-compose -p d7 -f docker-compose-cli.yml -f dspace/src/main/docker-compose/cli.ingest.yml run --rm dspace-cli
 ```

-## Ingest Option 2: Ingest Entities Test Data
-_Remove your d7 volumes if you already ingested content into your docker volumes_
+### Ingest Entities Test Data
+
+*Allows you to load Configurable Entities test data for testing/demo purposes.*
+
+Prerequisites
+- Start DSpace 7 using one of the options listed above
+- Build the DSpace CLI image if needed.  See the instructions above.
+- _Remove your d7 volumes if you already ingested content into your docker volumes_

 Start DSpace REST with a postgres database dump downloaded from the internet.
 ```
@@ -212,3 +237,85 @@ Similarly, you can see the value of any DSpace configuration (in local.cfg or ds
 # Output the value of `dspace.ui.url` from running Docker instance
 docker-compose -p d7 -f docker-compose-cli.yml run --rm dspace-cli dsprop -p dspace.ui.url
 ```
+
+NOTE: It is also possible to run CLI scripts directly on the "dspace" container (where the backend runs)
+This can be useful if you want to pass environment variables which override DSpace configs.
+```
+# Run the "./dspace database clean" command from the "dspace" container
+# Before doing so, it sets "db.cleanDisabled=false".
+# WARNING: This will delete all your data. It's just an example of how to do so.
+docker-compose -p d7 exec -e "db__P__cleanDisabled=false" dspace /dspace/bin/dspace database clean
+```
+
+## Upgrading PostgreSQL in Docker
+
+Occasionally, we update our `dspace-postgres-*` images to use a new version of PostgreSQL.
+Simply using the new image will likely throw errors as the pgdata (postgres data) directory is incompatible
+with the new version of PostgreSQL. These errors look like:
+```
+FATAL:  database files are incompatible with server
+DETAIL:  The data directory was initialized by PostgreSQL version 11, which is not compatible with this version 13.10
+```
+
+Here's how to fix those issues by migrating your old Postgres data to the new version of Postgres
+
+1. First, you must start up the older PostgreSQL image (to dump your existing data to a `*.sql` file)
+    ```
+    # This command assumes you are using the process described above to start all your containers
+    docker-compose -p d7 up -d
+    ```
+    * If you've already accidentally updated to the new PostgreSQL image, you have a few options:
+        * Pull down an older version of the image from Dockerhub (using a tag)
+        * Or, temporarily rebuild your local image with the old version of Postgres. For example:
+          ```
+          # This command will rebuild using PostgreSQL v11 & tag it locally as "dspace-7_x"
+          docker build --build-arg POSTGRES_VERSION=11 -t dspace/dspace-postgres-pgcrypto:dspace-7_x ./dspace/src/main/docker/dspace-postgres-pgcrypto/
+          # Then restart container with that image
+          docker-compose -p d7 up -d
+          ```
+2. Dump your entire "dspace" database out of the old "dspacedb" container to a local file named `pgdump.sql`
+    ```
+    # NOTE: WE HIGHLY RECOMMEND LOGGING INTO THE CONTAINER and doing the pg_dump within the container.
+    # If you attempt to run pg_dump from your local machine via docker "exec" (or similar), sometimes
+    # UTF-8 characters can be corrupted in the export file. This may result in data loss.
+
+    # First login to the "dspacedb" container
+    docker exec -it dspacedb /bin/bash
+
+    # Dump the "dspace" database to a file named "/tmp/pgdump.sql" within the container
+    pg_dump -U dspace dspace > /tmp/pgdump.sql
+
+    # Exit the container
+    exit
+
+    # Download (copy) that /tmp/pgdump.sql backup file from container to your local machine
+    docker cp dspacedb:/tmp/pgdump.sql .
+    ```
+3. Now, stop all existing containers. This shuts down the old version of PostgreSQL
+    ```
+    # This command assumes you are using the process described above to start/stop all your containers
+    docker-compose -p d7 down
+    ```
+4. Delete the `pgdata` volume. WARNING: This deletes all your old PostgreSQL data. Make sure you have that `pgdump.sql` file FIRST!
+    ```
+    # Assumes you are using `-p d7` which prefixes all volumes with `d7_`
+    docker volume rm d7_pgdata
+    ```
+5. Now, pull down the latest PostgreSQL image with the NEW version of PostgreSQL.
+    ```
+    docker-compose -f docker-compose.yml -f docker-compose-cli.yml pull
+    ```
+6. Start everything up using our `db.restore.yml` script.  This script will recreate the database
+using the local `./pgdump.sql` file. IMPORTANT: If you renamed that "pgdump.sql" file or stored it elsewhere,
+then you MUST change the name/directory in the `db.restore.yml` script.
+    ```
+    # Restore database from "./pgdump.sql" (this path is hardcoded in db.restore.yml)
+    docker-compose -p d7 -f docker-compose.yml -f dspace/src/main/docker-compose/db.restore.yml up -d
+    ```
+7. Finally, reindex all database contents into Solr (just to be sure Solr indexes are current).
+    ```
+    # Run "./dspace index-discovery -b" using our CLI image
+    docker-compose -p d7 -f docker-compose-cli.yml run --rm dspace-cli index-discovery -b
+    ```
+At this point in time, all your old database data should be migrated to the new Postgres
+and running at http://localhost:8080/server/
--- a/dspace/src/main/docker-compose/db.entities.yml
+++ b/dspace/src/main/docker-compose/db.entities.yml
@@ -10,7 +10,7 @@ version: "3.7"

 services:
  dspacedb:
-    image: dspace/dspace-postgres-pgcrypto:loadsql
+    image: dspace/dspace-postgres-pgcrypto:dspace-7_x-loadsql
    environment:
      # This SQL is available from https://github.com/DSpace-Labs/AIP-Files/releases/tag/demo-entities-data
      - LOADSQL=https://github.com/DSpace-Labs/AIP-Files/releases/download/demo-entities-data/dspace7-entities-data.sql
--- a/dspace/src/main/docker-compose/db.restore.yml
+++ b/dspace/src/main/docker-compose/db.restore.yml
@@ -0,0 +1,26 @@
+#
+# The contents of this file are subject to the license and copyright
+# detailed in the LICENSE and NOTICE files at the root of the source
+# tree and available online at
+#
+# http://www.dspace.org/license/
+#
+
+version: "3.7"
+
+#
+# Overrides the default "dspacedb" container behavior to load a local SQL file into PostgreSQL.
+#
+# This can be used to restore a "dspacedb" container from a pg_dump, or during upgrade to a new version of PostgreSQL.
+services:
+  dspacedb:
+    image: dspace/dspace-postgres-pgcrypto:dspace-7_x-loadsql
+    environment:
+      # Location where the dump SQL file will be available on the running container
+      - LOCALSQL=/tmp/pgdump.sql
+    volumes:
+      # Volume which shares a local SQL file at "./pgdump.sql" to the running container
+      # IF YOUR LOCAL FILE HAS A DIFFERENT NAME (or is in a different location), then change the "./pgdump.sql"
+      # portion of this line.
+      - ./pgdump.sql:/tmp/pgdump.sql
+
--- a/dspace/src/main/docker/README.md
+++ b/dspace/src/main/docker/README.md
@@ -1,4 +1,4 @@
-# Docker images supporting DSpace
+# Docker images supporting DSpace Backend

 ***
 :warning: **THESE IMAGES ARE NOT PRODUCTION READY**  The below Docker Compose images/resources were built for development/testing only.  Therefore, they may not be fully secured or up-to-date, and should not be used in production.
@@ -6,9 +6,15 @@
 If you wish to run DSpace on Docker in production, we recommend building your own Docker images. You are welcome to borrow ideas/concepts from the below images in doing so. But, the below images should not be used "as is" in any production scenario.
 ***

-## Dockerfile.dependencies
+## Overview
+The Dockerfiles in this directory (and subdirectories) are used by our [Docker Compose scripts](../docker-compose/README.md).
+
+## Dockerfile.dependencies (in root folder)

 This Dockerfile is used to pre-cache Maven dependency downloads that will be used in subsequent DSpace docker builds.
+Caching these Maven dependencies provides a speed increase to all later builds by ensuring the dependencies
+are only downloaded once.
+
 ```
 docker build -t dspace/dspace-dependencies:dspace-7_x -f Dockerfile.dependencies .
 ```
@@ -22,12 +28,13 @@ Admins to our DockerHub repo can manually publish with the following command.
 docker push dspace/dspace-dependencies:dspace-7_x
 ```

-## Dockerfile.test
+## Dockerfile.test (in root folder)

-This Dockerfile builds a DSpace 7 Tomcat image (for testing/development).
-This image deploys two DSpace webapps:
+This Dockerfile builds a DSpace 7 backend image (for testing/development).
+This image deploys two DSpace webapps to Tomcat running in Docker:
 1. The DSpace 7 REST API (at `http://localhost:8080/server`)
-2. The legacy (v6) REST API (at `http://localhost:8080//rest`), deployed without requiring HTTPS access.
+2. The legacy (v6) REST API (at `http://localhost:8080/rest`), deployed without requiring HTTPS access.
+This image also sets up debugging in Tomcat for development.

 ```
 docker build -t dspace/dspace:dspace-7_x-test -f Dockerfile.test .
@@ -42,12 +49,12 @@ Admins to our DockerHub repo can manually publish with the following command.
 docker push dspace/dspace:dspace-7_x-test
 ```

-## Dockerfile
+## Dockerfile (in root folder)

-This Dockerfile builds a DSpace 7 tomcat image.
-This image deploys two DSpace webapps:
+This Dockerfile builds a DSpace 7 backend image.
+This image deploys one DSpace webapp to Tomcat running in Docker:
 1. The DSpace 7 REST API (at `http://localhost:8080/server`)
-2. The legacy (v6) REST API (at `http://localhost:8080//rest`), deployed *requiring* HTTPS access.
+
 ```
 docker build -t dspace/dspace:dspace-7_x -f Dockerfile .
 ```
@@ -61,9 +68,9 @@ Admins to our DockerHub repo can publish with the following command.
 docker push dspace/dspace:dspace-7_x
 ```

-## Dockefile.cli
+## Dockerfile.cli (in root folder)

-This Dockerfile builds a DSpace 7 CLI image, which can be used to run commandline tools via Docker.
+This Dockerfile builds a DSpace 7 CLI (command line interface) image, which can be used to run DSpace's commandline tools via Docker.
 ```
 docker build -t dspace/dspace-cli:dspace-7_x -f Dockerfile.cli .
 ```
@@ -77,46 +84,60 @@ Admins to our DockerHub repo can publish with the following command.
 docker push dspace/dspace-cli:dspace-7_x
 ```

-## dspace/src/main/docker/dspace-postgres-pgcrypto/Dockerfile
+## ./dspace-postgres-pgcrypto/Dockerfile

 This is a PostgreSQL Docker image containing the `pgcrypto` extension required by DSpace 6+.
+This image is built *automatically* after each commit is made to the `main` branch.
+
+How to build manually:
 ```
 cd dspace/src/main/docker/dspace-postgres-pgcrypto
-docker build -t dspace/dspace-postgres-pgcrypto .
+docker build -t dspace/dspace-postgres-pgcrypto:dspace-7_x .
 ```

-**This image is built manually.**  It should be rebuilt as needed.
+It is also possible to change the version of PostgreSQL or the PostgreSQL user's password during the build:
+```
+cd dspace/src/main/docker/dspace-postgres-pgcrypto
+docker build -t dspace/dspace-postgres-pgcrypto:dspace-7_x --build-arg POSTGRES_VERSION=11 --build-arg POSTGRES_PASSWORD=mypass .
+```

 A copy of this file exists in the DSpace 6 branch.  A specialized version of this file exists for DSpace 4 in DSpace-Docker-Images.

-Admins to our DockerHub repo can publish with the following command.
+Admins to our DockerHub repo can (manually) publish with the following command.
 ```
-docker push dspace/dspace-postgres-pgcrypto
+docker push dspace/dspace-postgres-pgcrypto:dspace-7_x
 ```

-## dspace/src/main/docker/dspace-postgres-pgcrypto-curl/Dockerfile
+## ./dspace-postgres-pgcrypto-curl/Dockerfile

 This is a PostgreSQL Docker image containing the `pgcrypto` extension required by DSpace 6+.
 This image also contains `curl`.  The image is pre-configured to load a Postgres database dump on initialization.
+
+This image is built *automatically* after each commit is made to the `main` branch.
+
+How to build manually:
 ```
 cd dspace/src/main/docker/dspace-postgres-pgcrypto-curl
-docker build -t dspace/dspace-postgres-pgcrypto:loadsql .
+docker build -t dspace/dspace-postgres-pgcrypto:dspace-7_x-loadsql .
 ```

-**This image is built manually.**   It should be rebuilt as needed.
+Similar to `dspace-postgres-pgcrypto` above, you can also modify the version of PostgreSQL or the PostgreSQL user's password.
+See examples above.

 A copy of this file exists in the DSpace 6 branch.

-Admins to our DockerHub repo can publish with the following command.
+Admins to our DockerHub repo can (manually) publish with the following command.
 ```
-docker push dspace/dspace-postgres-pgcrypto:loadsql
+docker push dspace/dspace-postgres-pgcrypto:dspace-7_x-loadsql
 ```

-## dspace/src/main/docker/dspace-shibboleth/Dockerfile
+## ./dspace-shibboleth/Dockerfile

 This is a test / demo image which provides an Apache HTTPD proxy (in front of Tomcat)
-with mod_shib & Shibboleth installed.  It is primarily for usage for
-testing DSpace's Shibboleth integration. It uses https://samltest.id/ as the Shibboleth IDP
+with `mod_shib` & Shibboleth installed based on the
+[DSpace Shibboleth configuration instructions](https://wiki.lyrasis.org/display/DSDOC7x/Authentication+Plugins#AuthenticationPlugins-ShibbolethAuthentication).
+It is primarily for usage for testing DSpace's Shibboleth integration.
+It uses https://samltest.id/ as the Shibboleth IDP

 **This image is built manually.**   It should be rebuilt as needed.

@@ -130,7 +151,7 @@ docker run -i -t -d -p 80:80 -p 443:443 dspace/dspace-shibboleth

 This image can also be rebuilt using the `../docker-compose/docker-compose-shibboleth.yml` script.

-## dspace/src/main/docker/dspace-solr/Dockerfile
+## ./dspace-solr/Dockerfile

 This Dockerfile builds a Solr image with DSpace Solr configsets included. It
 can be pulled / built following the [docker compose resources](../docker-compose/README.md)
@@ -148,9 +169,10 @@ restart the `dspacesolr` container for the changes to be deployed. From DSpace r
 docker-compose -p d7 up --detach --build dspacesolr
 ```

-## test/ folder
+## ./test/ folder

 These resources are bundled into the `dspace/dspace:dspace-*-test` image at build time.
+See the `Dockerfile.test` section above for more information about the test image.


 ## Debugging Docker builds
--- a/dspace/src/main/docker/dspace-postgres-pgcrypto-curl/Dockerfile
+++ b/dspace/src/main/docker/dspace-postgres-pgcrypto-curl/Dockerfile
@@ -6,14 +6,21 @@
 # http://www.dspace.org/license/
 #

-# This will be deployed as dspace/dspace-postgres-pgcrpyto:loadsql
-FROM postgres:11
+# To build for example use:
+# docker build --build-arg POSTGRES_VERSION=13 --build-arg POSTGRES_PASSWORD=mypass ./dspace/src/main/docker/dspace-postgres-pgcrypto-curl/
+# This will be published as dspace/dspace-postgres-pgcrypto:$DSPACE_VERSION-loadsql
+
+ARG POSTGRES_VERSION=13
+ARG POSTGRES_PASSWORD=dspace
+
+FROM postgres:${POSTGRES_VERSION}

 ENV POSTGRES_DB dspace
 ENV POSTGRES_USER dspace
-ENV POSTGRES_PASSWORD dspace
+ENV POSTGRES_PASSWORD ${POSTGRES_PASSWORD}
+
+# Install curl which is necessary to load SQL file
+RUN apt-get update && apt-get install -y curl && rm -rf /var/lib/apt/lists/*

 # Load a SQL dump.  Set LOADSQL to a URL for the sql dump file.
-RUN apt-get update && apt-get install -y curl
-
 COPY install-pgcrypto.sh /docker-entrypoint-initdb.d/
--- a/dspace/src/main/docker/dspace-postgres-pgcrypto-curl/install-pgcrypto.sh
+++ b/dspace/src/main/docker/dspace-postgres-pgcrypto-curl/install-pgcrypto.sh
@@ -11,15 +11,33 @@ set -e

 CHECKFILE=/pgdata/ingest.hasrun.flag

+# If $LOADSQL environment variable set, use 'curl' to download that SQL and run it in PostgreSQL
+# This can be used to initialize a database based on test data available on the web.
 if [ ! -f $CHECKFILE -a ! -z ${LOADSQL} ]
 then
-  curl ${LOADSQL} -L -s --output /tmp/dspace.sql
-  psql -U $POSTGRES_USER < /tmp/dspace.sql
+  # Download SQL file to /tmp/dspace-db-init.sql
+  curl ${LOADSQL} -L -s --output /tmp/dspace-db-init.sql
+  # Load into PostgreSQL
+  psql -U $POSTGRES_USER < /tmp/dspace-db-init.sql
+  # Remove downloaded file
+  rm /tmp/dspace-db-init.sql

  touch $CHECKFILE
  exit
 fi

+# If $LOCALSQL environment variable set, then simply run it in PostgreSQL
+# This can be used to restore data from a pg_dump or similar.
+if [ ! -f $CHECKFILE -a ! -z ${LOCALSQL} ]
+then
+  # Load into PostgreSQL
+  psql -U $POSTGRES_USER < ${LOCALSQL}
+
+  touch $CHECKFILE
+  exit
+fi
+
+# Then, setup pgcrypto on this database
 psql -v ON_ERROR_STOP=1 --username "$POSTGRES_USER" <<-EOSQL
  -- Create a new schema in this database named "extensions" (or whatever you want to name it)
  CREATE SCHEMA extensions;
--- a/dspace/src/main/docker/dspace-postgres-pgcrypto/Dockerfile
+++ b/dspace/src/main/docker/dspace-postgres-pgcrypto/Dockerfile
@@ -6,13 +6,18 @@
 # http://www.dspace.org/license/
 #

-# This will be deployed as dspace/dspace-postgres-pgcrpyto:latest
-FROM postgres:11
+# To build for example use:
+# docker build --build-arg POSTGRES_VERSION=13 --build-arg POSTGRES_PASSWORD=mypass ./dspace/src/main/docker/dspace-postgres-pgcrypto/
+# This will be published as dspace/dspace-postgres-pgcrypto:$DSPACE_VERSION
+
+ARG POSTGRES_VERSION=13
+ARG POSTGRES_PASSWORD=dspace
+
+FROM postgres:${POSTGRES_VERSION}

 ENV POSTGRES_DB dspace
 ENV POSTGRES_USER dspace
-ENV POSTGRES_PASSWORD dspace
-
-RUN apt-get update
+ENV POSTGRES_PASSWORD ${POSTGRES_PASSWORD}

+# Copy over script which will initialize database and install pgcrypto extension
 COPY install-pgcrypto.sh /docker-entrypoint-initdb.d/