DP-2130: Update ASpace to v4.1.1

- Bumps ASpace to the latest version.
- Bumps Digitization Work Order plugin to 2.x to support ASpace v4.
- Upgrades Solr to v9 (required by ASpace v4).
- Reconfigures Solr to use a custom build rather than bind-mounted core configs.
- Renames Docker Compose files to preferred "compose.yml".
- Adds ability to test DB migrations with existing data loaded to `./db/dumps`.

Author: danschmidt5189

.dockerignore

@@ -1 +1,6 @@
 .env
+.git
+.github
+.gitignore
+db
+init

.env.example

@@ -1 +1,2 @@
 APPCONFIG_DB_URL=jdbc:mysql://db:3306/archivesspace?useUnicode=true&characterEncoding=UTF-8&user=archivesspace&password=archivesspace
+ARCHIVESSPACE_VERSION="v4.1.1"

.gitignore

@@ -1 +1,5 @@
 .env
+db/dumps/*
+!db/dumps/.keep
+data
+init

Dockerfile

@@ -1,30 +1,30 @@
 # ============================================================
 # Adding comment to trigger a build
 # BASE Stage
-FROM ubuntu:20.04 AS base
+FROM ubuntu:noble AS base
 
-ARG ARCHIVESSPACE_VERSION="v3.3.1"
+ARG ARCHIVESSPACE_VERSION="v4.1.1"
 ARG ARCHIVESSPACE_USER_UID="40052"
 ARG ARCHIVESSPACE_USER_GID="40052"
-ARG DWO_PLUGIN_VERSION="v1.13"
+ARG DWO_PLUGIN_VERSION="v2.1"
 ARG MT_PLUGIN_VERSION="v1.5"
-ARG MYSQL_CONNECTOR_VERSION="8.0.23"
+ARG MYSQL_CONNECTOR_VERSION="9.5.0"
 
 ENV ARCHIVESSPACE_LOGS="/dev/null"
 ENV ARCHIVESSPACE_PLUGIN_DWO_URL="https://github.com/hudmol/digitization_work_order/archive/refs/tags/${DWO_PLUGIN_VERSION}.zip"
 ENV ARCHIVESSPACE_PLUGIN_MT_URL="https://github.com/hudmol/material_types/archive/refs/tags/${MT_PLUGIN_VERSION}.zip"
 ENV ARCHIVESSPACE_SOURCE_URL="https://github.com/archivesspace/archivesspace/releases/download/${ARCHIVESSPACE_VERSION}/archivesspace-${ARCHIVESSPACE_VERSION}.zip"
 ENV DEBIAN_FRONTEND="noninteractive"
 ENV LANG="C.UTF-8"
-ENV MYSQL_CONNECTOR_JAR_URL="https://repo1.maven.org/maven2/mysql/mysql-connector-java/${MYSQL_CONNECTOR_VERSION}/mysql-connector-java-${MYSQL_CONNECTOR_VERSION}.jar"
+ENV MYSQL_CONNECTOR_JAR_URL="https://repo1.maven.org/maven2/com/mysql/mysql-connector-j/${MYSQL_CONNECTOR_VERSION}/mysql-connector-j-${MYSQL_CONNECTOR_VERSION}.jar"
 ENV TZ="UTC"
 
 RUN apt-get update && \
     apt-get -y install --no-install-recommends \
       ca-certificates \
       git \
       netbase \
-      openjdk-11-jre-headless \
+      openjdk-17-jre-headless \
       shared-mime-info \
       vim \
       wget \
@@ -70,26 +70,24 @@ RUN wget -O material_types.zip "$ARCHIVESSPACE_PLUGIN_MT_URL" && \
 FROM base AS final
 
 # Copy the built ArchivesSpace
-COPY --from=aspace --chown=root:archivesspace /opt/app /opt/app
+COPY --from=aspace --chown=archivesspace:archivesspace /opt/app /opt/app
 
 # Copy in our custom config files
-COPY --chown=root:archivesspace files/config/config.rb /opt/app/config/config.rb
-COPY --chown=root:archivesspace files/plugins/local/frontend/assets/images/* /opt/app/plugins/local/frontend/assets/images/
-COPY --chown=root:archivesspace files/plugins/local/frontend/locales/en.rb /opt/app/plugins/local/frontend/locales/en.rb
+COPY --chown=archivesspace:archivesspace files/plugins/local/frontend/assets/images/* /opt/app/plugins/local/frontend/assets/images/
+COPY --chown=archivesspace:archivesspace files/plugins/local/frontend/locales/en.rb /opt/app/plugins/local/frontend/locales/en.rb
 
 # Copy the built DWO plugin
-COPY --from=digitization_work_order --chown=root:archivesspace \
+COPY --from=digitization_work_order --chown=archivesspace:archivesspace \
     /opt/app/plugins/digitization_work_order \
     /opt/app/plugins/digitization_work_order
 
 # Copy the built Materials Type plugin
-COPY --from=material_types --chown=root:archivesspace \
+COPY --from=material_types --chown=archivesspace:archivesspace \
     /opt/app/plugins/material_types \
     /opt/app/plugins/material_types
 
 # Install the entrypoint script.
-COPY --chown=root:archivesspace docker-entrypoint.sh /bin/docker-entrypoint.sh
-RUN chmod ug+x /bin/docker-entrypoint.sh
+COPY --chown=archivesspace:archivesspace files/docker-entrypoint.sh /bin/docker-entrypoint.sh
 ENTRYPOINT ["/bin/docker-entrypoint.sh"]
 
 USER archivesspace

README.md

@@ -6,20 +6,27 @@ This repo Dockerizes ArchivesSpace. In a nutshell:
 # Populate your local .env file with secrets (e.g. OCLC keys)
 cp .env.example .env
 
-# Build the stack
+# Build the stack / pull dependencies
 docker compose build
+docker compose pull
 
 # Run it all
-docker compose up -d
+docker compose up --wait
+
+# Open ASpace in your browser
+open http://localhost:8080
 ```
 
+For ArchivesSpace v4+, consult their excellent [new documentation site](https://docs.archivesspace.org/).
+
 ### Database Initialization
 
-The database is initialized by an "updater" service which simply runs `scripts/setup-database.sh` and exits. Docker should retry it continuously until it succeeds.
+* The database is initialized by an "updater" service which simply runs `scripts/setup-database.sh` and exits. Docker should retry it continuously until it succeeds.
+* To test migrations with real data, add a dump to the `db/dumps/` directory. The updater still runs against this, making it helpful for testing whether your data will survive a migration.
 
 ### Secrets
 
-We've added an entrypoint.sh shim script which loads files from `/run/secrets` into the environment before running a given command. Secrets can be added there using Docker's normal methods, but read from the application using `ENV`.
+We've added a `docker-entrypoint.sh` shim script which loads files from `/run/secrets` into the environment before running a given command. Secrets can be added there using Docker's normal methods, but read from the application using `ENV`.
 
 ### Configuration File
 

compose.yml

@@ -2,17 +2,21 @@
 
 services:
   app: &services_app
-    build: .
-    user: root
+    build:
+      context: .
+      args: &aspace-build-args
+        - ARCHIVESSPACE_VERSION=${ARCHIVESSPACE_VERSION:-v4.1.1}
+    # ASpace bundles a lot of services, for a full reference:
+    # @see https://docs.archivesspace.org/customization/configuration/#urls-for-archivesspace-components
     ports:
-      - 8080:8080
-      - 8081:8081
-      - 8082:8082
-      - 8089:8089
-      - 8090:8090
+      - 8080:8080 # staff
+      - 8081:8081 # public (disabled by APPCONFIG_ENABLE_PUBLIC)
+      - 8082:8082 # OAI harvesting
+      - 8888:8888 # documentation
+      - 8089:8089 # backend
+      - 8090:8090 # built-in solr (unused)
+      - 8091:8091 # indexer
     configs:
-      - source: config.rb
-        target: /opt/app/config/config.rb
       - source: en-locales.yml
         target: /opt/app/locales/enums/en.yml
     depends_on:
@@ -22,9 +26,6 @@ services:
         condition: service_healthy
       updater:
         condition: service_completed_successfully
-    secrets:
-      # @note Customize these in your local .env file if necessary
-      - APPCONFIG_DB_URL
     environment:
       # @note ArchivesSpace settings can be specified by setting ENV vars of the form
       #       APPCONFIG_<Upcased Parameter Name>. We have run into problems with any
@@ -34,12 +35,16 @@ services:
       - APPCONFIG_FRONTEND_BRANDING_IMG_ALT_TEXT=ArchivesSpace Local Development Logo
       - APPCONFIG_PLUGINS_OVERRIDE=local,lcnaf,digitization_work_order,material_types
       - APPCONFIG_ENABLE_PUBLIC=false
+      - APPCONFIG_PUI_INDEXER_ENABLED=false
       - APPCONFIG_SOLR_URL=http://solr:8983/solr/archivesspace
       - APPCONFIG_SOLR_VERIFY_CHECKSUMS=false
       - ASPACE_LOGGED_IN_MSG=You are logged in to a local development instance of ArchivesSpace
       - ASPACE_WELCOME_HEADING=ArchivesSpace Development (local)
       - ASPACE_WELCOME_MESSAGE=You are on a local development instance of ArchivesSpace
       - JAVA_OPTS=-Djava.awt.headless=true -Dfile.encoding=UTF-8 -server -Xss512k -Djavax.accessibility.assistive_technologies=''
+    # @note Use `secrets:` instead of `environment:` to test that the entrypoint loads them into ENV
+    secrets:
+      - APPCONFIG_DB_URL
     volumes:
       - aspace_data:/opt/app/data
       - solr_data:/var/solr/data:ro
@@ -54,17 +59,20 @@ services:
     restart: on-failure
 
   solr:
-    image: solr:8.11.2
+    build:
+      context: solr
+      args: *aspace-build-args
+    command: solr-precreate archivesspace /opt/solr/server/solr/configsets/archivesspace
     environment:
+      # @see https://docs.archivesspace.org/provisioning/solr/#setup-the-environment
+      - SOLR_MODULES=analysis-extras
       # Eliminates "failed to reserve shared memory" warning
       # @see https://support.pingidentity.com/s/article/Addressing-Failed-to-reserve-shared-memory-errors
-      GC_TUNE: -XX:-UseLargePages
+      - GC_TUNE=-XX:-UseLargePages
     ports:
       - 8983:8983
-    command: solr-precreate archivesspace /opt/solr/server/solr/configsets/archivesspace
     volumes:
-      - ./solr:/opt/solr-8.11.2/server/solr/configsets/archivesspace/conf:ro
-      - solr_data:/var/solr/data
+      - solr_data:/var/solr
     healthcheck:
       test: curl --max-time 10 -f http://localhost:8983/solr/#/~cores/archivesspace || exit 1
       start_period: 10s
@@ -74,9 +82,6 @@ services:
 
   db:
     image: mariadb:10.9
-    depends_on:
-      solr:
-        condition: service_healthy
     environment:
       # @note These are all hardcoded for convenience
       - MYSQL_ROOT_PASSWORD=archivesspace-root
@@ -85,19 +90,22 @@ services:
       - MYSQL_PASSWORD=archivesspace
     ports:
       - 3306:3306
+    secrets:
+      - source: root-my.cnf
+        target: /root/.my.cnf
     volumes:
+      - ./db/dumps:/docker-entrypoint-initdb.d:ro
       - db_data:/var/lib/mysql
-      - ./init:/docker-entrypoint-initdb.d
 
 configs:
-  config.rb:
-    file: files/config/config.rb
   en-locales.yml:
     file: files/locales/enums/en.yml
 
 secrets:
   APPCONFIG_DB_URL:
     environment: APPCONFIG_DB_URL
+  root-my.cnf:
+    file: files/root-my.cnf
 
 volumes:
   aspace_data: {}

solr/stopwords.txt db/dumps/.keepsolr/stopwords.txt renamed to db/dumps/.keep

@@ -0,0 +1,3 @@
+[client]
+user = root
+password = archivesspace-root

docker-entrypoint.sh files/docker-entrypoint.shdocker-entrypoint.sh renamed to files/docker-entrypoint.sh

@@ -0,0 +1,21 @@
+FROM solr:9
+
+ARG ARCHIVESSPACE_VERSION="v4.1.1"
+ENV ARCHIVESSPACE_SOURCE_URL="https://github.com/archivesspace/archivesspace/releases/download/${ARCHIVESSPACE_VERSION}/archivesspace-${ARCHIVESSPACE_VERSION}.zip"
+
+# Upgrade system packages and install wget
+USER root
+RUN apt-get -y update && \
+    apt-get -y upgrade && \
+    apt-get -y install --no-install-recommends \
+      unzip \
+      wget && \
+    rm -rf /var/lib/apt/lists/*
+
+# Create a configset for the given ASpace release
+RUN mkdir -p /opt/solr/server/solr/configsets/archivesspace/conf && \
+    wget -O aspace.zip "$ARCHIVESSPACE_SOURCE_URL" && \
+    unzip aspace.zip 'archivesspace/solr/*' && \
+    mv archivesspace/solr/* /opt/solr/server/solr/configsets/archivesspace/conf/ && \
+    rm -rf aspace.zip archivesspace
+USER solr