Merge branch 'pascal/bind-mounts' into 'develop'

Introduce DOCKER_VOLUMES_PATH_PREFIX for easier storage and backup handling

See merge request FDM/rdm-system/rdms!206

.env.template

 IN_DOCKER=true
 
+# Common path prefix for all subvolume bind mounts to facilitate backup create and restoration
+# Note: This path needs to start with either "./" or "/" and needs to end with a "slash".
+# This is to allow for setting this to an empty string or not defining the variable at all if Docker's standard volume directory should be used.
+DOCKER_VOLUMES_PATH_PREFIX="./volumes/"
+
 # Solr setting
 SOLR_URL_SCHEME=http
 SOLR_HOST=solr

.gitignore

@@ -348,3 +348,11 @@ $RECYCLE.BIN/
 /hyrax/seed/*
 !hyrax/seed/setup.json.template
 
+volumes/fcrepo/*
+volumes/solr/*
+volumes/db-fcrepo/*
+volumes/db-app/*
+volumes/file_uploads/*
+volumes/derivatives/*
+volumes/cache/*
+volumes/redis/*

README.md

@@ -80,6 +80,34 @@ local     rdms_solr
 
 These will persist when the system is brought down and rebuilt. Deleting them will require importers etc. to run again.
 
+#### Persisting container volumes in a custom directory tree
+You can set the `DOCKER_VOLUMES_PATH_PREFIX` variable in the `.env` file to a path where all the above mentioned volumes should be physically stored, but note that this variable should always end in a forward slash `/` (This is a side effect of us *not* explicitly specifying a `/` between the variable name and the volume names in `docker-compose.yml`, because this allows leaving the variable empty/unset if the Docker default should be used, storing the volumes in `/var/lib/docker/volumes`). If you specify set this variable to a value in the `.env` file, you can run `create_volume_directories.sh` to create the directory tree with the subdirectory for each volume and set its required access permissions / file system ACLs. The main reason for this feature is to allow for easier and less error-prone backup creation and restoration.
+
+If you want to migrate data from existing Docker volumes in `/var/lib/docker/volumes` to the `${DOCKER_VOLUMES_PATH_PREFIX}` directory tree, you can do something like this:
+
+```shell
+# Shut down all Docker containers to ensure consistency
+docker compose -f docker-compose.yml down
+
+# Set the `DOCKER_VOLUMES_PATH_PREFIX` variable in the .env file to an absolute or relative path ending in "/", for example "./volumes/"
+vim .env
+
+# Source the modified .env file
+source .env
+
+# Create the volume directory tree
+# Note: This script can also be executed if some or all of the volume directories already exist.
+# In that case, it will *not* delete any data, but merely create missing directories and set their filesystem permissions and ACLs)
+./create_volume_directories.sh
+
+# Copy the data from the existing/old volume directories
+for volume in app cache db-app db-fcrepo derivatives fcrepo file_uploads redis solr
+do
+	cp -a "/var/lib/docker/volumes/rdms_${volume}/_data/*" "${DOCKER_VOLUMES_PATH_PREFIX}${volume}/"
+done
+```
+
+Note that when creating backups, numerical user IDs instead of user/group names should be used (because the numerical IDs of users and groups inside containers will usually not align neither with the host system nor with other containers), and filesystem ACLs need to be preserved. Therefore, for example, if you use `tar`, use tar's `--numeric-owner` and `--acls` parameters both when creating and extracting a backup tarball.
 
 ## Running RDMS
 

create_volume_directories.sh

+#!/bin/bash
+set -euo pipefail
+
+source .env
+
+echo "DOCKER_VOLUMES_PATH_PREFIX value: ${DOCKER_VOLUMES_PATH_PREFIX}"
+
+if [[ -z "${DOCKER_VOLUMES_PATH_PREFIX}" ]]; then
+	echo "Error: \${DOCKER_VOLUMES_PATH_PREFIX} is empty/unset. Aborting..."
+	exit 1
+fi
+if [[ ! "${DOCKER_VOLUMES_PATH_PREFIX}" =~ ^\.?\.?/([^/]+/)+$ ]]; then
+	echo "Error: \${DOCKER_VOLUMES_PATH_PREFIX} is neither an absolute nor a relative path or does not end with a \"/\". Aborting..."
+	exit 1
+fi
+
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}"             && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}cache"        && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}cache"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}db-fcrepo"    && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}db-fcrepo"    && setfacl --modify="user:70:rwx" "${DOCKER_VOLUMES_PATH_PREFIX}db-fcrepo"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}db-app"       && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}db-app"       && setfacl --modify="user:70:rwx" "${DOCKER_VOLUMES_PATH_PREFIX}db-app"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}derivatives"  && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}derivatives"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}fcrepo"       && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}fcrepo"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}file_uploads" && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}file_uploads"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}redis"        && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}redis"        && setfacl --modify="user:999:rwx" "${DOCKER_VOLUMES_PATH_PREFIX}redis"    && setfacl --modify="group:999:rwx" "${DOCKER_VOLUMES_PATH_PREFIX}redis"
+mkdir --mode=700 --parents "${DOCKER_VOLUMES_PATH_PREFIX}solr"         && chmod 700 "${DOCKER_VOLUMES_PATH_PREFIX}solr"         && setfacl --modify="user:8983:rwx" "${DOCKER_VOLUMES_PATH_PREFIX}solr"

docker-compose.yml

 version: '3'
 
-volumes:
-  solr:
-  db-app:
-  db-fcrepo:
-  app:
-  file_uploads:
-  derivatives:
-  cache:
-  fcrepo:
-  redis:
-
 networks:
   internal:
 
@@ -29,7 +18,7 @@ services:
     ports:
       - 8080:8080
     volumes:
-      - fcrepo:/data
+      - ${DOCKER_VOLUMES_PATH_PREFIX}fcrepo:/data
 
   solr:
     image: solr:8
@@ -50,7 +39,7 @@ services:
     networks:
       internal:
     volumes:
-      - solr:/var/solr
+      - ${DOCKER_VOLUMES_PATH_PREFIX}solr:/var/solr
       - ./hyrax/solr/conf:/opt/solr/solr_conf
     command:
       - sh
@@ -65,7 +54,7 @@ services:
     environment:
       - POSTGRES_DB=${POSTGRES_DB_FCREPO}
     volumes:
-      - db-fcrepo:/var/lib/postgresql/data
+      - ${DOCKER_VOLUMES_PATH_PREFIX}db-fcrepo:/var/lib/postgresql/data
     networks:
       internal:
     expose:
@@ -84,7 +73,7 @@ services:
     environment:
       - POSTGRES_DB=${POSTGRES_DB_APP}
     volumes:
-      - db-app:/var/lib/postgresql/data
+      - ${DOCKER_VOLUMES_PATH_PREFIX}db-app:/var/lib/postgresql/data
     networks:
       internal:
     expose:
@@ -107,9 +96,9 @@ services:
     env_file:
       - .env
     volumes:
-      - file_uploads:${UPLOADS_PATH}
-      - derivatives:${DERIVATIVES_PATH}
-      - cache:${CACHE_PATH}
+      - ${DOCKER_VOLUMES_PATH_PREFIX}file_uploads:${UPLOADS_PATH}
+      - ${DOCKER_VOLUMES_PATH_PREFIX}derivatives:${DERIVATIVES_PATH}
+      - ${DOCKER_VOLUMES_PATH_PREFIX}cache:${CACHE_PATH}
       - ${CRC_FOLDER_IMPORT_PATH}:/rub-test-data
     networks:
       internal:
@@ -161,5 +150,5 @@ services:
     ports:
       - 6379:6379
     volumes:
-      - redis:/data
+      - ${DOCKER_VOLUMES_PATH_PREFIX}redis:/data