From 139f0f7d5c762533e4fdcec5dc65e487170e570f Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 8 Mar 2022 17:27:51 +0100 Subject: [PATCH 01/60] feat(ct-base): add new base container image in submodule --- modules/container-base/pom.xml | 90 ++++++++ .../container-base/src/main/docker/Dockerfile | 204 ++++++++++++++++++ .../src/main/docker/assembly.xml | 17 ++ .../src/main/docker/scripts/entrypoint.sh | 17 ++ .../init_1_generate_deploy_commands.sh | 65 ++++++ .../main/docker/scripts/startInForeground.sh | 89 ++++++++ modules/dataverse-parent/pom.xml | 51 +++++ 7 files changed, 533 insertions(+) create mode 100644 modules/container-base/pom.xml create mode 100644 modules/container-base/src/main/docker/Dockerfile create mode 100644 modules/container-base/src/main/docker/assembly.xml create mode 100644 modules/container-base/src/main/docker/scripts/entrypoint.sh create mode 100644 modules/container-base/src/main/docker/scripts/init_1_generate_deploy_commands.sh create mode 100644 modules/container-base/src/main/docker/scripts/startInForeground.sh diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml new file mode 100644 index 00000000000..8cb7e1ac795 --- /dev/null +++ b/modules/container-base/pom.xml @@ -0,0 +1,90 @@ + + + 4.0.0 + + + edu.harvard.iq + dataverse-parent + ${revision} + ../dataverse-parent + + + io.gdcc + container-base + ${packaging.type} + Container Base Image + This module provides an application server base image to be decorated with the Dataverse app. + + + + + pom + + + + + ct + + docker-build + + + + + + + org.apache.maven.plugins + maven-dependency-plugin + + + unpack + initialize + + unpack + + + + + fish.payara.distributions + payara + ${payara.version} + zip + false + ${project.build.directory} + + + + + + + + + + io.fabric8 + docker-maven-plugin + true + + + + base + %g/base:jdk${target.java.version} + ${ct.registry} + + Dockerfile + + openjdk:${target.java.version}-jre + + @ + + assembly.xml + + + + + + + + + + + \ No newline at end of file diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile new file mode 100644 index 00000000000..635fbd89142 --- /dev/null +++ b/modules/container-base/src/main/docker/Dockerfile @@ -0,0 +1,204 @@ +# Copyright 2019 Forschungszentrum Jülich GmbH +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# http://www.apache.org/licenses/LICENSE-2.0 +# +################################################################################################################ +# +# THIS FILE IS TO BE USED WITH MAVEN DOCKER BUILD: +# mvn -Pct clean package docker:build +# +################################################################################################################ +# +# Some commands used are inspired by https://github.com/payara/Payara/tree/master/appserver/extras/docker-images. +# Most parts origin from older versions of https://github.com/gdcc/dataverse-kubernetes. +# +# We are not using upstream Payara images because: +# - Using same base image as Solr (https://hub.docker.com/_/solr) is reducing pulls +# - Their image is less optimised for production usage by design choices +# + +# Make the Java base image and version configurable (useful for trying newer Java versions and flavors) +ARG BASE_IMAGE="openjdk:11-jre" +FROM $BASE_IMAGE + +# Default payara ports to expose +# 4848: admin console +# 9009: debug port (JPDA) +# 8080: http +# 8181: https +EXPOSE 4848 9009 8080 8181 + +ENV HOME_DIR="/opt/payara" +ENV PAYARA_DIR="${HOME_DIR}/appserver" \ + SCRIPT_DIR="${HOME_DIR}/scripts" \ + CONFIG_DIR="${HOME_DIR}/config" \ + DEPLOY_DIR="${HOME_DIR}/deployments" \ + DOCROOT_DIR="/docroot" \ + SECRETS_DIR="/secrets" \ + DUMPS_DIR="/dumps" \ + PASSWORD_FILE="${HOME_DIR}/passwordFile" \ + ADMIN_USER="admin" \ + ADMIN_PASSWORD="admin" \ + DOMAIN_NAME="domain1" \ + PAYARA_ARGS="" +ENV PATH="${PATH}:${PAYARA_DIR}/bin" \ + DOMAIN_DIR="${PAYARA_DIR}/glassfish/domains/${DOMAIN_NAME}" \ + DEPLOY_PROPS="" \ + PREBOOT_COMMANDS="${CONFIG_DIR}/pre-boot-commands.asadmin" \ + POSTBOOT_COMMANDS="${CONFIG_DIR}/post-boot-commands.asadmin" \ + JVM_ARGS="" \ + MEM_MAX_RAM_PERCENTAGE="70.0" \ + MEM_XSS="512k" \ + # Source: https://github.com/fabric8io-images/run-java-sh/blob/master/TUNING.md#recommandations + MEM_MIN_HEAP_FREE_RATIO="20" \ + MEM_MAX_HEAP_FREE_RATIO="40" \ + MEM_MAX_GC_PAUSE_MILLIS="500" \ + MEM_METASPACE_SIZE="256m" \ + MEM_MAX_METASPACE_SIZE="2g" \ + # Make heap dumps on OOM appear in DUMPS_DIR + ENABLE_DUMPS=0 \ + JVM_DUMPS_ARG="-XX:+HeapDumpOnOutOfMemoryError" + +ARG ESH_VERSION=0.3.1 +ARG ESH_CHECKSUM="1e0bd783f930cba13d6708b11c1ac844bbb1eddd02ac1666fc10d47eb9517bd7" +ARG JATTACH_VERSION="v2.0" +ARG JATTACH_CHECKSUM="989dc53279c7fb3ec399dbff1692647439286e5a4339c2849fd4323e998af7f8" +ARG PKGS="jq imagemagick curl unzip wget acl dirmngr gpg lsof procps netcat tini" +ARG ASADMIN="${PAYARA_DIR}/bin/asadmin --user=${ADMIN_USER} --passwordfile=${PASSWORD_FILE}" + +### PART 1: SYSTEM ### +USER root +WORKDIR / +SHELL ["/bin/bash", "-euo", "pipefail", "-c"] +RUN true && \ + # Create pathes + mkdir -p "${HOME_DIR}" "${PAYARA_DIR}" "${DEPLOY_DIR}" "${CONFIG_DIR}" "${SCRIPT_DIR}" && \ + mkdir -p "${DOCROOT_DIR}" "${SECRETS_DIR}" "${DUMPS_DIR}" && \ + # Create user + addgroup --gid 1000 payara && \ + adduser --system --uid 1000 --no-create-home --shell /bin/bash --home "${HOME_DIR}" --gecos "" --ingroup payara payara && \ + echo payara:payara | chpasswd && \ + # Set permissions + chown -R payara: "${HOME_DIR}" && \ + chown -R payara: "${DOCROOT_DIR}" "${SECRETS_DIR}" "${DUMPS_DIR}" + +# Installing the packages in an extra container layer for better caching +RUN true && \ + # Install packages + apt-get update -q && \ + apt-get install -qqy --no-install-recommends ${PKGS} && \ + # Download & check esh template script + curl -sSfL -o /usr/bin/esh "https://raw.githubusercontent.com/jirutka/esh/v${ESH_VERSION}/esh" && \ + echo "${ESH_CHECKSUM} /usr/bin/esh" | sha256sum -c - && \ + chmod +x /usr/bin/esh && \ + # Install jattach + curl -sSfL -o /usr/bin/jattach "https://github.com/apangin/jattach/releases/download/${JATTACH_VERSION}/jattach" && \ + echo "${JATTACH_CHECKSUM} /usr/bin/jattach" | sha256sum -c - && \ + chmod +x /usr/bin/jattach && \ + # Cleanup + rm -rf "/var/lib/apt/lists/*" + +### PART 2: PAYARA ### +# After setting up system, now configure Payara +USER payara +WORKDIR ${HOME_DIR} + +# Copy Payara from build context (cached by Maven) +COPY --chown=payara:payara maven/appserver ${PAYARA_DIR}/ + +# Copy the system (appserver level) scripts like entrypoint, etc +COPY --chown=payara:payara maven/scripts ${SCRIPT_DIR}/ + +# Configure the domain to be container and production ready +RUN true && \ + # Set admin password + echo "AS_ADMIN_PASSWORD=" > /tmp/password-change-file.txt && \ + echo "AS_ADMIN_NEWPASSWORD=${ADMIN_PASSWORD}" >> /tmp/password-change-file.txt && \ + echo "AS_ADMIN_PASSWORD=${ADMIN_PASSWORD}" >> ${PASSWORD_FILE} && \ + asadmin --user=${ADMIN_USER} --passwordfile=/tmp/password-change-file.txt change-admin-password --domain_name=${DOMAIN_NAME} && \ + # Start domain for configuration + ${ASADMIN} start-domain ${DOMAIN_NAME} && \ + # Allow access to admin with password only + ${ASADMIN} enable-secure-admin && \ + ### CONTAINER USAGE ENABLEMENT + # List & delete memory settings from domain + for MEMORY_JVM_OPTION in $(${ASADMIN} list-jvm-options | grep "Xm[sx]\|Xss\|NewRatio"); \ + do \ + ${ASADMIN} delete-jvm-options $(echo $MEMORY_JVM_OPTION | sed -e 's/:/\\:/g'); \ + done && \ + # Tweak memory settings for containers + ${ASADMIN} create-jvm-options "-XX\:+UseContainerSupport" && \ + ${ASADMIN} create-jvm-options "-XX\:MaxRAMPercentage=\${ENV=MEM_MAX_RAM_PERCENTAGE}" && \ + ${ASADMIN} create-jvm-options "-Xss\${ENV=MEM_XSS}" && \ + ${ASADMIN} create-jvm-options "-XX\:MinHeapFreeRatio=\${ENV=MEM_MIN_HEAP_FREE_RATIO}" && \ + ${ASADMIN} create-jvm-options "-XX\:MaxHeapFreeRatio=\${ENV=MEM_MAX_HEAP_FREE_RATIO}" && \ + ${ASADMIN} create-jvm-options "-XX\:HeapDumpPath=\${ENV=DUMPS_DIR}" && \ + # Set logging to console only for containers + ${ASADMIN} set-log-attributes com.sun.enterprise.server.logging.GFFileHandler.logtoFile=false && \ + ### PRODUCTION READINESS + ${ASADMIN} create-jvm-options '-XX\:+UseG1GC' && \ + ${ASADMIN} create-jvm-options '-XX\:+UseStringDeduplication' && \ + ${ASADMIN} create-jvm-options '-XX\:MaxGCPauseMillis=${ENV=MEM_MAX_GC_PAUSE_MILLIS}' && \ + ${ASADMIN} create-jvm-options '-XX\:MetaspaceSize=${ENV=MEM_METASPACE_SIZE}' && \ + ${ASADMIN} create-jvm-options '-XX\:MaxMetaspaceSize=${ENV=MEM_MAX_METASPACE_SIZE}' && \ + ${ASADMIN} create-jvm-options '-XX\:+IgnoreUnrecognizedVMOptions' && \ + # Enlarge thread pools + ${ASADMIN} set server-config.thread-pools.thread-pool.http-thread-pool.max-thread-pool-size="50" && \ + ${ASADMIN} set server-config.thread-pools.thread-pool.http-thread-pool.max-queue-size="" && \ + ${ASADMIN} set default-config.thread-pools.thread-pool.thread-pool-1.max-thread-pool-size="250" && \ + # Enable file caching + ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-1.http.file-cache.enabled="true" && \ + ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-2.http.file-cache.enabled="true" && \ + ${ASADMIN} set default-config.network-config.protocols.protocol.http-listener-1.http.file-cache.enabled="true" && \ + ${ASADMIN} set default-config.network-config.protocols.protocol.http-listener-2.http.file-cache.enabled="true" && \ + # Enlarge EJB pools (cannot do this for server-config as set does not create new entries) + ${ASADMIN} set default-config.ejb-container.max-pool-size="128" && \ + # Misc settings + ${ASADMIN} create-system-properties fish.payara.classloading.delegate="false" && \ + ${ASADMIN} create-system-properties jersey.config.client.readTimeout="300000" && \ + ${ASADMIN} create-system-properties jersey.config.client.connectTimeout="300000" && \ + ### DATAVERSE APPLICATION SPECIFICS + # Configure the MicroProfile directory config source to point to /secrets + ${ASADMIN} set-config-dir --directory="${SECRETS_DIR}" && \ + # Make request timeouts configurable via MPCONFIG (default to 900 secs = 15 min) + ${ASADMIN} set 'server-config.network-config.protocols.protocol.http-listener-1.http.request-timeout-seconds=${MPCONFIG=dataverse.http.timeout:900}' && \ + # TODO: what of the below 3 items can be deleted for container usage? + ${ASADMIN} create-network-listener --protocol=http-listener-1 --listenerport=8009 --jkenabled=true jk-connector && \ + ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-1.http.comet-support-enabled=true && \ + ${ASADMIN} create-system-properties javax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl && \ + # Always disable phoning home... + ${ASADMIN} disable-phone-home && \ + ### CLEANUP + # Stop domain + ${ASADMIN} stop-domain "${DOMAIN_NAME}" && \ + # Delete generated files + rm -rf \ + "/tmp/password-change-file.txt" \ + "${PAYARA_DIR}/glassfish/domains/${DOMAIN_NAME}/osgi-cache" \ + "${PAYARA_DIR}/glassfish/domains/${DOMAIN_NAME}/logs" + +# Make docroot of Payara reside in higher level directory for easier targeting +# Due to gdcc/dataverse-kubernetes#177: create the generated pathes so they are +# writeable by us. TBR with gdcc/dataverse-kubernetes#178. +RUN rm -rf "${DOMAIN_DIR}"/docroot && \ + ln -s "${DOCROOT_DIR}" "${DOMAIN_DIR}"/docroot && \ + mkdir -p "${DOMAIN_DIR}"/generated/jsp/dataverse + +# Set the entrypoint to tini (as a process supervisor) +ENTRYPOINT ["/usr/bin/tini", "--"] +# JSON syntax should be used, but bypassed shell. Thus re-add expansion via shell exec. +CMD ["sh", "-c", "${SCRIPT_DIR}/entrypoint.sh"] + +LABEL org.opencontainers.image.created="@git.build.time@" \ + org.opencontainers.image.authors="Research Data Management at FZJ " \ + org.opencontainers.image.url="https://k8s-docs.gdcc.io" \ + org.opencontainers.image.documentation="https://k8s-docs.gdcc.io" \ + org.opencontainers.image.source="https://github.com/gdcc/dataverse/tree/develop%2Bct/modules/container-base" \ + org.opencontainers.image.version="@project.version@" \ + org.opencontainers.image.revision="@git.commit.id.abbrev@" \ + org.opencontainers.image.vendor="Global Dataverse Community Consortium" \ + org.opencontainers.image.licenses="Apache-2.0" \ + org.opencontainers.image.title="dataverse-k8s :: Dataverse containerized" \ + org.opencontainers.image.description="This container image provides an application server tuned for Dataverse software" diff --git a/modules/container-base/src/main/docker/assembly.xml b/modules/container-base/src/main/docker/assembly.xml new file mode 100644 index 00000000000..afd5530fa60 --- /dev/null +++ b/modules/container-base/src/main/docker/assembly.xml @@ -0,0 +1,17 @@ + + + + + ${project.basedir}/target/payara5 + appserver + + + + ${project.basedir}/src/main/docker/scripts + scripts + 0755 + + + \ No newline at end of file diff --git a/modules/container-base/src/main/docker/scripts/entrypoint.sh b/modules/container-base/src/main/docker/scripts/entrypoint.sh new file mode 100644 index 00000000000..6f71dfe013c --- /dev/null +++ b/modules/container-base/src/main/docker/scripts/entrypoint.sh @@ -0,0 +1,17 @@ +#!/bin/bash +########################################################################################################## +# +# This script is a fork of https://github.com/payara/Payara/blob/master/appserver/extras/docker-images/ +# server-full/src/main/docker/bin/entrypoint.sh and licensed under CDDL 1.1 by the Payara Foundation. +# +########################################################################################################## + +for f in "${SCRIPT_DIR}"/init_* "${SCRIPT_DIR}"/init.d/*; do + case "$f" in + *.sh) echo "[Entrypoint] running $f"; . "$f" ;; + *) echo "[Entrypoint] ignoring $f" ;; + esac + echo +done + +exec "${SCRIPT_DIR}"/startInForeground.sh "${PAYARA_ARGS}" diff --git a/modules/container-base/src/main/docker/scripts/init_1_generate_deploy_commands.sh b/modules/container-base/src/main/docker/scripts/init_1_generate_deploy_commands.sh new file mode 100644 index 00000000000..e2d717af666 --- /dev/null +++ b/modules/container-base/src/main/docker/scripts/init_1_generate_deploy_commands.sh @@ -0,0 +1,65 @@ +#!/bin/bash +########################################################################################################## +# +# A script to append deploy commands to the post boot command file at +# $PAYARA_HOME/scripts/post-boot-commands.asadmin file. All applications in the +# $DEPLOY_DIR (either files or folders) will be deployed. +# The $POSTBOOT_COMMANDS file can then be used with the start-domain using the +# --postbootcommandfile parameter to deploy applications on startup. +# +# Usage: +# ./generate_deploy_commands.sh +# +# Optionally, any number of parameters of the asadmin deploy command can be +# specified as parameters to this script. +# E.g., to deploy applications with implicit CDI scanning disabled: +# +# ./generate_deploy_commands.sh --properties=implicitCdiEnabled=false +# +# Environment variables used: +# - $PREBOOT_COMMANDS - the pre boot command file. +# - $POSTBOOT_COMMANDS - the post boot command file. +# +# Note that many parameters to the deploy command can be safely used only when +# a single application exists in the $DEPLOY_DIR directory. +# +########################################################################################################## +# +# This script is a fork of https://github.com/payara/Payara/blob/master/appserver/extras/docker-images/ +# server-full/src/main/docker/bin/init_1_generate_deploy_commands.sh and licensed under CDDL 1.1 +# by the Payara Foundation. +# +########################################################################################################## + +# Check required variables are set +if [ -z "$DEPLOY_DIR" ]; then echo "Variable DEPLOY_DIR is not set."; exit 1; fi +if [ -z "$PREBOOT_COMMANDS" ]; then echo "Variable PREBOOT_COMMANDS is not set."; exit 1; fi +if [ -z "$POSTBOOT_COMMANDS" ]; then echo "Variable POSTBOOT_COMMANDS is not set."; exit 1; fi + +# Create pre and post boot command files if they don't exist +touch "$POSTBOOT_COMMANDS" +touch "$PREBOOT_COMMANDS" + +deploy() { + + if [ -z "$1" ]; then + echo "No deployment specified"; + exit 1; + fi + + DEPLOY_STATEMENT="deploy $DEPLOY_PROPS $1" + if grep -q "$1" "$POSTBOOT_COMMANDS"; then + echo "post boot commands already deploys $1"; + else + echo "Adding deployment target $1 to post boot commands"; + echo "$DEPLOY_STATEMENT" >> "$POSTBOOT_COMMANDS"; + fi +} + +# RAR files first +find "$DEPLOY_DIR" -mindepth 1 -maxdepth 1 -name "*.rar" -print0 \ + | while IFS= read -r -d '' file; do deploy "$file"; done + +# Then every other WAR, EAR, JAR or directory +find "$DEPLOY_DIR" -mindepth 1 -maxdepth 1 ! -name "*.rar" -a -name "*.war" -o -name "*.ear" -o -name "*.jar" -o -type d -print0 \ + | while IFS= read -r -d '' file; do deploy "$file"; done \ No newline at end of file diff --git a/modules/container-base/src/main/docker/scripts/startInForeground.sh b/modules/container-base/src/main/docker/scripts/startInForeground.sh new file mode 100644 index 00000000000..4843f6ae055 --- /dev/null +++ b/modules/container-base/src/main/docker/scripts/startInForeground.sh @@ -0,0 +1,89 @@ +#!/bin/bash +########################################################################################################## +# +# This script is to execute Payara Server in foreground, mainly in a docker environment. +# It allows to avoid running 2 instances of JVM, which happens with the start-domain --verbose command. +# +# Usage: +# Running +# startInForeground.sh +# is equivalent to running +# asadmin start-domain +# +# It's possible to use any arguments of the start-domain command as arguments to startInForeground.sh +# +# Environment variables used: +# - $ADMIN_USER - the username to use for the asadmin utility. +# - $PASSWORD_FILE - the password file to use for the asadmin utility. +# - $PREBOOT_COMMANDS - the pre boot command file. +# - $POSTBOOT_COMMANDS - the post boot command file. +# - $DOMAIN_NAME - the name of the domain to start. +# - $JVM_ARGS - extra JVM options to pass to the Payara Server instance. +# - $AS_ADMIN_MASTERPASSWORD - the master password for the Payara Server instance. +# +# This script executes the asadmin tool which is expected at ~/appserver/bin/asadmin. +# +########################################################################################################## +# +# This script is a fork of https://github.com/payara/Payara/blob/master/appserver/ +# extras/docker-images/server-full/src/main/docker/bin/startInForeground.sh and licensed under CDDL 1.1 +# by the Payara Foundation. +# +########################################################################################################## + +# Check required variables are set +if [ -z "$ADMIN_USER" ]; then echo "Variable ADMIN_USER is not set."; exit 1; fi +if [ -z "$PASSWORD_FILE" ]; then echo "Variable PASSWORD_FILE is not set."; exit 1; fi +if [ -z "$PREBOOT_COMMANDS" ]; then echo "Variable PREBOOT_COMMANDS is not set."; exit 1; fi +if [ -z "$POSTBOOT_COMMANDS" ]; then echo "Variable POSTBOOT_COMMANDS is not set."; exit 1; fi +if [ -z "$DOMAIN_NAME" ]; then echo "Variable DOMAIN_NAME is not set."; exit 1; fi + +# Check if dumps are enabled - add arg to JVM_ARGS in this case +if [ -n "${ENABLE_DUMPS}" ] && [ "${ENABLE_DUMPS}" = "1" ]; then + JVM_ARGS="${JVM_DUMPS_ARG} ${JVM_ARGS}" +fi + +# The following command gets the command line to be executed by start-domain +# - print the command line to the server with --dry-run, each argument on a separate line +# - remove -read-string argument +# - surround each line except with parenthesis to allow spaces in paths +# - remove lines before and after the command line and squash commands on a single line + +# Create pre and post boot command files if they don't exist +touch "$POSTBOOT_COMMANDS" +touch "$PREBOOT_COMMANDS" + +# shellcheck disable=SC2068 +# -- Using $@ is necessary here as asadmin cannot deal with options enclosed in ""! +OUTPUT=$("${PAYARA_DIR}"/bin/asadmin --user="${ADMIN_USER}" --passwordfile="${PASSWORD_FILE}" start-domain --dry-run --prebootcommandfile="${PREBOOT_COMMANDS}" --postbootcommandfile="${POSTBOOT_COMMANDS}" $@ "$DOMAIN_NAME") +STATUS=$? +if [ "$STATUS" -ne 0 ] + then + echo ERROR: "$OUTPUT" >&2 + exit 1 +fi + +COMMAND=$(echo "$OUTPUT"\ + | sed -n -e '2,/^$/p'\ + | sed "s|glassfish.jar|glassfish.jar $JVM_ARGS |g") + +echo Executing Payara Server with the following command line: +echo "$COMMAND" | tr ' ' '\n' +echo + +# Run the server in foreground - read master password from variable or file or use the default "changeit" password + +set +x +if test "$AS_ADMIN_MASTERPASSWORD"x = x -a -f "$PASSWORD_FILE" + then + # shellcheck disable=SC1090 + source "$PASSWORD_FILE" +fi +if test "$AS_ADMIN_MASTERPASSWORD"x = x + then + AS_ADMIN_MASTERPASSWORD=changeit +fi +echo "AS_ADMIN_MASTERPASSWORD=$AS_ADMIN_MASTERPASSWORD" > /tmp/masterpwdfile +# shellcheck disable=SC2086 +# -- Unquoted exec var is necessary, as otherwise things get escaped that may not be escaped (parameters for Java) +exec ${COMMAND} < /tmp/masterpwdfile diff --git a/modules/dataverse-parent/pom.xml b/modules/dataverse-parent/pom.xml index 14b84f80279..4db2232be7d 100644 --- a/modules/dataverse-parent/pom.xml +++ b/modules/dataverse-parent/pom.xml @@ -182,6 +182,10 @@ 3.0.0-M5 3.3.0 3.1.2 + + + 0.39.1 + ghcr.io @@ -244,6 +248,11 @@ + + io.fabric8 + docker-maven-plugin + ${fabric8-dmp.version} + @@ -315,4 +324,46 @@ --> + + + ct + + + 5.2022.1 + + + + + + + io.github.git-commit-id + git-commit-id-maven-plugin + 5.0.0 + + + retrieve-git-details + + revision + + initialize + + + + ${project.basedir}/../../.git + UTC + 8 + false + + + + + + + + From 2319a4787e0c4e41b633382ed7c9684130933be8 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 16 Jun 2022 21:22:41 +0200 Subject: [PATCH 02/60] feat(ct-base): remove the esh tool Will be replaced with a capability to make API endpoints for authentication providers read from MPCONFIG sources. --- modules/container-base/src/main/docker/Dockerfile | 6 ------ 1 file changed, 6 deletions(-) diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index 635fbd89142..491c0747ada 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -61,8 +61,6 @@ ENV PATH="${PATH}:${PAYARA_DIR}/bin" \ ENABLE_DUMPS=0 \ JVM_DUMPS_ARG="-XX:+HeapDumpOnOutOfMemoryError" -ARG ESH_VERSION=0.3.1 -ARG ESH_CHECKSUM="1e0bd783f930cba13d6708b11c1ac844bbb1eddd02ac1666fc10d47eb9517bd7" ARG JATTACH_VERSION="v2.0" ARG JATTACH_CHECKSUM="989dc53279c7fb3ec399dbff1692647439286e5a4339c2849fd4323e998af7f8" ARG PKGS="jq imagemagick curl unzip wget acl dirmngr gpg lsof procps netcat tini" @@ -89,10 +87,6 @@ RUN true && \ # Install packages apt-get update -q && \ apt-get install -qqy --no-install-recommends ${PKGS} && \ - # Download & check esh template script - curl -sSfL -o /usr/bin/esh "https://raw.githubusercontent.com/jirutka/esh/v${ESH_VERSION}/esh" && \ - echo "${ESH_CHECKSUM} /usr/bin/esh" | sha256sum -c - && \ - chmod +x /usr/bin/esh && \ # Install jattach curl -sSfL -o /usr/bin/jattach "https://github.com/apangin/jattach/releases/download/${JATTACH_VERSION}/jattach" && \ echo "${JATTACH_CHECKSUM} /usr/bin/jattach" | sha256sum -c - && \ From f0202cb2c177c5ebeeb176c58c8b27256d32697b Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 17 Jun 2022 10:29:37 +0200 Subject: [PATCH 03/60] chore(deps): update container plugin and payara version for containers --- modules/dataverse-parent/pom.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/dataverse-parent/pom.xml b/modules/dataverse-parent/pom.xml index 4db2232be7d..fa693f8a8ac 100644 --- a/modules/dataverse-parent/pom.xml +++ b/modules/dataverse-parent/pom.xml @@ -184,7 +184,7 @@ 3.1.2 - 0.39.1 + 0.40.1 ghcr.io @@ -334,7 +334,7 @@ See also: https://github.com/IQSS/dataverse/issues/8048 See also: https://github.com/payara/Payara/issues/5368 --> - 5.2022.1 + 5.2022.2 From 2dc0596d8634cadecb691b95a39ba5a3355fcd99 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 11 Aug 2022 13:54:41 +0200 Subject: [PATCH 04/60] fix(ct-base): unpack Payara to target/payara Payara 5 defaults to a "payara5" topmost dir, Payara 6 to "payara6". To avoid adding different directories in the assembly, cut the number from the directories name when unpacking. This does not prevent you from doing stupid things like not cleaning before switching the version leading to an unknown state of old and new libs, etc. --- modules/container-base/pom.xml | 6 ++++++ modules/container-base/src/main/docker/assembly.xml | 2 +- 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index 8cb7e1ac795..765a4c72843 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -51,6 +51,12 @@ zip false ${project.build.directory} + + + ^payara\d + payara + + diff --git a/modules/container-base/src/main/docker/assembly.xml b/modules/container-base/src/main/docker/assembly.xml index afd5530fa60..9fc62d49fa1 100644 --- a/modules/container-base/src/main/docker/assembly.xml +++ b/modules/container-base/src/main/docker/assembly.xml @@ -4,7 +4,7 @@ - ${project.basedir}/target/payara5 + ${project.basedir}/target/payara appserver From 246f8b8cbfd18356c6f2cb63481d1fa02afad390 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 11 Aug 2022 14:03:19 +0200 Subject: [PATCH 05/60] fix(ct-base): migrate base image from OpenJDK to Eclipse Temurin There was an ongoing discussion that the Docker Hub Image "openjdk" is not backed by any official supported project but complete goodwill of Oracle shipping their JRE/JDK. There is no "real" release of OpenJDK . There exist only real distributions like Oracle JDK, Eclipse Temurin, Azul JDK, AWS Corretto etc (see https://whichjdk.com). As for this reason the "openjdk" image has been deprecated, switching to Eclipse Temurin JRE here. See also: https://github.com/docker-library/openjdk/issues/505 --- modules/container-base/pom.xml | 2 +- modules/container-base/src/main/docker/Dockerfile | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index 765a4c72843..5ebaa9ea323 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -78,7 +78,7 @@ Dockerfile - openjdk:${target.java.version}-jre + eclipse-temurin:${target.java.version}-jre @ diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index 491c0747ada..2fed83db59f 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -20,7 +20,7 @@ # # Make the Java base image and version configurable (useful for trying newer Java versions and flavors) -ARG BASE_IMAGE="openjdk:11-jre" +ARG BASE_IMAGE="eclipse-temurin:11-jre" FROM $BASE_IMAGE # Default payara ports to expose From 76ea50871bafe028d1edad35f441e7731398ed00 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 11 Aug 2022 14:05:06 +0200 Subject: [PATCH 06/60] chore(deps): update Docker Maven Plugin to the latest release --- modules/dataverse-parent/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/dataverse-parent/pom.xml b/modules/dataverse-parent/pom.xml index fa693f8a8ac..eaa09b61bd7 100644 --- a/modules/dataverse-parent/pom.xml +++ b/modules/dataverse-parent/pom.xml @@ -184,7 +184,7 @@ 3.1.2 - 0.40.1 + 0.40.2 ghcr.io From f62dee2ec6a5dd237e2fbc10346bdebeb6a3c2f1 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 11 Aug 2022 15:13:48 +0200 Subject: [PATCH 07/60] feat(ct-base): enable multiarch image build via docker buildx With the rise of Apple M1/M2 silicons, we need to provide ARM64 based images in addition to AMD64. --- modules/container-base/pom.xml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index 5ebaa9ea323..add8a120a58 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -76,6 +76,12 @@ %g/base:jdk${target.java.version} ${ct.registry} + + + linux/arm64 + linux/amd64 + + Dockerfile eclipse-temurin:${target.java.version}-jre From 72935d481e1e1ab260e763a000bfef172629cc16 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 12 Aug 2022 12:08:13 +0200 Subject: [PATCH 08/60] chore(ct-base): add maintainer details to POM --- modules/container-base/pom.xml | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index add8a120a58..015ebba598d 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -16,6 +16,18 @@ Container Base Image This module provides an application server base image to be decorated with the Dataverse app. + + + poikilotherm + Oliver Bertuch + github@bertuch.eu + Europe/Berlin + + maintainer + + + + From 17d8b53bb985fc77faebc8273b84012fac2bb525 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 12 Aug 2022 12:09:21 +0200 Subject: [PATCH 09/60] docs(ct-base): update OCI tag labels --- modules/container-base/src/main/docker/Dockerfile | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index 2fed83db59f..036e2f17831 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -187,12 +187,12 @@ CMD ["sh", "-c", "${SCRIPT_DIR}/entrypoint.sh"] LABEL org.opencontainers.image.created="@git.build.time@" \ org.opencontainers.image.authors="Research Data Management at FZJ " \ - org.opencontainers.image.url="https://k8s-docs.gdcc.io" \ - org.opencontainers.image.documentation="https://k8s-docs.gdcc.io" \ - org.opencontainers.image.source="https://github.com/gdcc/dataverse/tree/develop%2Bct/modules/container-base" \ + org.opencontainers.image.url="https://guides.dataverse.org/en/latest/container/" \ + org.opencontainers.image.documentation="https://guides.dataverse.org/en/latest/container/" \ + org.opencontainers.image.source="https://github.com/IQSS/dataverse/tree/develop/modules/container-base" \ org.opencontainers.image.version="@project.version@" \ org.opencontainers.image.revision="@git.commit.id.abbrev@" \ org.opencontainers.image.vendor="Global Dataverse Community Consortium" \ org.opencontainers.image.licenses="Apache-2.0" \ - org.opencontainers.image.title="dataverse-k8s :: Dataverse containerized" \ + org.opencontainers.image.title="Dataverse Base Image" \ org.opencontainers.image.description="This container image provides an application server tuned for Dataverse software" From 0a9947bd6868b9b45314b6fe0cfc918c48ed4eeb Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 12 Aug 2022 12:11:14 +0200 Subject: [PATCH 10/60] feat(ct-base): add debug/develop mode script --- .../container-base/src/main/docker/Dockerfile | 4 +- .../init_1_generate_devmode_commands.sh | 61 +++++++++++++++++++ 2 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 modules/container-base/src/main/docker/scripts/init_1_generate_devmode_commands.sh diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index 036e2f17831..fe44fc61847 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -59,7 +59,9 @@ ENV PATH="${PATH}:${PAYARA_DIR}/bin" \ MEM_MAX_METASPACE_SIZE="2g" \ # Make heap dumps on OOM appear in DUMPS_DIR ENABLE_DUMPS=0 \ - JVM_DUMPS_ARG="-XX:+HeapDumpOnOutOfMemoryError" + JVM_DUMPS_ARG="-XX:+HeapDumpOnOutOfMemoryError" \ + ENABLE_JMX=0 \ + ENABLE_JDWP=0 ARG JATTACH_VERSION="v2.0" ARG JATTACH_CHECKSUM="989dc53279c7fb3ec399dbff1692647439286e5a4339c2849fd4323e998af7f8" diff --git a/modules/container-base/src/main/docker/scripts/init_1_generate_devmode_commands.sh b/modules/container-base/src/main/docker/scripts/init_1_generate_devmode_commands.sh new file mode 100644 index 00000000000..9d71e3bb81b --- /dev/null +++ b/modules/container-base/src/main/docker/scripts/init_1_generate_devmode_commands.sh @@ -0,0 +1,61 @@ +#!/bin/bash + +set -euo pipefail + +###### ###### ###### ###### ###### ###### ###### ###### ###### ###### ###### +# This script enables different development options, like a JMX connector +# usable with VisualVM, JRebel hot-reload support and JDWP debugger service. +# Enable it by adding env vars on startup (e.g. via ConfigMap) +# +# As this script is "sourced" from entrypoint.sh, we can manipulate env vars +# for the parent shell before executing Payara. +###### ###### ###### ###### ###### ###### ###### ###### ###### ###### ###### + +# 0. Init variables +ENABLE_JMX=${ENABLE_JMX:-0} +ENABLE_JDWP=${ENABLE_JDWP:-0} + +DV_PREBOOT=${PAYARA_DIR}/dataverse_preboot +echo "# Dataverse preboot configuration for Payara" > "${DV_PREBOOT}" + +# 1. Configure JMX (enabled by default on port 8686, but requires SSL) +# See also https://blog.payara.fish/monitoring-payara-server-with-jconsole +# To still use it, you can use a sidecar container proxying or using JMX via localhost without SSL. +if [ "${ENABLE_JMX}" = "1" ]; then + echo "Enabling unsecured JMX on 0.0.0.0:8686. You'll need a sidecar for this, as access is allowed from same machine only (without SSL)." + { \ + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.jvm=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.connector-service=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.connector-connection-pool=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.jdbc-connection-pool=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.web-services-container=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.ejb-container=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.thread-pool=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.http-service=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.security=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.jms-service=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.jersey=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.transaction-service=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.jpa=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.web-container=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.orb=HIGH" + echo "set configs.config.server-config.monitoring-service.module-monitoring-levels.deployment=HIGH" + #echo "set configs.config.server-config.admin-service.jmx-connector.system.address=127.0.0.1" + echo "set configs.config.server-config.admin-service.jmx-connector.system.security-enabled=false" + } >> "${DV_PREBOOT}" +fi + +# 2. Enable JDWP via debugging switch +if [ "${ENABLE_JDWP}" = "1" ]; then + echo "Enabling JDWP remote debugging support via asadmin debugging switch." + export PAYARA_ARGS="${PAYARA_ARGS} --debug=true" +fi + +# 3. Add the commands to the existing preboot file, but insert BEFORE deployment +TMP_PREBOOT=$(mktemp) +cat "${DV_PREBOOT}" "${PREBOOT_COMMANDS}" > "${TMP_PREBOOT}" +mv "${TMP_PREBOOT}" "${PREBOOT_COMMANDS}" +echo "DEBUG: preboot contains the following commands:" +echo "--------------------------------------------------" +cat "${PREBOOT_COMMANDS}" +echo "--------------------------------------------------" \ No newline at end of file From 2e812dcc15413d5814072b86971b924ee13824e4 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Mon, 22 Aug 2022 13:50:48 +0200 Subject: [PATCH 11/60] deps(ct-base): update to jattach v2.1 --- modules/container-base/src/main/docker/Dockerfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index fe44fc61847..d13808c3272 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -63,8 +63,8 @@ ENV PATH="${PATH}:${PAYARA_DIR}/bin" \ ENABLE_JMX=0 \ ENABLE_JDWP=0 -ARG JATTACH_VERSION="v2.0" -ARG JATTACH_CHECKSUM="989dc53279c7fb3ec399dbff1692647439286e5a4339c2849fd4323e998af7f8" +ARG JATTACH_VERSION="v2.1" +ARG JATTACH_CHECKSUM="07885fdc782e02e7302c6d190f54c3930afa10a38140365adf54076ec1086a8e" ARG PKGS="jq imagemagick curl unzip wget acl dirmngr gpg lsof procps netcat tini" ARG ASADMIN="${PAYARA_DIR}/bin/asadmin --user=${ADMIN_USER} --passwordfile=${PASSWORD_FILE}" From 7e836c70dd44a538bf1fdd0d73045730da053951 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 23 Aug 2022 00:10:24 +0200 Subject: [PATCH 12/60] chore(ct-base): add JMX to exposed ports and make it default enabled as in Payara --- modules/container-base/src/main/docker/Dockerfile | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index d13808c3272..ba459607826 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -25,10 +25,11 @@ FROM $BASE_IMAGE # Default payara ports to expose # 4848: admin console -# 9009: debug port (JPDA) +# 9009: debug port (JDWP) # 8080: http # 8181: https -EXPOSE 4848 9009 8080 8181 +# 8686: JMX +EXPOSE 4848 9009 8080 8181 8686 ENV HOME_DIR="/opt/payara" ENV PAYARA_DIR="${HOME_DIR}/appserver" \ @@ -60,7 +61,7 @@ ENV PATH="${PATH}:${PAYARA_DIR}/bin" \ # Make heap dumps on OOM appear in DUMPS_DIR ENABLE_DUMPS=0 \ JVM_DUMPS_ARG="-XX:+HeapDumpOnOutOfMemoryError" \ - ENABLE_JMX=0 \ + ENABLE_JMX=1 \ ENABLE_JDWP=0 ARG JATTACH_VERSION="v2.1" From fe7b2d06148e6a2e6d6b2939f366de9ea2162cff Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 23 Aug 2022 00:11:08 +0200 Subject: [PATCH 13/60] docs(ct): add container guide to guides index --- doc/sphinx-guides/source/container/index.rst | 26 ++++++++++++++++++++ doc/sphinx-guides/source/index.rst | 7 ++++-- 2 files changed, 31 insertions(+), 2 deletions(-) create mode 100644 doc/sphinx-guides/source/container/index.rst diff --git a/doc/sphinx-guides/source/container/index.rst b/doc/sphinx-guides/source/container/index.rst new file mode 100644 index 00000000000..1bf86f16f43 --- /dev/null +++ b/doc/sphinx-guides/source/container/index.rst @@ -0,0 +1,26 @@ +Container Guide +=============== + +**Contents:** + +.. toctree:: + + base-image + app-image + +Running Dataverse software in containers is quite different than in a :doc:`classic installation <../installation/prep>`. + +Both approaches have pros and cons. These days (2022) containers are very often used for development and testing, +but there is an ever rising move for running applications in the cloud using container technology. + +**NOTE:** +**As the "Institute for Quantitative Social Sciences" at Harvard is running their installations in the classic +deployment way, the container support is mostly created and maintained by the Dataverse community.** + +This guide is *not* about installation on technology like Docker Swarm, Kubernetes, Rancher or other +solutions to run containers in production. There is the `Dataverse on K8s project `_ for this +purpose. + +This guide focuses on describing the container images managed from the main Dataverse repository (again: by the +community, not IQSS), their features and limitations. Instructions on how to build the images yourself, how to +extend them and how to use them for development purposes may be found in respective subpages. \ No newline at end of file diff --git a/doc/sphinx-guides/source/index.rst b/doc/sphinx-guides/source/index.rst index f7e81756e5b..f15a973544d 100755 --- a/doc/sphinx-guides/source/index.rst +++ b/doc/sphinx-guides/source/index.rst @@ -19,17 +19,20 @@ These documentation guides are for the |version| version of Dataverse. To find g installation/index developers/index style/index + container/index How the Guides Are Organized ---------------------------- The guides are documentation that explain how to use Dataverse, which are divided into the following sections: User Guide, -Installation Guide, Developer Guide, API Guide and Style Guide. The User Guide is further divided into primary activities: finding & using +Installation Guide, Developer Guide, API Guide, Style Guide and Container Guide. +The User Guide is further divided into primary activities: finding & using data, adding Datasets, administering dataverses or Datasets, and Dataset exploration/visualizations. Details on all of the above tasks can be found in the Users Guide. The Installation Guide is for people or organizations who want to host their -own Dataverse. The Developer Guide contains instructions for +own Dataverse. The Container Guide adds to this information on container-based installations. +The Developer Guide contains instructions for people who want to contribute to the Open Source Dataverse project or who want to modify the code to suit their own needs. Finally, the API Guide is for Developers that work on other applications and are interested in connecting with Dataverse through our APIs. From a93dbbdb4c5d2cfed80a13f265238a59f551999a Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 23 Aug 2022 00:12:35 +0200 Subject: [PATCH 14/60] docs(ct-base): add extensive base image module documentation --- .../source/container/base-image.rst | 229 ++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 doc/sphinx-guides/source/container/base-image.rst diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst new file mode 100644 index 00000000000..4f441f79ad7 --- /dev/null +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -0,0 +1,229 @@ +Application Base Image +====================== + +Within the main repository, you may find the base image's files at ``/modules/container-base``. +This Maven module uses the `Maven Docker Plugin `_ to build and ship the image. + +Contents +++++++++ + +The base image provides: + +- `Eclipse Temurin JRE using Java 11 `_ +- `Payara Community Application Server `_ +- CLI tools necessary to run Dataverse (i. e. ``curl`` or ``jq`` - see also :doc:`../installation/prerequisites` in Installation Guide) +- Linux tools for analysis, monitoring and so on +- `Jattach `_ + +This image is created as a "multi-arch image", supporting the most common architectures Dataverse usually runs on: +AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2). + +It inherits being built on an Ubuntu environment from the upstream +`base image of Eclipse Temurin `_. +You are free to change the JRE/JDK image to your liking (see below). + + + +Build Instructions +++++++++++++++++++ + +Assuming you have `Docker `_, `Docker Desktop `_, +`Moby `_ or some remote Docker host configured, up and running from here on. + +Simply execute the Maven modules packaging target with activated "container profile. Either from the projects Git root: + +``mvn -Pct -f modules/container-base package`` + +Or move to the module and execute: + +``cd modules/container-base && mvn -Pct package`` + +Some additional notes, using Maven parameters to change the build and use ...: + +- ... a different Payara version: add ``-Dpayara.version=V.YYYY.R``. +- | ... a different Temurin JRE version ``A``: add ``-Dtarget.java.version=A`` (i.e. ``11``, ``17``, ...). + | *Note:* must resolve to an available Docker tag ``A-jre`` of Eclipse Temurin! +- ... a different Java Distribution: add ``-Ddocker.buildArg.BASE_IMAGE="name:tag"`` with precise reference to an + image available from local or remote (e. g. Docker Hub). + + + +Tunables +++++++++ + +The base image provides a Payara domain suited for production use, but can also be used during development. +Many settings have been carefully selected for best performance and stability of the Dataverse application. + +As with any service, you should always monitor any metrics and make use of the tuning capabilities the base image +provides. These are mostly based on environment variables (very common with containers) and provide sane defaults. + +.. list-table:: + :align: left + :width: 100 + :widths: 10 10 10 50 + :header-rows: 1 + + * - Env. variable + - Default + - Type + - Description + * - ``DEPLOY_PROPS`` + - (empty) + - String + - Set to add arguments to generated `asadmin deploy` commands. + * - ``PREBOOT_COMMANDS`` + - [preboot]_ + - Abs. path + - Provide path to file with ``asadmin`` commands to run **before** boot of application server. + See also `Pre/postboot script docs`_. + * - ``POSTBOOT_COMMANDS`` + - [postboot]_ + - Abs. path + - Provide path to file with ``asadmin`` commands to run **after** boot of application server. + See also `Pre/postboot script docs`_. + * - ``JVM_ARGS`` + - (empty) + - String + - Additional arguments to pass to application server's JVM on start. + * - ``MEM_MAX_RAM_PERCENTAGE`` + - ``70.0`` + - Percentage + - Maximum amount of container's allocated RAM to be used as heap space. + Make sure to leave some room for native memory, OS overhead etc! + * - ``MEM_XSS`` + - ``512k`` + - Size + - Tune the maximum JVM stack size. + * - ``MEM_MIN_HEAP_FREE_RATIO`` + - ``20`` + - Integer + - Make the heap shrink aggressively and grow conservatively. See also `run-java-sh recommendations`_. + * - ``MEM_MAX_HEAP_FREE_RATIO`` + - ``40`` + - Integer + - Make the heap shrink aggressively and grow conservatively. See also `run-java-sh recommendations`_. + * - ``MEM_MAX_GC_PAUSE_MILLIS`` + - ``500`` + - Milliseconds + - Shorter pause times might result in lots of collections causing overhead without much gain. + This needs monitoring and tuning. It's a complex matter. + * - ``MEM_METASPACE_SIZE`` + - ``256m`` + - Size + - Initial size of memory reserved for class metadata, also used as trigger to run a garbage collection + once passing this size. + * - ``MEM_MAX_METASPACE_SIZE`` + - ``2g`` + - Size + - The metaspace's size will not outgrow this limit. + * - ``ENABLE_DUMPS`` + - ``0`` + - Bool, ``0|1`` + - If enabled, the argument(s) given in ``JVM_DUMP_ARG`` will be added to the JVM starting up. + This means it will enable dumping the heap to ``${DUMPS_DIR}`` (see below) in "out of memory" cases. + (You should back this location with disk space / ramdisk, so it does not write into an overlay filesystem!) + * - ``JVM_DUMPS_ARG`` + - [dump-option]_ + - String + - Can be fine tuned for more grained controls of dumping behaviour. + * - ``ENABLE_JMX`` + - ``1`` + - Bool, ``0|1`` + - Enable JMX - Payara enables this by default, hard to deactivate. + * - ``ENABLE_JDWP`` + - ``0`` + - Bool, ``0|1`` + - Enable the "Java Debug Wire Protocol" to attach a remote debugger to the JVM in this container. + Listens on port 9009 when enabled. Search the internet for numerous tutorials to use it. + * - ``DATAVERSE_HTTP_TIMEOUT`` + - ``900`` + - Seconds + - See :ref:`:ApplicationServerSettings` ``http.request-timeout-seconds``. + + *Note:* can also be set using any other `MicroProfile Config Sources`_ available via ``dataverse.http.timeout``. + + +.. [preboot] ``${CONFIG_DIR}/pre-boot-commands.asadmin`` +.. [postboot] ``${CONFIG_DIR}/post-boot-commands.asadmin`` +.. [dump-option] ``-XX:+HeapDumpOnOutOfMemoryError`` + + + +Locations ++++++++++ + +This environment variables represent certain locations and might be reused in your scripts etc. +These variables aren't meant to be reconfigurable and reflect state in the filesystem layout! + +.. list-table:: + :align: left + :width: 100 + :widths: 10 10 50 + :header-rows: 1 + + * - Env. variable + - Value + - Description + * - ``HOME_DIR`` + - ``/opt/payara`` + - Home base to Payara and the application + * - ``PAYARA_DIR`` + - ``${HOME_DIR}/appserver`` + - Installation directory of Payara server + * - ``SCRIPT_DIR`` + - ``${HOME_DIR}/scripts`` + - Any scripts like the container entrypoint, init scripts, etc + * - ``CONFIG_DIR`` + - ``${HOME_DIR}/config`` + - Payara Server configurations like pre/postboot command files go here + (Might be reused for Dataverse one day) + * - ``DEPLOY_DIR`` + - ``${HOME_DIR}/deployments`` + - Any EAR or WAR file, exploded WAR directory etc are autodeployed on start + * - ``DOCROOT_DIR`` + - ``/docroot`` + - Mount a volume here to store i18n language bundle files, sitemaps, images for Dataverse collections, logos, + custom themes and stylesheets, etc here. You might need to replicate this data or place on shared file storage. + * - ``SECRETS_DIR`` + - ``/secrets`` + - Mount secrets or other here, being picked up automatically by + `Directory Config Source `_. + See also various :doc:`../installation/config` options involving secrets. + * - ``DUMPS_DIR`` + - ``/dumps`` + - Default location where heap dumps will be stored (see above). + You should mount some storage here (disk or ephemeral). + * - ``DOMAIN_DIR`` + - ``${PAYARA_DIR}/glassfish`` ``/domains/${DOMAIN_NAME}`` + - Path to root of the Payara domain applications will be deployed into. Usually ``${DOMAIN_NAME}`` will be ``domain1``. + + + +Exposed Ports ++++++++++++++ + +The default ports that are exposed by this image are: + +- 8080 - HTTP listener +- 8181 - HTTPS listener +- 4848 - Admin Service HTTPS listener +- 8686 - JMX listener +- 9009 - "Java Debug Wire Protocol" port (when ``ENABLE_JDWP=1``) + + + +Hints ++++++ + +By default, ``domain1`` is enabled to use the ``G1GC`` garbage collector. + +For running a Java application within a Linux based container, the support for CGroups is essential. It has been +included and activated by default since Java 8u192, Java 11 LTS and later. If you are interested in more details, +you can read about those in a few places like https://developers.redhat.com/articles/2022/04/19/java-17-whats-new-openjdks-container-awareness, +https://www.eclipse.org/openj9/docs/xxusecontainersupport, etc. The other memory defaults are inspired +from `run-java-sh recommendations`_. + + +.. _Pre/postboot script docs: https://docs.payara.fish/community/docs/Technical%20Documentation/Payara%20Micro%20Documentation/Payara%20Micro%20Configuration%20and%20Management/Micro%20Management/Asadmin%20Commands/Pre%20and%20Post%20Boot%20Commands.html +.. _MicroProfile Config Sources: https://docs.payara.fish/community/docs/Technical%20Documentation/MicroProfile/Config/Overview.html +.. _run-java-sh recommendations: https://github.com/fabric8io-images/run-java-sh/blob/master/TUNING.md#recommandations \ No newline at end of file From 67db02ff0249720c47e3025820c30fb6d737ec83 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 24 Aug 2022 15:08:30 +0200 Subject: [PATCH 15/60] docs(ct-base): remove reference to not (yet) existing docs page --- doc/sphinx-guides/source/container/index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/sphinx-guides/source/container/index.rst b/doc/sphinx-guides/source/container/index.rst index 1bf86f16f43..801ded7d0a5 100644 --- a/doc/sphinx-guides/source/container/index.rst +++ b/doc/sphinx-guides/source/container/index.rst @@ -6,7 +6,6 @@ Container Guide .. toctree:: base-image - app-image Running Dataverse software in containers is quite different than in a :doc:`classic installation <../installation/prep>`. From d5f80754e0ebf1ed56d34c1d7dbbe3d5fdc49b4a Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 24 Aug 2022 17:38:29 +0200 Subject: [PATCH 16/60] docs(ct-base): add Docker Hub Eclipse Temurin tag search example --- doc/sphinx-guides/source/container/base-image.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 4f441f79ad7..4333bf38d5c 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -43,6 +43,7 @@ Some additional notes, using Maven parameters to change the build and use ...: - ... a different Payara version: add ``-Dpayara.version=V.YYYY.R``. - | ... a different Temurin JRE version ``A``: add ``-Dtarget.java.version=A`` (i.e. ``11``, ``17``, ...). | *Note:* must resolve to an available Docker tag ``A-jre`` of Eclipse Temurin! + (See also `Docker Hub search example `_) - ... a different Java Distribution: add ``-Ddocker.buildArg.BASE_IMAGE="name:tag"`` with precise reference to an image available from local or remote (e. g. Docker Hub). From 5e61241a27229fdbe7ce6fb7e84c520b609fdb33 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 26 Aug 2022 18:26:30 +0200 Subject: [PATCH 17/60] style(ct-base): incorporate requested changes by @pdurbin - Change order of guides - Remove unnecessary quotes from IQSS - Add TOC to base image docs - Add flag again about community support only to base image docs --- doc/sphinx-guides/source/container/base-image.rst | 14 ++++++++++++-- doc/sphinx-guides/source/container/index.rst | 5 +++-- doc/sphinx-guides/source/index.rst | 2 +- 3 files changed, 16 insertions(+), 5 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 4333bf38d5c..ac64323eeea 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -1,11 +1,21 @@ Application Base Image ====================== +.. contents:: |toctitle| + :local: + Within the main repository, you may find the base image's files at ``/modules/container-base``. This Maven module uses the `Maven Docker Plugin `_ to build and ship the image. -Contents -++++++++ +**NOTE: This image is created, maintained and supported by the Dataverse community on a best-effort basis.** +IQSS will not offer you support how to deploy or run it, please reach out to the community for help on using it. +You might be interested in taking a look at :doc:`../developers/containers`, linking you to some (community-based) +efforts. + + + +Image Contents +++++++++++++++ The base image provides: diff --git a/doc/sphinx-guides/source/container/index.rst b/doc/sphinx-guides/source/container/index.rst index 801ded7d0a5..f6c99bfc19e 100644 --- a/doc/sphinx-guides/source/container/index.rst +++ b/doc/sphinx-guides/source/container/index.rst @@ -13,8 +13,9 @@ Both approaches have pros and cons. These days (2022) containers are very often but there is an ever rising move for running applications in the cloud using container technology. **NOTE:** -**As the "Institute for Quantitative Social Sciences" at Harvard is running their installations in the classic -deployment way, the container support is mostly created and maintained by the Dataverse community.** +**As the Institute for Quantitative Social Sciences (IQSS) at Harvard is running their installations in the classic +deployment way, the container support is mostly created and maintained by the Dataverse community on a best-effort +basis.** This guide is *not* about installation on technology like Docker Swarm, Kubernetes, Rancher or other solutions to run containers in production. There is the `Dataverse on K8s project `_ for this diff --git a/doc/sphinx-guides/source/index.rst b/doc/sphinx-guides/source/index.rst index f15a973544d..cbfafb419ab 100755 --- a/doc/sphinx-guides/source/index.rst +++ b/doc/sphinx-guides/source/index.rst @@ -18,8 +18,8 @@ These documentation guides are for the |version| version of Dataverse. To find g api/index installation/index developers/index - style/index container/index + style/index How the Guides Are Organized ---------------------------- From a3a70998b9fcacc1a96e8357d459cba489425785 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 26 Aug 2022 18:29:30 +0200 Subject: [PATCH 18/60] feat(ct-base): make image names configurable and rename Add new Maven properties to choose a different Java base image and change the name of the target base image when people customize it. Also changes the build arg for the Java base image name. With this, the image name changes to follow the same convention as the Java base image. --- doc/sphinx-guides/source/container/base-image.rst | 4 +++- modules/container-base/pom.xml | 7 ++++--- modules/container-base/src/main/docker/Dockerfile | 4 ++-- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index ac64323eeea..834381e6779 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -50,11 +50,13 @@ Or move to the module and execute: Some additional notes, using Maven parameters to change the build and use ...: +- | ... a different image name and tag: add ``-Dbase.image=name:tag``. + | *Note:* default is ``gdcc/base:${target.java.version}-jre`` - ... a different Payara version: add ``-Dpayara.version=V.YYYY.R``. - | ... a different Temurin JRE version ``A``: add ``-Dtarget.java.version=A`` (i.e. ``11``, ``17``, ...). | *Note:* must resolve to an available Docker tag ``A-jre`` of Eclipse Temurin! (See also `Docker Hub search example `_) -- ... a different Java Distribution: add ``-Ddocker.buildArg.BASE_IMAGE="name:tag"`` with precise reference to an +- ... a different Java Distribution: add ``-Djava.image="name:tag"`` with precise reference to an image available from local or remote (e. g. Docker Hub). diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index 015ebba598d..f8e97bb4349 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -39,6 +39,8 @@ ct docker-build + gdcc/base:${target.java.version}-jre + eclipse-temurin:${target.java.version}-jre @@ -85,8 +87,7 @@ base - %g/base:jdk${target.java.version} - ${ct.registry} + ${base.image} @@ -96,7 +97,7 @@ Dockerfile - eclipse-temurin:${target.java.version}-jre + ${java.image} @ diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index ba459607826..6fdc790a21a 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -20,8 +20,8 @@ # # Make the Java base image and version configurable (useful for trying newer Java versions and flavors) -ARG BASE_IMAGE="eclipse-temurin:11-jre" -FROM $BASE_IMAGE +ARG JAVA_IMAGE="eclipse-temurin:11-jre" +FROM $JAVA_IMAGE # Default payara ports to expose # 4848: admin console From 06d31fde25c3bfa812339c0afad94b7a83e92e59 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 26 Aug 2022 18:34:40 +0200 Subject: [PATCH 19/60] fix(ct-base): make container build use install not package goal By switching to `mvn install` instead of `mvn package`, we allow the main image carrying the application to declare a dependency on the container-base module (to make sure it get's built alongside, as we might want to change the Payara version!) This commits also adds the Maven install plugin to the parent POM for versioning plus to the container-base POM for having the target available. (This is a necessary workaround for a Maven Docker Plugin shortcoming.) --- .../source/container/base-image.rst | 4 ++-- modules/container-base/pom.xml | 19 +++++++++++++++++++ modules/dataverse-parent/pom.xml | 6 ++++++ 3 files changed, 27 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 834381e6779..585fe1184e7 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -42,11 +42,11 @@ Assuming you have `Docker `_, `Docker D Simply execute the Maven modules packaging target with activated "container profile. Either from the projects Git root: -``mvn -Pct -f modules/container-base package`` +``mvn -Pct -f modules/container-base install`` Or move to the module and execute: -``cd modules/container-base && mvn -Pct package`` +``cd modules/container-base && mvn -Pct install`` Some additional notes, using Maven parameters to change the build and use ...: diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index f8e97bb4349..0e8f24a781b 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -108,6 +108,25 @@ + + + + maven-install-plugin + + + default-install + install + + install + + + + diff --git a/modules/dataverse-parent/pom.xml b/modules/dataverse-parent/pom.xml index eaa09b61bd7..411ce85b2fa 100644 --- a/modules/dataverse-parent/pom.xml +++ b/modules/dataverse-parent/pom.xml @@ -178,6 +178,7 @@ 3.2.2 3.3.2 3.2.0 + 3.0.0-M1 3.0.0-M5 3.0.0-M5 3.3.0 @@ -226,6 +227,11 @@ maven-dependency-plugin ${maven-dependency-plugin.version} + + org.apache.maven.plugins + maven-install-plugin + ${maven-install-plugin.version} + org.apache.maven.plugins maven-surefire-plugin From 98ad9361843519b3f904ecc3df5d7b877802c30a Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 26 Aug 2022 18:37:28 +0200 Subject: [PATCH 20/60] fix(ct-base): flatten container-base POM By using the flattening POM plugin, the installed POM will not carry references to the dataverse-parent module. This reference is a) unnecessary and b) troublesome because of the ${revision} hack. (And we do not provide it as a dependency from Central/...) --- modules/container-base/.gitignore | 1 + modules/container-base/pom.xml | 36 +++++++++++++++++++++++++++++++ 2 files changed, 37 insertions(+) create mode 100644 modules/container-base/.gitignore diff --git a/modules/container-base/.gitignore b/modules/container-base/.gitignore new file mode 100644 index 00000000000..d75620abf70 --- /dev/null +++ b/modules/container-base/.gitignore @@ -0,0 +1 @@ +.flattened-pom.xml diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index 0e8f24a781b..cee3989661a 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -108,6 +108,42 @@ + + + + org.codehaus.mojo + flatten-maven-plugin + 1.2.7 + + true + oss + + remove + remove + + + + + + flatten + process-resources + + flatten + + + + + flatten.clean + clean + + clean + + + + 0.40.2 - ghcr.io From 64f84ea461d0fc8d1e4147b1bdcb8b86c2bafcd0 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 31 Aug 2022 01:56:51 +0200 Subject: [PATCH 35/60] style(ct-base): make up base image name from tag and add default With defaulting to develop, we rest on using any build of the image during experimentation etc to go with a (local) develop tag. Removing the Java version from the tag makes it easier to use and reflects the nature of it. It aligns image builds with the release schema of the actual application while still allowing for experiments and having different sources of truth for released and develop code. --- modules/container-base/pom.xml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index 12eb3b137ff..67e2c2f9911 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -39,7 +39,8 @@ ct docker-build - gdcc/base:${target.java.version}-jre + gdcc/base:${base.image.tag} + develop eclipse-temurin:${target.java.version}-jre 1000 1000 From 5a986af6cc7651fd43ec5a4207349dab17b6651e Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 31 Aug 2022 01:57:16 +0200 Subject: [PATCH 36/60] chore(deps): make container profile use Payara 5.2022.3 --- modules/dataverse-parent/pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/dataverse-parent/pom.xml b/modules/dataverse-parent/pom.xml index 7a3b71fb68c..86b46817635 100644 --- a/modules/dataverse-parent/pom.xml +++ b/modules/dataverse-parent/pom.xml @@ -340,7 +340,7 @@ See also: https://github.com/IQSS/dataverse/issues/8048 See also: https://github.com/payara/Payara/issues/5368 --> - 5.2022.2 + 5.2022.3 From 65f9d6356b8caca3ddd54e323c838e6b9749f3cc Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 31 Aug 2022 02:02:32 +0200 Subject: [PATCH 37/60] feat(ct-base): enable base image pushes for master and develop branch - Make pushes to develop or master branch release a container image to Docker Hub by default (can be changed / extended). - Defaulting to the develop tag by default makes it more reusable for depending workflows based on pull requests. - Moving all multi-arch building to only happen on pushes, as it will be done during push/deploy phase only and those need credentials only avail in git push context running at repo owner of CI action. - Removing the Java version matrix parameter, too - we are gonna stick with what is default for releasing the images as they are meant to be a somewhat reliable base. It's still open for experiments. --- .github/workflows/container_base_push.yml | 22 +++++++++++++++++----- 1 file changed, 17 insertions(+), 5 deletions(-) diff --git a/.github/workflows/container_base_push.yml b/.github/workflows/container_base_push.yml index fc23b30d8ad..82c7a376ae0 100644 --- a/.github/workflows/container_base_push.yml +++ b/.github/workflows/container_base_push.yml @@ -5,16 +5,21 @@ on: push: branches: - 'develop' + - 'master' paths: - 'modules/container-base/**' - 'modules/dataverse-parent/pom.xml' pull_request: branches: - 'develop' + - 'master' paths: - 'modules/container-base/**' - 'modules/dataverse-parent/pom.xml' +env: + IMAGE_TAG: develop + REGISTRY: docker.io jobs: build: @@ -45,14 +50,21 @@ jobs: key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} restore-keys: ${{ runner.os }}-m2 - - name: Set up QEMU for multi-arch builds - uses: docker/setup-qemu-action@v2 - - name: Build base container image - run: mvn -f modules/container-base -Pct package -Dtarget.java.version=${{ matrix.jdk }} + - name: Build base container image with local architecture + run: mvn -f modules/container-base -Pct package - if: ${{ github.event_name == 'push' }} # run only if this is a push - PRs have no access to secrets name: Log in to the Container registry uses: docker/login-action@v1 with: username: ${{ secrets.DOCKERHUB_USERNAME }} - password: ${{ secrets.DOCKERHUB_TOKEN }} \ No newline at end of file + password: ${{ secrets.DOCKERHUB_TOKEN }} + - if: ${{ github.event_name == 'push' }} # run only if this is a push - multi-arch makes no sense with PR + name: Set up QEMU for multi-arch builds + uses: docker/setup-qemu-action@v2 + - name: Re-set image tag based on branch + if: ${{ github.ref == 'master' }} + run: echo "IMAGE_TAG=release" + - if: ${{ github.event_name == 'push' }} # run only if this is a push - tag push will only succeed in upstream + name: Deploy multi-arch base container image to Docker Hub + run: mvn -f modules/container-base -Pct deploy -Dbase.image.tag=${{ env.IMAGE_TAG }} -Ddocker.registry=${{ env.REGISTRY }} From 8f39ef2c6e564af53756895a0115e0d58f24d602 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 14 Sep 2022 16:42:29 +0200 Subject: [PATCH 38/60] style(ct-base): upgrade Dockerfile with heredocs #8932 Instead of using "&& \" style continuation of a RUN layer, newer Docker versions (since 2021) allow usage of heredocs. Also move some ARG to more suitable places --- .../container-base/src/main/docker/Dockerfile | 158 ++++++++++-------- 1 file changed, 85 insertions(+), 73 deletions(-) diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index caec4ee6619..68b9da13c67 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -67,43 +67,47 @@ ENV PATH="${PATH}:${PAYARA_DIR}/bin" \ ENABLE_JDWP=0 \ ENABLE_RELOAD=0 -ARG JATTACH_VERSION="v2.1" -ARG JATTACH_CHECKSUM="07885fdc782e02e7302c6d190f54c3930afa10a38140365adf54076ec1086a8e" -ARG PKGS="jq imagemagick curl unzip wget acl dirmngr gpg lsof procps netcat tini" -ARG ASADMIN="${PAYARA_DIR}/bin/asadmin --user=${ADMIN_USER} --passwordfile=${PASSWORD_FILE}" - ### PART 1: SYSTEM ### ARG UID=1000 ARG GID=1000 USER root WORKDIR / SHELL ["/bin/bash", "-euo", "pipefail", "-c"] -RUN true && \ +RUN <> /tmp/password-change-file.txt && \ - echo "AS_ADMIN_PASSWORD=${ADMIN_PASSWORD}" >> ${PASSWORD_FILE} && \ - asadmin --user=${ADMIN_USER} --passwordfile=/tmp/password-change-file.txt change-admin-password --domain_name=${DOMAIN_NAME} && \ + echo "AS_ADMIN_PASSWORD=" > /tmp/password-change-file.txt + echo "AS_ADMIN_NEWPASSWORD=${ADMIN_PASSWORD}" >> /tmp/password-change-file.txt + echo "AS_ADMIN_PASSWORD=${ADMIN_PASSWORD}" >> ${PASSWORD_FILE} + asadmin --user=${ADMIN_USER} --passwordfile=/tmp/password-change-file.txt change-admin-password --domain_name=${DOMAIN_NAME} # Start domain for configuration - ${ASADMIN} start-domain ${DOMAIN_NAME} && \ + ${ASADMIN} start-domain ${DOMAIN_NAME} # Allow access to admin with password only - ${ASADMIN} enable-secure-admin && \ + ${ASADMIN} enable-secure-admin + ### CONTAINER USAGE ENABLEMENT # List & delete memory settings from domain - for MEMORY_JVM_OPTION in $(${ASADMIN} list-jvm-options | grep "Xm[sx]\|Xss\|NewRatio"); \ - do \ - ${ASADMIN} delete-jvm-options $(echo $MEMORY_JVM_OPTION | sed -e 's/:/\\:/g'); \ - done && \ + for MEMORY_JVM_OPTION in $(${ASADMIN} list-jvm-options | grep "Xm[sx]\|Xss\|NewRatio"); + do + ${ASADMIN} delete-jvm-options $(echo $MEMORY_JVM_OPTION | sed -e 's/:/\\:/g'); + done # Tweak memory settings for containers - ${ASADMIN} create-jvm-options "-XX\:+UseContainerSupport" && \ - ${ASADMIN} create-jvm-options "-XX\:MaxRAMPercentage=\${ENV=MEM_MAX_RAM_PERCENTAGE}" && \ - ${ASADMIN} create-jvm-options "-Xss\${ENV=MEM_XSS}" && \ - ${ASADMIN} create-jvm-options "-XX\:MinHeapFreeRatio=\${ENV=MEM_MIN_HEAP_FREE_RATIO}" && \ - ${ASADMIN} create-jvm-options "-XX\:MaxHeapFreeRatio=\${ENV=MEM_MAX_HEAP_FREE_RATIO}" && \ - ${ASADMIN} create-jvm-options "-XX\:HeapDumpPath=\${ENV=DUMPS_DIR}" && \ + ${ASADMIN} create-jvm-options "-XX\:+UseContainerSupport" + ${ASADMIN} create-jvm-options "-XX\:MaxRAMPercentage=\${ENV=MEM_MAX_RAM_PERCENTAGE}" + ${ASADMIN} create-jvm-options "-Xss\${ENV=MEM_XSS}" + ${ASADMIN} create-jvm-options "-XX\:MinHeapFreeRatio=\${ENV=MEM_MIN_HEAP_FREE_RATIO}" + ${ASADMIN} create-jvm-options "-XX\:MaxHeapFreeRatio=\${ENV=MEM_MAX_HEAP_FREE_RATIO}" + ${ASADMIN} create-jvm-options "-XX\:HeapDumpPath=\${ENV=DUMPS_DIR}" # Set logging to console only for containers - ${ASADMIN} set-log-attributes com.sun.enterprise.server.logging.GFFileHandler.logtoFile=false && \ + ${ASADMIN} set-log-attributes com.sun.enterprise.server.logging.GFFileHandler.logtoFile=false \ + ### PRODUCTION READINESS - ${ASADMIN} create-jvm-options '-XX\:+UseG1GC' && \ - ${ASADMIN} create-jvm-options '-XX\:+UseStringDeduplication' && \ - ${ASADMIN} create-jvm-options '-XX\:+DisableExplicitGC' && \ - ${ASADMIN} create-jvm-options '-XX\:MaxGCPauseMillis=${ENV=MEM_MAX_GC_PAUSE_MILLIS}' && \ - ${ASADMIN} create-jvm-options '-XX\:MetaspaceSize=${ENV=MEM_METASPACE_SIZE}' && \ - ${ASADMIN} create-jvm-options '-XX\:MaxMetaspaceSize=${ENV=MEM_MAX_METASPACE_SIZE}' && \ - ${ASADMIN} create-jvm-options '-XX\:+IgnoreUnrecognizedVMOptions' && \ + ${ASADMIN} create-jvm-options '-XX\:+UseG1GC' + ${ASADMIN} create-jvm-options '-XX\:+UseStringDeduplication' + ${ASADMIN} create-jvm-options '-XX\:+DisableExplicitGC' + ${ASADMIN} create-jvm-options '-XX\:MaxGCPauseMillis=${ENV=MEM_MAX_GC_PAUSE_MILLIS}' + ${ASADMIN} create-jvm-options '-XX\:MetaspaceSize=${ENV=MEM_METASPACE_SIZE}' + ${ASADMIN} create-jvm-options '-XX\:MaxMetaspaceSize=${ENV=MEM_MAX_METASPACE_SIZE}' + ${ASADMIN} create-jvm-options '-XX\:+IgnoreUnrecognizedVMOptions' # Disable autodeploy and hot reload - ${ASADMIN} set configs.config.server-config.admin-service.das-config.dynamic-reload-enabled="false" && \ - ${ASADMIN} set configs.config.server-config.admin-service.das-config.autodeploy-enabled="false" && \ + ${ASADMIN} set configs.config.server-config.admin-service.das-config.dynamic-reload-enabled="false" + ${ASADMIN} set configs.config.server-config.admin-service.das-config.autodeploy-enabled="false" # Enlarge thread pools - ${ASADMIN} set server-config.thread-pools.thread-pool.http-thread-pool.max-thread-pool-size="50" && \ - ${ASADMIN} set server-config.thread-pools.thread-pool.http-thread-pool.max-queue-size="" && \ - ${ASADMIN} set default-config.thread-pools.thread-pool.thread-pool-1.max-thread-pool-size="250" && \ + ${ASADMIN} set server-config.thread-pools.thread-pool.http-thread-pool.max-thread-pool-size="50" + ${ASADMIN} set server-config.thread-pools.thread-pool.http-thread-pool.max-queue-size="" + ${ASADMIN} set default-config.thread-pools.thread-pool.thread-pool-1.max-thread-pool-size="250" # Enable file caching - ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-1.http.file-cache.enabled="true" && \ - ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-2.http.file-cache.enabled="true" && \ - ${ASADMIN} set default-config.network-config.protocols.protocol.http-listener-1.http.file-cache.enabled="true" && \ - ${ASADMIN} set default-config.network-config.protocols.protocol.http-listener-2.http.file-cache.enabled="true" && \ + ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-1.http.file-cache.enabled="true" + ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-2.http.file-cache.enabled="true" + ${ASADMIN} set default-config.network-config.protocols.protocol.http-listener-1.http.file-cache.enabled="true" + ${ASADMIN} set default-config.network-config.protocols.protocol.http-listener-2.http.file-cache.enabled="true" # Disable the HTTPS listener (we are always fronting our appservers with a reverse proxy handling SSL) - ${ASADMIN} set configs.config.server-config.network-config.network-listeners.network-listener.http-listener-2.enabled="false" && \ - # Enlarge and tune EJB pools (cannot do this for server-config as set does not create new entries) \ - ${ASADMIN} set default-config.ejb-container.pool-resize-quantity="2" && \ - ${ASADMIN} set default-config.ejb-container.max-pool-size="128" && \ - ${ASADMIN} set default-config.ejb-container.steady-pool-size="10" && \ + ${ASADMIN} set configs.config.server-config.network-config.network-listeners.network-listener.http-listener-2.enabled="false" + # Enlarge and tune EJB pools (cannot do this for server-config as set does not create new entries) + ${ASADMIN} set default-config.ejb-container.pool-resize-quantity="2" + ${ASADMIN} set default-config.ejb-container.max-pool-size="128" + ${ASADMIN} set default-config.ejb-container.steady-pool-size="10" # Misc settings - ${ASADMIN} create-system-properties fish.payara.classloading.delegate="false" && \ - ${ASADMIN} create-system-properties jersey.config.client.readTimeout="300000" && \ - ${ASADMIN} create-system-properties jersey.config.client.connectTimeout="300000" && \ + ${ASADMIN} create-system-properties fish.payara.classloading.delegate="false" + ${ASADMIN} create-system-properties jersey.config.client.readTimeout="300000" + ${ASADMIN} create-system-properties jersey.config.client.connectTimeout="300000" \ + ### DATAVERSE APPLICATION SPECIFICS # Configure the MicroProfile directory config source to point to /secrets - ${ASADMIN} set-config-dir --directory="${SECRETS_DIR}" && \ + ${ASADMIN} set-config-dir --directory="${SECRETS_DIR}" # Make request timeouts configurable via MPCONFIG (default to 900 secs = 15 min) - ${ASADMIN} set 'server-config.network-config.protocols.protocol.http-listener-1.http.request-timeout-seconds=${MPCONFIG=dataverse.http.timeout:900}' && \ + ${ASADMIN} set 'server-config.network-config.protocols.protocol.http-listener-1.http.request-timeout-seconds=${MPCONFIG=dataverse.http.timeout:900}' # TODO: what of the below 3 items can be deleted for container usage? - ${ASADMIN} create-network-listener --protocol=http-listener-1 --listenerport=8009 --jkenabled=true jk-connector && \ - ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-1.http.comet-support-enabled=true && \ - ${ASADMIN} create-system-properties javax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl && \ + ${ASADMIN} create-network-listener --protocol=http-listener-1 --listenerport=8009 --jkenabled=true jk-connector + ${ASADMIN} set server-config.network-config.protocols.protocol.http-listener-1.http.comet-support-enabled=true + ${ASADMIN} create-system-properties javax.xml.parsers.SAXParserFactory=com.sun.org.apache.xerces.internal.jaxp.SAXParserFactoryImpl # Always disable phoning home... - ${ASADMIN} disable-phone-home && \ + ${ASADMIN} disable-phone-home \ + ### CLEANUP # Stop domain - ${ASADMIN} stop-domain "${DOMAIN_NAME}" && \ - # Disable JSP servlet dynamic reloads \ - sed -i 's#org.apache.jasper.servlet.JspServlet#org.apache.jasper.servlet.JspServlet\n \n development\n false\n \n \n genStrAsCharArray\n true\n #' "${DOMAIN_DIR}/config/default-web.xml" && \ + ${ASADMIN} stop-domain "${DOMAIN_NAME}" + # Disable JSP servlet dynamic reloads + sed -i 's#org.apache.jasper.servlet.JspServlet#org.apache.jasper.servlet.JspServlet\n \n development\n false\n \n \n genStrAsCharArray\n true\n #' "${DOMAIN_DIR}/config/default-web.xml" # Cleanup old CA certificates to avoid unnecessary log clutter during startup - ${SCRIPT_DIR}/removeExpiredCaCerts.sh && \ + ${SCRIPT_DIR}/removeExpiredCaCerts.sh # Delete generated files rm -rf \ "/tmp/password-change-file.txt" \ "${PAYARA_DIR}/glassfish/domains/${DOMAIN_NAME}/osgi-cache" \ "${PAYARA_DIR}/glassfish/domains/${DOMAIN_NAME}/logs" +EOF # Make docroot of Payara reside in higher level directory for easier targeting # Due to gdcc/dataverse-kubernetes#177: create the generated pathes so they are # writeable by us. TBR with gdcc/dataverse-kubernetes#178. -RUN rm -rf "${DOMAIN_DIR}"/docroot && \ - ln -s "${DOCROOT_DIR}" "${DOMAIN_DIR}"/docroot && \ +RUN < Date: Wed, 14 Sep 2022 21:18:28 +0200 Subject: [PATCH 39/60] feat,fix(ct-base): add extension point for background script #8932 By moving from tini to dumb-init, we can offer a new extension point: if an application image extending this base image provides an executable script at ${SCRIPT_DIR}/startInBackground.sh, it will be executed after the init scripts and in parallel to the application server. By adding ${SCRIPT_DIR} to $PATH, we can now also skip variable expansion, fixing a bug: formerly, the "exec" in entrypoint.sh and startInForeground.sh where not replacing the shell properly. The switch to dumb-init makes sure signals will be transferred also to any background processes! --- .../container-base/src/main/docker/Dockerfile | 10 +++++----- .../src/main/docker/scripts/entrypoint.sh | 17 ++++++++++++++++- 2 files changed, 21 insertions(+), 6 deletions(-) diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index 68b9da13c67..c56abb975e2 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -46,7 +46,7 @@ ENV PAYARA_DIR="${HOME_DIR}/appserver" \ ADMIN_PASSWORD="admin" \ DOMAIN_NAME="domain1" \ PAYARA_ARGS="" -ENV PATH="${PATH}:${PAYARA_DIR}/bin" \ +ENV PATH="${PATH}:${PAYARA_DIR}/bin:${SCRIPT_DIR}" \ DOMAIN_DIR="${PAYARA_DIR}/glassfish/domains/${DOMAIN_NAME}" \ DEPLOY_PROPS="" \ PREBOOT_COMMANDS="${CONFIG_DIR}/pre-boot-commands.asadmin" \ @@ -88,7 +88,7 @@ EOF ARG JATTACH_VERSION="v2.1" ARG JATTACH_CHECKSUM="07885fdc782e02e7302c6d190f54c3930afa10a38140365adf54076ec1086a8e" -ARG PKGS="jq imagemagick curl unzip wget acl dirmngr gpg lsof procps netcat tini" +ARG PKGS="jq imagemagick curl unzip wget acl dirmngr gpg lsof procps netcat dumb-init" # Installing the packages in an extra container layer for better caching RUN < Date: Wed, 14 Sep 2022 21:32:51 +0200 Subject: [PATCH 40/60] docs(ct-base): document startInBackground.sh #8932 --- .../source/container/base-image.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 524ef8a7fbe..3f7b3b46c85 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -23,7 +23,8 @@ The base image provides: - `Payara Community Application Server `_ - CLI tools necessary to run Dataverse (i. e. ``curl`` or ``jq`` - see also :doc:`../installation/prerequisites` in Installation Guide) - Linux tools for analysis, monitoring and so on -- `Jattach `_ +- `Jattach `__ (attach to running JVM) +- `dumb-init `__ (see :ref:`below ` for details) This image is created as a "multi-arch image", supporting the most common architectures Dataverse usually runs on: AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2). @@ -246,6 +247,22 @@ its sources plus uncached scheduled nightly builds to make sure security updates Note: for the Github Action to be able to push to Docker Hub, two repository secrets (DOCKERHUB_USERNAME, DOCKERHUB_TOKEN) have been added by IQSS admins to their repository. +.. _base-entrypoint: + +Entry & Extension Points +++++++++++++++++++++++++ + +The entrypoint shell script provided by this base image will by default ensure to: + +- Run any scripts named ``${SCRIPT_DIR}/init_*`` or in ``${SCRIPT_DIR}/init.d/*`` directory for initialization + **before** the application server starts. +- Run an executable script ``${SCRIPT_DIR}/startInBackground.sh`` in the background - if present. +- Run the application server startup scripting in foreground (``${SCRIPT_DIR}/startInForeground.sh``). + +If you need to create some scripting that runs in parallel under supervision of `dumb-init `_, +e.g. to wait for the application to deploy before executing something, this is your point of extension: simply provide +the ``${SCRIPT_DIR}/startInBackground.sh`` executable script with your application image. + Other Hints From f8bf73479708a0d1cfb6882db9a118e12d70d34d Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 14 Sep 2022 21:50:06 +0200 Subject: [PATCH 41/60] ci(shellcheck,shellspec): split ShellCheck and ShellSpec To avoid unnecessary Shellspec runs for scripts that have no such tests, branch out the Shellcheck part of it into different workflow. Also make "bash" explicit as the container base image using an "unknown shebang" via dumb-init, but it's simply bash. --- .github/workflows/shellcheck.yml | 24 ++++++++++++++++++++++++ .github/workflows/shellspec.yml | 14 -------------- 2 files changed, 24 insertions(+), 14 deletions(-) create mode 100644 .github/workflows/shellcheck.yml diff --git a/.github/workflows/shellcheck.yml b/.github/workflows/shellcheck.yml new file mode 100644 index 00000000000..2d910f54127 --- /dev/null +++ b/.github/workflows/shellcheck.yml @@ -0,0 +1,24 @@ +name: "Shellcheck" +on: + push: + paths: + - conf/solr/** + - modules/container-base/** + pull_request: + paths: + - conf/solr/** + - modules/container-base/** +jobs: + shellcheck: + name: Shellcheck + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + - name: shellcheck + uses: reviewdog/action-shellcheck@v1 + with: + github_token: ${{ secrets.github_token }} + reporter: github-pr-review # Change reporter. + fail_on_error: true + # Container base image uses dumb-init shebang, so nail to using bash + shellcheck_flags: "--shell=bash --external-sources" \ No newline at end of file diff --git a/.github/workflows/shellspec.yml b/.github/workflows/shellspec.yml index 2b127a7be5c..5c251cfc897 100644 --- a/.github/workflows/shellspec.yml +++ b/.github/workflows/shellspec.yml @@ -4,29 +4,15 @@ on: paths: - tests/shell/** - conf/solr/** - - modules/container-base/** # add more when more specs are written relying on data pull_request: paths: - tests/shell/** - conf/solr/** - - modules/container-base/** # add more when more specs are written relying on data env: SHELLSPEC_VERSION: 0.28.1 jobs: - shellcheck: - name: Shellcheck - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: shellcheck - uses: reviewdog/action-shellcheck@v1 - with: - github_token: ${{ secrets.github_token }} - reporter: github-pr-review # Change reporter. - fail_on_error: true - exclude: "./tests/shell/*" shellspec-ubuntu: name: "Ubuntu" runs-on: ubuntu-latest From 626b4951cfbf163895ce75e605b4daec455e0aae Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 20 Sep 2022 00:22:38 +0200 Subject: [PATCH 42/60] docs(ct-base): clarify support image tags #8932 Adding notes about the image tags produced by the community for reuse in the community. Document final tagging strategy, using the branch name (develop/main) instead of the Java version or sth. Reshape the automated builds and publishing part to be included in the supported tags and build instructions section to reduce text complexity and group matching parts together. --- .../source/container/base-image.rst | 40 +++++++++++++------ 1 file changed, 27 insertions(+), 13 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 3f7b3b46c85..ea54ecbebd2 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -12,6 +12,17 @@ IQSS will not offer you support how to deploy or run it, please reach out to the You might be interested in taking a look at :doc:`../developers/containers`, linking you to some (community-based) efforts. +Supported Image Tags +++++++++++++++++++++ + +This image is sourced within the main upstream code repository of the Dataverse software. Development and maintenance +happens there (again, by the community). Community supported image tags are based on the two most important branches: + +- ``develop`` representing the unstable state of affairs in Dataverse's development branch + (`Dockerfile `__) +- ``release`` representing the latest stable release in Dataverse's main branch + (`Dockerfile `__) + Image Contents @@ -51,8 +62,12 @@ Or move to the module and execute: Some additional notes, using Maven parameters to change the build and use ...: +- | ... a different tag only: add ``-Dbase.image.tag=tag``. + | *Note:* default is ``develop`` - | ... a different image name and tag: add ``-Dbase.image=name:tag``. - | *Note:* default is ``gdcc/base:${target.java.version}-jre`` + | *Note:* default is ``gdcc/base:${base.image.tag}`` +- ... a different image registry than *Docker Hub*: add ``-Ddocker.registry=registry.example.org`` (see also + `DMP docs on registries `__) - ... a different Payara version: add ``-Dpayara.version=V.YYYY.R``. - | ... a different Temurin JRE version ``A``: add ``-Dtarget.java.version=A`` (i.e. ``11``, ``17``, ...). | *Note:* must resolve to an available Docker tag ``A-jre`` of Eclipse Temurin! @@ -61,6 +76,17 @@ Some additional notes, using Maven parameters to change the build and use ...: image available from local or remote (e. g. Docker Hub). - ... a different UID/GID for the ``payara`` user/group: add ``-Dbase.image.uid=1234`` (or ``.gid``) +Automated Builds & Publishing +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +To make reusing most simple, the image is built with a Github Action within the IQSS repository and then pushed +to `Docker Hub gdcc/base repository `_. It is built and pushed on every edit to +its sources plus uncached scheduled nightly builds to make sure security updates are finding their way in. + +*Note:* For the Github Action to be able to push to Docker Hub, two repository secrets +(DOCKERHUB_USERNAME, DOCKERHUB_TOKEN) have been added by IQSS admins to their repository. + + Tunables ++++++++ @@ -234,18 +260,6 @@ The HTTPS listener (on port 8181) becomes deactivated during the build, as we wi application server and handle SSL/TLS termination at this point. Save the memory and some CPU cycles! -Publishing and Updates -++++++++++++++++++++++ - -This image is sourced within the main upstream code repository of the Dataverse software. Development and maintenance -happens there (again, by the community). - -To make reusing most simple, the image is built with a Github Action within the IQSS repository and then pushed -to `Docker Hub gdcc/base repository `_. It is built and pushed on every edit to -its sources plus uncached scheduled nightly builds to make sure security updates are finding their way in. - -Note: for the Github Action to be able to push to Docker Hub, two repository secrets -(DOCKERHUB_USERNAME, DOCKERHUB_TOKEN) have been added by IQSS admins to their repository. .. _base-entrypoint: From 77592113f310d314d7de11b372a60cf3b4e08600 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 20 Sep 2022 00:27:06 +0200 Subject: [PATCH 43/60] style,docs(ct-base): small word adjusts for some build options --- doc/sphinx-guides/source/container/base-image.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index ea54ecbebd2..3e83af23bfb 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -70,10 +70,10 @@ Some additional notes, using Maven parameters to change the build and use ...: `DMP docs on registries `__) - ... a different Payara version: add ``-Dpayara.version=V.YYYY.R``. - | ... a different Temurin JRE version ``A``: add ``-Dtarget.java.version=A`` (i.e. ``11``, ``17``, ...). - | *Note:* must resolve to an available Docker tag ``A-jre`` of Eclipse Temurin! + | *Note:* must resolve to an available image tag ``A-jre`` of Eclipse Temurin! (See also `Docker Hub search example `_) - ... a different Java Distribution: add ``-Djava.image="name:tag"`` with precise reference to an - image available from local or remote (e. g. Docker Hub). + image available local or remote. - ... a different UID/GID for the ``payara`` user/group: add ``-Dbase.image.uid=1234`` (or ``.gid``) Automated Builds & Publishing From 2141bcafae5fea8ac2414a0aecede81b988a7306 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 20 Sep 2022 00:48:16 +0200 Subject: [PATCH 44/60] docs(ct-base): add notes about multiarch builds #8932 Addin description on requirements to build cross platform added as subsection of the build instructions seemed valuable. --- .../source/container/base-image.rst | 23 +++++++++++++++---- 1 file changed, 19 insertions(+), 4 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 3e83af23bfb..41d88c97e2d 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -37,8 +37,7 @@ The base image provides: - `Jattach `__ (attach to running JVM) - `dumb-init `__ (see :ref:`below ` for details) -This image is created as a "multi-arch image", supporting the most common architectures Dataverse usually runs on: -AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2). +This image is created as a "multi-arch image", see :ref:`below `. It inherits being built on an Ubuntu environment from the upstream `base image of Eclipse Temurin `_. @@ -86,6 +85,24 @@ its sources plus uncached scheduled nightly builds to make sure security updates *Note:* For the Github Action to be able to push to Docker Hub, two repository secrets (DOCKERHUB_USERNAME, DOCKERHUB_TOKEN) have been added by IQSS admins to their repository. +.. _base-multiarch: + +Processor Architecture and Multiarch +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +This image is created as a "multi-arch image", supporting the most common architectures Dataverse usually runs on: +AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2), by using Maven Docker Plugin's *BuildX* mode. + +Building the image via ``mvn -Pct package`` or ``mvn -Pct install`` as above will only build for the architecture of +the Docker maschine's CPU. + +Only ``mvn -Pct deploy`` will trigger building on all enabled architectures. +Yet, to enable building with non-native code on your build machine, you will need to setup a cross-platform builder. + +On Linux, you should install `qemu-user-static `__ (preferably via +your package management) on the host and run ``docker run --rm --privileged multiarch/qemu-user-static --reset -p yes`` +to enable that builder. The Docker plugin will setup everything else for you. + Tunables @@ -290,8 +307,6 @@ you can read about those in a few places like https://developers.redhat.com/arti https://www.eclipse.org/openj9/docs/xxusecontainersupport, etc. The other memory defaults are inspired from `run-java-sh recommendations`_. -*Note: the build process used the newer ``buildx`` feature of Docker to provide multiarch images.* - .. _Pre/postboot script docs: https://docs.payara.fish/community/docs/Technical%20Documentation/Payara%20Micro%20Documentation/Payara%20Micro%20Configuration%20and%20Management/Micro%20Management/Asadmin%20Commands/Pre%20and%20Post%20Boot%20Commands.html From 276b3b5159471bd44cff99bfb1b9e6b279634b4a Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 20 Sep 2022 10:49:19 +0200 Subject: [PATCH 45/60] feat(ct-base): add wait-for script to image Many scripts shipped with an app image might rely on the availability of an external service, API or simply the database or search index. Adding a standard script here to make it easier to wait for their availability. --- doc/sphinx-guides/source/container/base-image.rst | 1 + modules/container-base/src/main/docker/Dockerfile | 11 +++++++++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 41d88c97e2d..197f4175538 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -35,6 +35,7 @@ The base image provides: - CLI tools necessary to run Dataverse (i. e. ``curl`` or ``jq`` - see also :doc:`../installation/prerequisites` in Installation Guide) - Linux tools for analysis, monitoring and so on - `Jattach `__ (attach to running JVM) +- `wait-for `__ (tool to "wait for" a service to be available) - `dumb-init `__ (see :ref:`below ` for details) This image is created as a "multi-arch image", see :ref:`below `. diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index c56abb975e2..cafeb2ffb59 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -88,6 +88,8 @@ EOF ARG JATTACH_VERSION="v2.1" ARG JATTACH_CHECKSUM="07885fdc782e02e7302c6d190f54c3930afa10a38140365adf54076ec1086a8e" +ARG WAIT_FOR_VERSION="v2.2.3" +ARG WAIT_FOR_CHECKSUM="70271181be69cd2c7265b2746f97fccfd7e8aa1059894138a775369c23589ff4" ARG PKGS="jq imagemagick curl unzip wget acl dirmngr gpg lsof procps netcat dumb-init" # Installing the packages in an extra container layer for better caching @@ -95,12 +97,17 @@ RUN < Date: Thu, 22 Sep 2022 14:17:58 +0200 Subject: [PATCH 46/60] chore(deps): remove Payara version from Maven ct profile With the merge of #8949 the custom version is no longer necessary. --- modules/dataverse-parent/pom.xml | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/modules/dataverse-parent/pom.xml b/modules/dataverse-parent/pom.xml index 9326ba71263..ce4dfb56257 100644 --- a/modules/dataverse-parent/pom.xml +++ b/modules/dataverse-parent/pom.xml @@ -334,13 +334,7 @@ ct - - 5.2022.3 + From ee1e0c8019d1cec82750f4e9454fd6ca264a520d Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 3 Nov 2022 17:59:06 +0100 Subject: [PATCH 47/60] build(ct-base): switch to Payara 5.2022.4 The upgrade to 5.2022.3 made Dataverse deployments fail because the postboot script deployment method was broken. This has been fixed with 5.2022.4, which is why we use this version now. --- modules/dataverse-parent/pom.xml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/modules/dataverse-parent/pom.xml b/modules/dataverse-parent/pom.xml index 4ffc5941278..fe50601d583 100644 --- a/modules/dataverse-parent/pom.xml +++ b/modules/dataverse-parent/pom.xml @@ -337,7 +337,11 @@ ct - + + 5.2022.4 From 05345ba39688291d028af40497b1ada4368a1418 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 4 Nov 2022 17:03:51 +0100 Subject: [PATCH 48/60] feat(ct-base): make buildx/BuildKit use a shared state for builds Should speed up recurring builds a bit. --- modules/container-base/pom.xml | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index 67e2c2f9911..f8b59dcecaa 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -97,6 +97,7 @@ linux/arm64 linux/amd64 + ${project.build.directory}/buildx-state Dockerfile From e261e3701b1af286d5901e1a82f84fff525dcd74 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Fri, 4 Nov 2022 17:09:27 +0100 Subject: [PATCH 49/60] feat(ct-base): switch /docroot to /dv and add volumes #8932 - Instead of a /docroot, add a more generic /dv which is owned by payara:payara and can be used to either store data in a single volume using subfolders or use subfolders with different backing volumes. Anyway, data is not written to overlay FS this way. (As long as an app image points to this location) - Also define /secrets and /dumps as volumes, so data flowing into these locations is again not added to the overlay FS (which might cause severe damage in case of heap dumps!) - Document the different locations in the base image guide. - Remove the /docroot workaround for uploaded files. This will be solved at application level (either by moving the workaround there) or https://github.com/IQSS/dataverse/pull/8983 --- .../source/container/base-image.rst | 48 +++++++++++++++---- .../container-base/src/main/docker/Dockerfile | 19 +++----- 2 files changed, 45 insertions(+), 22 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 197f4175538..8cf6af1f904 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -218,7 +218,16 @@ Locations +++++++++ This environment variables represent certain locations and might be reused in your scripts etc. -These variables aren't meant to be reconfigurable and reflect state in the filesystem layout! +All of these variables aren't meant to be reconfigurable and reflect state in the filesystem layout! + +**Writeable at build time:** + +The overlay filesystem of Docker and other container technologies is not meant to be used for any performance IO. +You should avoid *writing* data anywhere in the file tree at runtime, except for well known locations with mounted +volumes backing them (see below). + +The locations below are meant to be written to when you build a container image, either this base or anything +building upon it. You can also use these for references in scripts, etc. .. list-table:: :align: left @@ -245,10 +254,35 @@ These variables aren't meant to be reconfigurable and reflect state in the files * - ``DEPLOY_DIR`` - ``${HOME_DIR}/deployments`` - Any EAR or WAR file, exploded WAR directory etc are autodeployed on start - * - ``DOCROOT_DIR`` - - ``/docroot`` - - Mount a volume here to store i18n language bundle files, sitemaps, images for Dataverse collections, logos, - custom themes and stylesheets, etc here. You might need to replicate this data or place on shared file storage. + * - ``DOMAIN_DIR`` + - ``${PAYARA_DIR}/glassfish`` ``/domains/${DOMAIN_NAME}`` + - Path to root of the Payara domain applications will be deployed into. Usually ``${DOMAIN_NAME}`` will be ``domain1``. + + +**Writeable at runtime:** + +The locations below are defined as `Docker volumes `_ by the base image. +They will by default get backed by an "anonymous volume", but you can (and should) bind-mount a host directory or +named Docker volume in these places to avoid data loss, gain performance and/or use a network file system. + +**Notes:** +1. On Kubernetes you still need to provide volume definitions for these places in your deployment objects! +2. You should not write data into these locations at build time - it will be shadowed by the mounted volumes! + +.. list-table:: + :align: left + :width: 100 + :widths: 10 10 50 + :header-rows: 1 + + * - Env. variable + - Value + - Description + * - ``STORAGE_DIR`` + - ``/dv`` + - This place is writeable by the Payara user, making it usable as a place to store research data, customizations + or other. Images inheriting the base image should create distinct folders here, backed by different + mounted volumes. * - ``SECRETS_DIR`` - ``/secrets`` - Mount secrets or other here, being picked up automatically by @@ -258,10 +292,6 @@ These variables aren't meant to be reconfigurable and reflect state in the files - ``/dumps`` - Default location where heap dumps will be stored (see above). You should mount some storage here (disk or ephemeral). - * - ``DOMAIN_DIR`` - - ``${PAYARA_DIR}/glassfish`` ``/domains/${DOMAIN_NAME}`` - - Path to root of the Payara domain applications will be deployed into. Usually ``${DOMAIN_NAME}`` will be ``domain1``. - Exposed Ports diff --git a/modules/container-base/src/main/docker/Dockerfile b/modules/container-base/src/main/docker/Dockerfile index cafeb2ffb59..07968e92359 100644 --- a/modules/container-base/src/main/docker/Dockerfile +++ b/modules/container-base/src/main/docker/Dockerfile @@ -1,4 +1,4 @@ -# Copyright 2019 Forschungszentrum Jülich GmbH +# Copyright 2022 Forschungszentrum Jülich GmbH # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. # You may obtain a copy of the License at @@ -38,7 +38,7 @@ ENV PAYARA_DIR="${HOME_DIR}/appserver" \ SCRIPT_DIR="${HOME_DIR}/scripts" \ CONFIG_DIR="${HOME_DIR}/config" \ DEPLOY_DIR="${HOME_DIR}/deployments" \ - DOCROOT_DIR="/docroot" \ + STORAGE_DIR="/dv" \ SECRETS_DIR="/secrets" \ DUMPS_DIR="/dumps" \ PASSWORD_FILE="${HOME_DIR}/passwordFile" \ @@ -73,17 +73,19 @@ ARG GID=1000 USER root WORKDIR / SHELL ["/bin/bash", "-euo", "pipefail", "-c"] +# Mark these directories as mutuable data containers to avoid cluttering the images overlayfs at runtime. +VOLUME ${STORAGE_DIR} ${SECRETS_DIR} ${DUMPS_DIR} RUN < Date: Fri, 4 Nov 2022 17:10:47 +0100 Subject: [PATCH 50/60] ci(ct-base): switch some steps to run on push or schedule #8932 Instead of only running the steps to push images to Docker Hub on a Git push event, also make it possible to run them an anything not being a pull_request event. (Like a schedule) --- .github/workflows/container_base_push.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/container_base_push.yml b/.github/workflows/container_base_push.yml index 82c7a376ae0..2520a7e9257 100644 --- a/.github/workflows/container_base_push.yml +++ b/.github/workflows/container_base_push.yml @@ -53,18 +53,18 @@ jobs: - name: Build base container image with local architecture run: mvn -f modules/container-base -Pct package - - if: ${{ github.event_name == 'push' }} # run only if this is a push - PRs have no access to secrets + - if: ${{ github.event_name != 'pull_request' }} # run only if this is not a pull request - PRs have no access to secrets name: Log in to the Container registry uses: docker/login-action@v1 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - - if: ${{ github.event_name == 'push' }} # run only if this is a push - multi-arch makes no sense with PR + - if: ${{ github.event_name != 'pull_request' }} # run only if this is not a pull request - multi-arch makes no sense with PR name: Set up QEMU for multi-arch builds uses: docker/setup-qemu-action@v2 - name: Re-set image tag based on branch if: ${{ github.ref == 'master' }} run: echo "IMAGE_TAG=release" - - if: ${{ github.event_name == 'push' }} # run only if this is a push - tag push will only succeed in upstream + - if: ${{ github.event_name != 'pull_request' }} # run only if this is not a pull request - tag push will only succeed in upstream name: Deploy multi-arch base container image to Docker Hub run: mvn -f modules/container-base -Pct deploy -Dbase.image.tag=${{ env.IMAGE_TAG }} -Ddocker.registry=${{ env.REGISTRY }} From fbfcaa4c5fec93dc2e8ea434497a700e5a047463 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 8 Nov 2022 16:30:39 +0100 Subject: [PATCH 51/60] docs,ci(ct-base): add and push README description to Docker Hub #8932 When pushing to Docker Hub from development, we now also push a short description with disclaimers, links to docs and license hints. --- .github/workflows/container_base_push.yml | 21 +++++++-- modules/container-base/README.md | 56 +++++++++++++++++++++++ 2 files changed, 74 insertions(+), 3 deletions(-) create mode 100644 modules/container-base/README.md diff --git a/.github/workflows/container_base_push.yml b/.github/workflows/container_base_push.yml index 2520a7e9257..1ef8ba94e78 100644 --- a/.github/workflows/container_base_push.yml +++ b/.github/workflows/container_base_push.yml @@ -9,6 +9,7 @@ on: paths: - 'modules/container-base/**' - 'modules/dataverse-parent/pom.xml' + - '.github/workflows/container_base_push.yml' pull_request: branches: - 'develop' @@ -16,6 +17,7 @@ on: paths: - 'modules/container-base/**' - 'modules/dataverse-parent/pom.xml' + - '.github/workflows/container_base_push.yml' env: IMAGE_TAG: develop @@ -53,18 +55,31 @@ jobs: - name: Build base container image with local architecture run: mvn -f modules/container-base -Pct package - - if: ${{ github.event_name != 'pull_request' }} # run only if this is not a pull request - PRs have no access to secrets + # Run anything below only if this is not a pull request. + # Accessing, pushing tags etc. to DockerHub will only succeed in upstream because secrets. + + - if: ${{ github.event_name != 'pull_request' && github.ref == 'develop' }} + name: Push description to DockerHub + uses: peter-evans/dockerhub-description@v3 + with: + username: ${{ secrets.DOCKERHUB_USERNAME }} + password: ${{ secrets.DOCKERHUB_TOKEN }} + repository: gdcc/base + short-description: "Dataverse Base Container image providing Payara application server and optimized configuration" + readme-filepath: ./modules/container-base/README.md + + - if: ${{ github.event_name != 'pull_request' }} name: Log in to the Container registry uses: docker/login-action@v1 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - - if: ${{ github.event_name != 'pull_request' }} # run only if this is not a pull request - multi-arch makes no sense with PR + - if: ${{ github.event_name != 'pull_request' }} name: Set up QEMU for multi-arch builds uses: docker/setup-qemu-action@v2 - name: Re-set image tag based on branch if: ${{ github.ref == 'master' }} run: echo "IMAGE_TAG=release" - - if: ${{ github.event_name != 'pull_request' }} # run only if this is not a pull request - tag push will only succeed in upstream + - if: ${{ github.event_name != 'pull_request' }} name: Deploy multi-arch base container image to Docker Hub run: mvn -f modules/container-base -Pct deploy -Dbase.image.tag=${{ env.IMAGE_TAG }} -Ddocker.registry=${{ env.REGISTRY }} diff --git a/modules/container-base/README.md b/modules/container-base/README.md new file mode 100644 index 00000000000..d6f93b14da7 --- /dev/null +++ b/modules/container-base/README.md @@ -0,0 +1,56 @@ +# Dataverse Base Container Image + +A "base image" offers you a pre-installed and pre-tuned application server to deploy Dataverse software to. +Adding basic functionality like executing scripts at container boot, monitoring, memory tweaks etc is all done +at this layer, to make the application image focus on the app itself. + +## Quick Reference + +**Maintained by:** + +This image is created, maintained and supported by the Dataverse community on a best-effort basis. + +**Where to find documentation:** + +The [Dataverse Container Guide - Base Image](https://guides.dataverse.org/en/latest/container/base-image.html) +provides in-depth information about content, building, tuning and so on for this image. + +**Where to get help and ask questions:** + +IQSS will not offer you support how to deploy or run it, please reach out to the community for help on using it. +You can join the Community Chat on Matrix at https://chat.dataverse.org or the Community Slack at +https://dataversecommunity.slack.com to ask for help and guidance. + +## Supported Image Tags + +This image is sourced within the main upstream code [repository of the Dataverse software](https://github.com/IQSS/dataverse). +Development and maintenance happens there (again, by the community). Community supported image tags are based on the two +most important branches: + +- `develop` representing the unstable state of affairs in Dataverse's development branch + ([`Dockerfile`](https://github.com/IQSS/dataverse/tree/develop/modules/container-base/src/main/docker/Dockerfile)) +- `release` representing the latest stable release in Dataverse's main branch + ([`Dockerfile`](https://github.com/IQSS/dataverse/tree/master/modules/container-base/src/main/docker/Dockerfile)) + +Within the main repository, you may find the base image's files at `/modules/container-base`. +This Maven module uses the `Maven Docker Plugin `_ to build and ship the image. +You may use, extend, or alter this image to your liking and/or host in some different registry if you want to. + +**Supported architectures:** This image is created as a "multi-arch image", supporting the most common architectures +Dataverse usually runs on: AMD64 (Windows/Linux/...) and ARM64 (Apple M1/M2). + +## License + +Image content created by the community is licensed under [Apache License, Version 2.0](https://www.apache.org/licenses/LICENSE-2.0), +like the [main Dataverse project](https://github.com/IQSS/dataverse/blob/develop/LICENSE.md). + +Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and limitations under the License. + +As with all Docker images, all images likely also contain other software which may be under other licenses (such as +[Payara Server](https://github.com/payara/Payara/blob/master/LICENSE.txt), Bash, etc from the base +distribution, along with any direct or indirect (Java) dependencies contained). + +As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies +with any relevant licenses for all software contained within. From 1241591eb171609542df9e218388f6bb71e7ae71 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 8 Nov 2022 16:31:33 +0100 Subject: [PATCH 52/60] docs(ct-base): add short intro to base image docs page #8932 Explain a bit (short!) what this image is and what to expect. --- doc/sphinx-guides/source/container/base-image.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 8cf6af1f904..8016ce95f27 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -4,8 +4,13 @@ Application Base Image .. contents:: |toctitle| :local: +A "base image" offers you a pre-installed and pre-tuned application server to deploy Dataverse software to. +Adding basic functionality like executing scripts at container boot, monitoring, memory tweaks etc is all done +at this layer, to make the application image focus on the app itself. + Within the main repository, you may find the base image's files at ``/modules/container-base``. This Maven module uses the `Maven Docker Plugin `_ to build and ship the image. +You may use, extend, or alter this image to your liking and/or host in some different registry if you want to. **NOTE: This image is created, maintained and supported by the Dataverse community on a best-effort basis.** IQSS will not offer you support how to deploy or run it, please reach out to the community for help on using it. From 22eb801f0a1dacaea2f34ea1a2864cf5d54f5365 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 8 Nov 2022 23:36:39 +0100 Subject: [PATCH 53/60] ci(ct-base): update action versions #8932 --- .github/workflows/container_base_push.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/container_base_push.yml b/.github/workflows/container_base_push.yml index 1ef8ba94e78..519e135f944 100644 --- a/.github/workflows/container_base_push.yml +++ b/.github/workflows/container_base_push.yml @@ -38,15 +38,15 @@ jobs: steps: - name: Checkout repository - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Set up JDK ${{ matrix.jdk }} - uses: actions/setup-java@v2 + uses: actions/setup-java@v3 with: java-version: ${{ matrix.jdk }} distribution: 'adopt' - name: Cache Maven packages - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: ~/.m2 key: ${{ runner.os }}-m2-${{ hashFiles('**/pom.xml') }} @@ -70,7 +70,7 @@ jobs: - if: ${{ github.event_name != 'pull_request' }} name: Log in to the Container registry - uses: docker/login-action@v1 + uses: docker/login-action@v2 with: username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} From 7d4388ed5022e64a1db721160169d93a2c565007 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 8 Nov 2022 23:42:20 +0100 Subject: [PATCH 54/60] ci(ct-base): fix step if-conditions for branch names #8932 Github context offers ".ref" but we need ".ref_name" to match *just* the branch name. --- .github/workflows/container_base_push.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/container_base_push.yml b/.github/workflows/container_base_push.yml index 519e135f944..5a7280ce3b1 100644 --- a/.github/workflows/container_base_push.yml +++ b/.github/workflows/container_base_push.yml @@ -58,7 +58,7 @@ jobs: # Run anything below only if this is not a pull request. # Accessing, pushing tags etc. to DockerHub will only succeed in upstream because secrets. - - if: ${{ github.event_name != 'pull_request' && github.ref == 'develop' }} + - if: ${{ github.event_name == 'push' && github.ref_name == 'develop' }} name: Push description to DockerHub uses: peter-evans/dockerhub-description@v3 with: @@ -78,7 +78,7 @@ jobs: name: Set up QEMU for multi-arch builds uses: docker/setup-qemu-action@v2 - name: Re-set image tag based on branch - if: ${{ github.ref == 'master' }} + if: ${{ github.ref_name == 'master' }} run: echo "IMAGE_TAG=release" - if: ${{ github.event_name != 'pull_request' }} name: Deploy multi-arch base container image to Docker Hub From 3d790aacc7ffd4f44e8fb9a4880400960b52b48d Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Tue, 8 Nov 2022 23:50:31 +0100 Subject: [PATCH 55/60] ci(ct-base): fix failing image pushes #8932 The login to the registry needs to be explicit otherwise pushes will fail to acquire the correct token and pushes are rejected with "insufficient_scope: authorization failed" --- .github/workflows/container_base_push.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/container_base_push.yml b/.github/workflows/container_base_push.yml index 5a7280ce3b1..fc0a3564e50 100644 --- a/.github/workflows/container_base_push.yml +++ b/.github/workflows/container_base_push.yml @@ -72,6 +72,7 @@ jobs: name: Log in to the Container registry uses: docker/login-action@v2 with: + registry: ${{ env.REGISTRY }} username: ${{ secrets.DOCKERHUB_USERNAME }} password: ${{ secrets.DOCKERHUB_TOKEN }} - if: ${{ github.event_name != 'pull_request' }} From 609688092192e674686243096fcc45a9e4086826 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 9 Nov 2022 15:18:48 +0100 Subject: [PATCH 56/60] docs(ct-base): rephrase slightly to match wording in main index Co-authored-by: Benjamin Peuch --- doc/sphinx-guides/source/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/sphinx-guides/source/index.rst b/doc/sphinx-guides/source/index.rst index be32e94d80f..0cd01b8a5a7 100755 --- a/doc/sphinx-guides/source/index.rst +++ b/doc/sphinx-guides/source/index.rst @@ -31,7 +31,7 @@ The User Guide is further divided into primary activities: finding & using data, adding Datasets, administering dataverses or Datasets, and Dataset exploration/visualizations. Details on all of the above tasks can be found in the Users Guide. The Installation Guide is for people or organizations who want to host their -own Dataverse. The Container Guide adds to this information on container-based installations. +own Dataverse. The Container Guide gives information on how to deploy Dataverse with containers. The Developer Guide contains instructions for people who want to contribute to the Open Source Dataverse project or who want to modify the code to suit their own needs. Finally, the API Guide is for From 4a79dcbddde84251c4a975e3b858d00171ffef66 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Wed, 9 Nov 2022 15:25:33 +0100 Subject: [PATCH 57/60] docs(ct-base): apply some language tweaks to docs pages Co-authored-by: Benjamin Peuch --- doc/sphinx-guides/source/container/index.rst | 2 +- modules/container-base/README.md | 10 +++++----- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/sphinx-guides/source/container/index.rst b/doc/sphinx-guides/source/container/index.rst index f6c99bfc19e..6d22318ad03 100644 --- a/doc/sphinx-guides/source/container/index.rst +++ b/doc/sphinx-guides/source/container/index.rst @@ -9,7 +9,7 @@ Container Guide Running Dataverse software in containers is quite different than in a :doc:`classic installation <../installation/prep>`. -Both approaches have pros and cons. These days (2022) containers are very often used for development and testing, +Both approaches have pros and cons. These days, containers are very often used for development and testing, but there is an ever rising move for running applications in the cloud using container technology. **NOTE:** diff --git a/modules/container-base/README.md b/modules/container-base/README.md index d6f93b14da7..ce48eae8a65 100644 --- a/modules/container-base/README.md +++ b/modules/container-base/README.md @@ -1,7 +1,7 @@ # Dataverse Base Container Image A "base image" offers you a pre-installed and pre-tuned application server to deploy Dataverse software to. -Adding basic functionality like executing scripts at container boot, monitoring, memory tweaks etc is all done +Adding basic functionality like executing scripts at container boot, monitoring, memory tweaks, etc., is all done at this layer, to make the application image focus on the app itself. ## Quick Reference @@ -17,14 +17,14 @@ provides in-depth information about content, building, tuning and so on for this **Where to get help and ask questions:** -IQSS will not offer you support how to deploy or run it, please reach out to the community for help on using it. +IQSS will not offer you support how to deploy or run it. Please reach out to the community for help on using it. You can join the Community Chat on Matrix at https://chat.dataverse.org or the Community Slack at https://dataversecommunity.slack.com to ask for help and guidance. ## Supported Image Tags This image is sourced within the main upstream code [repository of the Dataverse software](https://github.com/IQSS/dataverse). -Development and maintenance happens there (again, by the community). Community supported image tags are based on the two +Development and maintenance happens there (again, by the community). Community-supported image tags are based on the two most important branches: - `develop` representing the unstable state of affairs in Dataverse's development branch @@ -32,7 +32,7 @@ most important branches: - `release` representing the latest stable release in Dataverse's main branch ([`Dockerfile`](https://github.com/IQSS/dataverse/tree/master/modules/container-base/src/main/docker/Dockerfile)) -Within the main repository, you may find the base image's files at `/modules/container-base`. +Within the main repository, you may find the base image files at `/modules/container-base`. This Maven module uses the `Maven Docker Plugin `_ to build and ship the image. You may use, extend, or alter this image to your liking and/or host in some different registry if you want to. @@ -49,7 +49,7 @@ Unless required by applicable law or agreed to in writing, software distributed See the License for the specific language governing permissions and limitations under the License. As with all Docker images, all images likely also contain other software which may be under other licenses (such as -[Payara Server](https://github.com/payara/Payara/blob/master/LICENSE.txt), Bash, etc from the base +[Payara Server](https://github.com/payara/Payara/blob/master/LICENSE.txt), Bash, etc., from the base distribution, along with any direct or indirect (Java) dependencies contained). As for any pre-built image usage, it is the image user's responsibility to ensure that any use of this image complies From f1a64a873c7900462f5ae96fb2cb3c1186339a46 Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 10 Nov 2022 16:39:24 +0100 Subject: [PATCH 58/60] docs(ct-base): incorporate review suggestions #8932 Thanks @atrisovic @pdurbin --- doc/sphinx-guides/source/container/base-image.rst | 2 ++ doc/sphinx-guides/source/container/index.rst | 8 ++++---- modules/container-base/README.md | 13 +++++++++---- 3 files changed, 15 insertions(+), 8 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 8016ce95f27..9391c90f695 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -8,6 +8,8 @@ A "base image" offers you a pre-installed and pre-tuned application server to de Adding basic functionality like executing scripts at container boot, monitoring, memory tweaks etc is all done at this layer, to make the application image focus on the app itself. +**NOTE: The base image does not contain the Dataverse application itself.** + Within the main repository, you may find the base image's files at ``/modules/container-base``. This Maven module uses the `Maven Docker Plugin `_ to build and ship the image. You may use, extend, or alter this image to your liking and/or host in some different registry if you want to. diff --git a/doc/sphinx-guides/source/container/index.rst b/doc/sphinx-guides/source/container/index.rst index 6d22318ad03..25d891016ed 100644 --- a/doc/sphinx-guides/source/container/index.rst +++ b/doc/sphinx-guides/source/container/index.rst @@ -7,10 +7,10 @@ Container Guide base-image -Running Dataverse software in containers is quite different than in a :doc:`classic installation <../installation/prep>`. +Running Dataverse software in containers is quite different than in a :doc:`standard installation <../installation/prep>`. Both approaches have pros and cons. These days, containers are very often used for development and testing, -but there is an ever rising move for running applications in the cloud using container technology. +but there is an ever rising move toward running applications in the cloud using container technology. **NOTE:** **As the Institute for Quantitative Social Sciences (IQSS) at Harvard is running their installations in the classic @@ -22,5 +22,5 @@ solutions to run containers in production. There is the `Dataverse on K8s projec purpose. This guide focuses on describing the container images managed from the main Dataverse repository (again: by the -community, not IQSS), their features and limitations. Instructions on how to build the images yourself, how to -extend them and how to use them for development purposes may be found in respective subpages. \ No newline at end of file +community, not IQSS), their features and limitations. Instructions on how to build the images yourself and how to +develop and extend them further may be found in respective subpages. \ No newline at end of file diff --git a/modules/container-base/README.md b/modules/container-base/README.md index ce48eae8a65..cbf8921f9e7 100644 --- a/modules/container-base/README.md +++ b/modules/container-base/README.md @@ -1,8 +1,13 @@ # Dataverse Base Container Image -A "base image" offers you a pre-installed and pre-tuned application server to deploy Dataverse software to. +The Dataverse Base Container Image contains primarily a pre-installed and pre-tuned application server with the +necessary software dependencies for deploying and launching a Dataverse repository installation. + Adding basic functionality like executing scripts at container boot, monitoring, memory tweaks, etc., is all done -at this layer, to make the application image focus on the app itself. +at this layer. Application images building from this very base focus on adding deployable Dataverse code and +actual scripts. + +*Note:* Currently, there is no application image. Please watch https://github.com/IQSS/dataverse/issues/8934 ## Quick Reference @@ -17,7 +22,7 @@ provides in-depth information about content, building, tuning and so on for this **Where to get help and ask questions:** -IQSS will not offer you support how to deploy or run it. Please reach out to the community for help on using it. +IQSS will not offer support on how to deploy or run it. Please reach out to the community for help on using it. You can join the Community Chat on Matrix at https://chat.dataverse.org or the Community Slack at https://dataversecommunity.slack.com to ask for help and guidance. @@ -33,7 +38,7 @@ most important branches: ([`Dockerfile`](https://github.com/IQSS/dataverse/tree/master/modules/container-base/src/main/docker/Dockerfile)) Within the main repository, you may find the base image files at `/modules/container-base`. -This Maven module uses the `Maven Docker Plugin `_ to build and ship the image. +This Maven module uses the [Maven Docker Plugin](https://dmp.fabric8.io) to build and ship the image. You may use, extend, or alter this image to your liking and/or host in some different registry if you want to. **Supported architectures:** This image is created as a "multi-arch image", supporting the most common architectures From 426f74623278a3d65c413378c07b347806d1b40c Mon Sep 17 00:00:00 2001 From: Oliver Bertuch Date: Thu, 10 Nov 2022 21:43:46 +0100 Subject: [PATCH 59/60] style(ct-base): rephrase container image tags #8932 As requested by review from @pdurbin, aligning image tag names. --- .github/workflows/container_base_push.yml | 4 ++-- doc/sphinx-guides/source/container/base-image.rst | 10 ++++++---- modules/container-base/README.md | 8 ++++---- modules/container-base/pom.xml | 2 +- 4 files changed, 13 insertions(+), 11 deletions(-) diff --git a/.github/workflows/container_base_push.yml b/.github/workflows/container_base_push.yml index fc0a3564e50..120f55984dc 100644 --- a/.github/workflows/container_base_push.yml +++ b/.github/workflows/container_base_push.yml @@ -20,7 +20,7 @@ on: - '.github/workflows/container_base_push.yml' env: - IMAGE_TAG: develop + IMAGE_TAG: unstable REGISTRY: docker.io jobs: @@ -80,7 +80,7 @@ jobs: uses: docker/setup-qemu-action@v2 - name: Re-set image tag based on branch if: ${{ github.ref_name == 'master' }} - run: echo "IMAGE_TAG=release" + run: echo "IMAGE_TAG=stable" - if: ${{ github.event_name != 'pull_request' }} name: Deploy multi-arch base container image to Docker Hub run: mvn -f modules/container-base -Pct deploy -Dbase.image.tag=${{ env.IMAGE_TAG }} -Ddocker.registry=${{ env.REGISTRY }} diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index 9391c90f695..b03879f83f8 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -22,12 +22,14 @@ efforts. Supported Image Tags ++++++++++++++++++++ -This image is sourced within the main upstream code repository of the Dataverse software. Development and maintenance -happens there (again, by the community). Community supported image tags are based on the two most important branches: +This image is sourced from the main upstream code `repository of the Dataverse software `_. +Development and maintenance of the `image's code ` +happens there (again, by the community). Community-supported image tags are based on the two most important +upstream branches: -- ``develop`` representing the unstable state of affairs in Dataverse's development branch +- The ``unstable`` tag corresponds to the ``develop`` branch, where pull requests are merged. (`Dockerfile `__) -- ``release`` representing the latest stable release in Dataverse's main branch +- The ``stable`` tag corresponds to the ``master`` branch, where releases are cut from. (`Dockerfile `__) diff --git a/modules/container-base/README.md b/modules/container-base/README.md index cbf8921f9e7..15011d5c6f4 100644 --- a/modules/container-base/README.md +++ b/modules/container-base/README.md @@ -29,12 +29,12 @@ https://dataversecommunity.slack.com to ask for help and guidance. ## Supported Image Tags This image is sourced within the main upstream code [repository of the Dataverse software](https://github.com/IQSS/dataverse). -Development and maintenance happens there (again, by the community). Community-supported image tags are based on the two -most important branches: +Development and maintenance of the [image's code](https://github.com/IQSS/dataverse/tree/develop/modules/container-base) +happens there (again, by the community). Community-supported image tags are based on the two most important branches: -- `develop` representing the unstable state of affairs in Dataverse's development branch +- The `unstable` tag corresponds to the `develop` branch, where pull requests are merged. ([`Dockerfile`](https://github.com/IQSS/dataverse/tree/develop/modules/container-base/src/main/docker/Dockerfile)) -- `release` representing the latest stable release in Dataverse's main branch +- The `stable` tag corresponds to the `master` branch, where releases are cut from. ([`Dockerfile`](https://github.com/IQSS/dataverse/tree/master/modules/container-base/src/main/docker/Dockerfile)) Within the main repository, you may find the base image files at `/modules/container-base`. diff --git a/modules/container-base/pom.xml b/modules/container-base/pom.xml index f8b59dcecaa..bbee6ad67d5 100644 --- a/modules/container-base/pom.xml +++ b/modules/container-base/pom.xml @@ -40,7 +40,7 @@ docker-build gdcc/base:${base.image.tag} - develop + unstable eclipse-temurin:${target.java.version}-jre 1000 1000 From 5122515ebe2c8beb04306b79e04fc7735bef3d66 Mon Sep 17 00:00:00 2001 From: Philip Durbin Date: Fri, 16 Dec 2022 14:35:16 -0500 Subject: [PATCH 60/60] tweak docs #8932 --- .../source/container/base-image.rst | 8 +++---- doc/sphinx-guides/source/container/index.rst | 23 ++++++++++--------- .../source/developers/containers.rst | 2 ++ 3 files changed, 18 insertions(+), 15 deletions(-) diff --git a/doc/sphinx-guides/source/container/base-image.rst b/doc/sphinx-guides/source/container/base-image.rst index b03879f83f8..931c722f91b 100644 --- a/doc/sphinx-guides/source/container/base-image.rst +++ b/doc/sphinx-guides/source/container/base-image.rst @@ -23,7 +23,7 @@ Supported Image Tags ++++++++++++++++++++ This image is sourced from the main upstream code `repository of the Dataverse software `_. -Development and maintenance of the `image's code ` +Development and maintenance of the `image's code `_ happens there (again, by the community). Community-supported image tags are based on the two most important upstream branches: @@ -49,7 +49,7 @@ The base image provides: This image is created as a "multi-arch image", see :ref:`below `. -It inherits being built on an Ubuntu environment from the upstream +It inherits (is built on) an Ubuntu environment from the upstream `base image of Eclipse Temurin `_. You are free to change the JRE/JDK image to your liking (see below). @@ -75,7 +75,7 @@ Some additional notes, using Maven parameters to change the build and use ...: | *Note:* default is ``develop`` - | ... a different image name and tag: add ``-Dbase.image=name:tag``. | *Note:* default is ``gdcc/base:${base.image.tag}`` -- ... a different image registry than *Docker Hub*: add ``-Ddocker.registry=registry.example.org`` (see also +- ... a different image registry than Docker Hub: add ``-Ddocker.registry=registry.example.org`` (see also `DMP docs on registries `__) - ... a different Payara version: add ``-Dpayara.version=V.YYYY.R``. - | ... a different Temurin JRE version ``A``: add ``-Dtarget.java.version=A`` (i.e. ``11``, ``17``, ...). @@ -351,4 +351,4 @@ from `run-java-sh recommendations`_. .. _Pre/postboot script docs: https://docs.payara.fish/community/docs/Technical%20Documentation/Payara%20Micro%20Documentation/Payara%20Micro%20Configuration%20and%20Management/Micro%20Management/Asadmin%20Commands/Pre%20and%20Post%20Boot%20Commands.html .. _MicroProfile Config Sources: https://docs.payara.fish/community/docs/Technical%20Documentation/MicroProfile/Config/Overview.html -.. _run-java-sh recommendations: https://github.com/fabric8io-images/run-java-sh/blob/master/TUNING.md#recommandations \ No newline at end of file +.. _run-java-sh recommendations: https://github.com/fabric8io-images/run-java-sh/blob/master/TUNING.md#recommandations diff --git a/doc/sphinx-guides/source/container/index.rst b/doc/sphinx-guides/source/container/index.rst index 25d891016ed..92ac94e2cf2 100644 --- a/doc/sphinx-guides/source/container/index.rst +++ b/doc/sphinx-guides/source/container/index.rst @@ -1,26 +1,27 @@ Container Guide =============== -**Contents:** - -.. toctree:: - - base-image - -Running Dataverse software in containers is quite different than in a :doc:`standard installation <../installation/prep>`. +Running the Dataverse software in containers is quite different than in a :doc:`standard installation <../installation/prep>`. Both approaches have pros and cons. These days, containers are very often used for development and testing, but there is an ever rising move toward running applications in the cloud using container technology. **NOTE:** -**As the Institute for Quantitative Social Sciences (IQSS) at Harvard is running their installations in the classic -deployment way, the container support is mostly created and maintained by the Dataverse community on a best-effort +**As the Institute for Quantitative Social Sciences (IQSS) at Harvard is running a standard, non-containerized installation, +container support described in this guide is mostly created and maintained by the Dataverse community on a best-effort basis.** This guide is *not* about installation on technology like Docker Swarm, Kubernetes, Rancher or other solutions to run containers in production. There is the `Dataverse on K8s project `_ for this -purpose. +purpose, as mentioned in the :doc:`/developers/containers` section of the Developer Guide. This guide focuses on describing the container images managed from the main Dataverse repository (again: by the community, not IQSS), their features and limitations. Instructions on how to build the images yourself and how to -develop and extend them further may be found in respective subpages. \ No newline at end of file +develop and extend them further are provided. + +**Contents:** + +.. toctree:: + + base-image + diff --git a/doc/sphinx-guides/source/developers/containers.rst b/doc/sphinx-guides/source/developers/containers.rst index 64c7710f0f5..63eff266a4f 100755 --- a/doc/sphinx-guides/source/developers/containers.rst +++ b/doc/sphinx-guides/source/developers/containers.rst @@ -9,6 +9,8 @@ The Dataverse Community is exploring the use of Docker, Kubernetes, and other co The :doc:`testing` section mentions using Docker for integration tests. +See also the :doc:`/container/index`. + .. contents:: |toctitle| :local: