LIBDRUM-790. Updated "README-DRUM.md" for DSpace 7

README-DRUM.md

@@ -1,98 +1,121 @@
 # Digital Repository at the University of Maryland (DRUM)
 
-Home: <http://drum.lib.umd.edu/>
-
-See <http://drum.lib.umd.edu/help/about_drum.jsp> for more information.
+Home: <https://drum.lib.umd.edu/>
 
 ## Documentation
 
 The original DSpace documentation:
 
-* [README-DSPACE.md](README-DSPACE.md)
-* [DSpace Manual](dspace/docs/pdf/DSpace-Manual.pdf)
+* [README-DSPACE.md](README.md)
+
+## Development Environment
+
+Instructions for building and running drum locally can be found in
+[dspace/docs/Drum7DockerDevelopmentEnvironment.md](/dspace/docs/Drum7DockerDevelopmentEnvironment.md)
+
+## Building Images for K8s Deployment
+
+As of May 2023,  MacBooks utilizing Apple Silicon (the "arm64" architecture)
+are unable to directly generate the "amd64" Docker images used by Kubernetes.
+
+The following procedure uses the Docker "buildx" functionality and the
+Kubernetes "build" namespace to build the Docker images. This procedure should
+work on both "arm64" and "amd64" MacBooks.
+
+All images will be automatically pushed to the Nexus.
+
+### Local Machine Setup
+
+See <https://confluence.umd.edu/display/LIB/Docker+Builds+in+Kubernetes> in
+Confluence for information about setting up a MacBook to use the Kubernetes
+"build" namespace.
+
+### Creating the Docker images
 
-### Development Environment
+1) In an empty directory, checkout the Git repository and switch into the
+   directory:
 
-Instructions for building and running drum locally can be found at:
-[Drum7DockerDevelopmentEnvironment.md](/dspace/docs/Drum7DockerDevelopmentEnvironment.md)
+    ```bash
+    $ git clone git@github.com:umd-lib/DSpace.git drum
+    $ cd drum
+    ```
 
-### Building Images for K8s Deployment
+2) Checkout the appropriate Git tag, branch, or commit for the Docker images.
 
-#### DSpace Image
+3) Set up a "DRUM_TAG" environment variable:
 
-Dockerfile.dependencies is used to pre-cache maven downloads that will be used
-in subsequent DSpace docker builds.
+    ```bash
+    $ export DRUM_TAG=<DOCKER_IMAGE_TAG>
+    ```
 
-```bash
-docker build -t docker.lib.umd.edu/drum-dependencies-6_x:latest -f Dockerfile.dependencies .
-```
+   where \<DOCKER_IMAGE_TAG> is the Docker image tag to associate with the
+   Docker images. This will typically be the Git tag for the DRUM version,
+   or some other identifier, such as a Git commit hash. For example, using the
+   Git tag of "7.4/drum-0":
 
-This Dockerfile builds a drum tomcat image.
+    ```bash
+    $ export DRUM_TAG=7.4/drum-0
+    ```
 
-```bash
-docker build -t docker.lib.umd.edu/drum:<VERSION> .
-```
+4) Set up a "DRUM_DIR" environment variable referring to the current
+   directory:
 
-The version would follow the drum project version. For example, a release
-version could be `6.3/drum-4.2`, and we can suffix the version number
-with `-rcX` or use `latest` as the version for non-production images.
+    ```bash
+    $ export DRUM_DIR=`pwd`
+    ```
 
-#### Postgres Image
+5) Switch to the Kubernetes "build" namespace:
 
-To build postgres image with pgcrypto module.
+    ```bash
+    $ kubectl config use-context build
+    ```
 
-```bash
-cd dspace/src/main/docker/dspace-postgres-pgcrypto
-docker build -t docker.lib.umd.edu/dspace-postgres:<VERSION> .
-```
+6) Create the "docker.lib.umd.edu/drum-dependencies-7_x" Docker image. This
+   image is used to pre-cache Maven downloads that will be used in subsequent
+   DSpace docker builds:
 
