jeffersonlab/wildfly repository overview

⁠wildfly

Configurable Wildfly⁠ base Docker image and bash setup scripts.

• Overview⁠
• Configure⁠
• Release⁠

⁠Overview

This Jefferson Lab Wildfly template for Wildfly 37.0.1 assumes apps are authenticated with Keycloak⁠ and use an Oracle or MariaDB database. It is generally expected that only one database will be configured at a time. Optionally an SMTP mail server can be configured. The full EE Wildfly distribution is used as a starting point and a few libraries are added including:

• JLog: JLab logbook client
• Keycloak admin client
• Apache POI (Excel doc API)
• Tuckey URL rewrite

⁠Configure

Wildfly must be configured before the first deployment of an app. scripts/wildfly-lib.sh⁠ is a library of bash functions that install and configure Wildfly; the image has it at /wildfly-lib.sh. Run it with an env file of bash variables and the functions to call, in order. It stops at the first function that fails:

/wildfly-lib.sh -e /app-setup.env wildfly_start_and_wait config_keycloak_client config_oracle_client \
  config_email wildfly_reload wildfly_stop

Or source it and call the functions from your own script:

. /wildfly-lib.sh
WILDFLY_APP_HOME=/opt/wildfly/current
wildfly_start_and_wait && config_gzip && wildfly_reload && wildfly_stop

Each function checks the variables it needs and fails, naming any that are missing. Nothing runs unless you name it: call only the functions your server and app need. /wildfly-lib.sh --help lists the functions and their variables. Example env files: the image's server config⁠ and install config⁠, and an app config⁠. Bash can be executed on Linux, Windows (WSL2), and Mac with some perseverance.

Note: If you are using Windows and WSL2 you may need to run dos2unix on .env and .sh files

⁠Install

For a new Wildfly on a host or in an image. On RHEL 9, as root:

wildfly-lib.sh -e host.env install_java create_user_and_group download_wildfly unzip_wildfly \
  create_wildfly_symlinks adjust_jvm_options create_systemd_service create_log_file_cleanup_cron

⁠Server Setup

Only needs to be executed once per permanent installation of Wildfly. All but apply_elytron_patch need Wildfly running: call wildfly_start_and_wait first, and wildfly_reload or wildfly_stop last. Every function here needs WILDFLY_APP_HOME, the path to Wildfly's home dir (/opt/wildfly/current in the image), so the table leaves it out. Optional variables are in italics.

Note: The image serves a self-signed localhost demo certificate, config/localhost-demo.crt⁠, from its keystore server.p12. Its private key, config/localhost-demo.key⁠, is public: the pair is for local development and tests only and must never be used on a real host. Every build serves the same certificate, so integration tests can pin it and developers can trust it in their browser once (SHA-256 fingerprint 41:01:9E:C4:7F:4F:6B:80:21:E6:49:49:11:0B:39:3F:9E:4E:65:BE:C2:C2:6E:DA:26:91:76:94:6E:11:19:31). To serve your own certificate, mount a custom PKCS12 keystore file to /opt/wildfly/current/standalone/configuration/server.p12. pem_to_keystore makes one from PEM files: it needs PEM_CERT_PATH, PEM_INTERMEDIATE_CERT_PATH, PEM_KEY_PATH, KEYSTORE_PASS, and KEYSTORE_OUTPUT_PATH.

⁠App Setup

Must be executed once per app installed in Wildfly, with Wildfly running. These also need WILDFLY_APP_HOME. Call one database's function, not both.

Note: The _dynamic functions only make sense for Wildfly instances used for a single app (such as in a Container). Providing runtime overrides to a multi-app configuration would overwrite all app configs of the same name.

Note: As an alternative to the bash scripts The docker image configures Wildfly for use in the compose environment and that's a good starting point to copy from. Outside a compose environment you may need to tweak the standalone.xml configuration to use different host names and ports (For example Oracle and Keycloak host names would need to be updated to localhost:1521 and localhost:8081 respectively when using the deps.yaml and running Wildfly outside the compose network):

docker compose up
docker exec -it demo /opt/jboss/wildfly/bin/jboss-cli.sh --connect -c "undeploy smoothness-demo.war"
docker exec -it demo /opt/jboss/wildfly/bin/jboss-cli.sh --connect -c shutdown
docker cp demo:/opt/jboss/wildfly .

⁠Migrating from the setup scripts

Version 4 replaced the separate setup scripts with wildfly-lib.sh:

• server-setup.sh ENV_FILE FUNCTION... and app-setup.sh ENV_FILE FUNCTION... still work, but are deprecated; either one runs any function in the library. They no longer run a default list of functions when none is named: name each one, or call wildfly-lib.sh as above.
• A function now fails if a variable it needs is missing, where it used to skip silently. For example config_email without EMAIL_FROM, or config_oracle_client without ORACLE_DATASOURCE, now fails the build: drop the call if you don't need it. Functions no longer read variables that other functions need, so server-setup.sh no longer needs WILDFLY_RUN_USER for config_email, and app-setup.sh no longer needs the KEYCLOAK_* variables for config_oracle_client.
• The on/off variables are gone, since calling a function is what turns it on: APPLY_ELYTRON_PATCH, ACCESS_LOG, GZIP, PROXY, PERSISTENT_SESSIONS, WILDFLY_SKIP_START, WILDFLY_SKIP_RELOAD, and WILDFLY_SKIP_STOP.
• Removed scripts, and the functions that replace them: rhel9-setup.sh and devcontainer-setup.sh: the Install⁠ functions, with adjust_java, download, unzip_and_chmod, and create_symbolic_links renamed install_java, download_wildfly, unzip_wildfly, and create_wildfly_symlinks. provided-setup.sh: add_jboss_modules (was add_modules and config_provided) and enable_global_modules (was enable_globals). pem-to-java-keystore.sh: pem_to_keystore.
• config_admin_user reads the admin console user's name and password from WILDFLY_ADMIN_USER and WILDFLY_ADMIN_PASS, not WILDFLY_USER and WILDFLY_PASS. WILDFLY_USER now only means the OS user that owns and runs Wildfly, in the Install⁠ functions.
• wildfly_start_and_wait runs Wildfly as WILDFLY_RUN_USER only when that isn't the current user, so it also works when the build already runs as that user.
• create_log_file_cleanup_cron puts its script in WILDFLY_USER_HOME and runs it as WILDFLY_USER, not always in /opt/wildfly as wildfly.

⁠Docker Runtime

These environment variables are Docker specific and are used by the docker-entrypoint.sh⁠ script to wait on the Oracle database to start.

Note: The entrypoint script waits for either an Oracle or a MariaDB database to start but not both. Oracle takes precedence.

⁠Release

1. Bump the version number in the VERSION file and commit and push to GitHub (using Semantic Versioning⁠).
2. The CD⁠ GitHub Action should run automatically invoking:
   • The Create release⁠ GitHub Action to tag the source and create release notes summarizing any pull requests. Edit the release notes to add any missing details.
   • The Publish docker image⁠ GitHub Action to create a new demo Docker image.