-We could follow the same versioning scheme as the main drum image, but we don't
-necessarily have create new image versions for postgres for every patch or
-hotfix version increments. The postgres image can be built when there is a
-relevant change.
+    ```bash
+    $ docker buildx build --platform linux/amd64 --builder=kube --push --no-cache -t docker.lib.umd.edu/drum-dependencies-7_x:latest -f Dockerfile.dependencies .
+    ```
 
-#### Solr Image
+7) Create the "docker.lib.umd.edu/drum" Docker image:
 
-To build postgres image with pgcrypto module.
+    ```bash
+    $ docker buildx build --platform linux/amd64 --builder=kube --push --no-cache -f Dockerfile -t docker.lib.umd.edu/drum:$DRUM_TAG .
+    ```
 
-```bash
-cd dspace/solr
-docker build -t docker.lib.umd.edu/drum-solr:<VERSION> .
-```
+8) Create the "docker.lib.umd.edu/dspace-postgres", which is a Postgres image
+   with "pgcrypto" module:
 
-We could follow the same versioning scheme as the main drum image, but we don't
-necessariliy have create new image versions for solr for every patch or hotfix
-version increments. The solr image can be built when there is a relevant change.
+    **Note:** The "Dockerfile" for the "dspace-postgres" image specifies
+    only the major Postgres version as the base image. This allows Postgres
+    minor version updates to be retrieved automatically. It may not be
+    necessary to create new "dspace-postgres" image versions for every DRUM
+    patch or hotfix version increment.
 
-### Deployment
+    ```bash
+    $ cd $DRUM_DIR/dspace/src/main/docker/dspace-postgres-pgcrypto
 
-The `dspace-installer` directory that contains all the artifacts and the ant
-script to perform the deployment. The `installer-dist` maven profile creates a
-tar file of the installer directory which can be pushed to the UMD nexus by
-using the `deploy-release` or `deploy-snapshot` profile.
+    $ docker buildx build --platform linux/amd64 --builder=kube --push --no-cache -f Dockerfile -t docker.lib.umd.edu/dspace-postgres:$DRUM_TAG .
+    ```
 
-```bash
-# Switch to the dspace directory
-cd /apps/git/drum/dspace
+9) Create the "docker.lib.umd.edu/drum-solr":
 
-# Deploy a snapshot version to nexus
-# (use this profile if the current project version is a SNAPSHOT version)
-mvn -P installer-dist,deploy-snapshot
+    **Note:** The "Dockerfile" for the "drum-solr" image specifies only the
+    major Solr version as the base image. This allows Solr minor version updates
+    to be retrieved automatically. It may not be necessary to create new
+    "drum-solr" image versions for every DRUM patch or hotfix version increment.
 
-# Deploy a release version to nexus
-mvn -P installer-dist,deploy-release
-```
+    ```bash
+    $ cd $DRUM_DIR/dspace/solr
 
-*NOTE:* For the Nexus deployment to succeed, the nexus server, username and
-password needs to be configured in the `.m2/setting.xml` and a prior successful
-`mvn install`.
+    $ docker buildx build --platform linux/amd64 --builder=kube --push --no-cache -f Dockerfile -t docker.lib.umd.edu/drum-solr:$DRUM_TAG .
+    ```
 
 ### Features
 
 * [DrumFeatures](dspace/docs/DrumFeatures.md) - Summary of DRUM enhancements to
   base DSpace functionality
-* [DrumFeaturesandCode](dspace/docs/DrumFeaturesandCode.md) - DRUM enhancements
-  with implementation details
 * [DrumConfigurationCustomization](dspace/docs/DrumConfigurationCustomization.md) -
   Information about customizing DSpace for DRUM.
 * [docs](dspace/docs) - additional documentation