A Java EE 8 web application template and JSP tag library based on the JQuery UI Smoothness theme. The included demo web application showcases the template layout.
The template is designed for database-centric web applications in the JLab accelerator environment and supports interactions with the following dependent services (for the demo they're Containers):
- Keycloak - OAuth OIDC authentication
- Oracle DB - data persistence (test server linked)
- Puppet-Show - HTML-to-PDF reports
- SMTP Email - send email programmatically (test server linked)
- JLab Logbook - operations electronic event logging
Client-side libraries (JavaScript):
- jQuery - General Web API wrapper
- jQuery UI - General User Interface widgets
- select2 - Improved select widget (multi-select)
- Flot - Graphing and reports
Server-side librarires (Java):
- Tuckey urlrewrite - URL Rewriting (cache busting resource versioning)
- Hibernate - Object-Relational Mapping (persistence).
- JLog - JLab elog API
This git repo is actually comprised of two projects tied together in a Gradle Multi-Project build:
- smoothness-weblib - the library for sharing
- smoothness-demo - a demo application that uses the library
The demo is included in a Gradle Multi-Project build mainly so we can take advantage of the artifact dependency feature, such that we can build the library and quickly test it in the demo without having to publish to a maven artifact repo and then download it from the repo (faster build/deploy/test cycle).
- Grab project
git clone https://github.com/JeffersonLab/smoothness
cd smoothness
- Launch Compose
docker compose up
- Navigate to page (Link)
http://localhost:8080/smoothness-demo
Note: Login with demo username "tbrown" and password "password".
This library requires a Java 11+ JVM and standard library at run time, plus a Java EE 8+ application server (developed with Wildfly).
You can obtain the library jar file from the Maven Central repository directly or from a Maven friendly build tool with the following coordinates (Gradle example shown):
implementation 'org.jlab:smoothness-weblib:<version>'
Check the Release Notes to see what has changed in each version.
This application requires a Java 11+ JVM and standard library to run, plus a Java EE 8+ application server (developed with Wildfly). Use the Docker Compose quickstart to automate the setup of the app, else manually:
- Install service dependencies
- Download Wildfly 26.1.3
- Configure Wildfly and start it
- Download demo.war and deploy it to Wildfly
- Navigate your web browser to localhost:8080/smoothness-demo
We use the JeffersonLab/wildfly bash scripts to setup Wildfly. See JeffersonLab/wildfly#configure.
At runtime smoothness apps use the following global environment variables:
| Name | Description |
|---|---|
| CDN_SERVER | Optional (Unless RESOURCE_LOCATION=CDN). Host name and port of content delivery network host for shared smoothness resources |
| CDN_VERSION | Optional (Unless RESOURCE_LOCATION=CDN). Version of smoothness lib on CDN |
| BACKEND_SERVER_URL | Scheme, host name, and port of app server from inside the backend network. This only differs from FRONTEND_SERVER_URL in some scenarios, such as Docker. Needed for puppet show service. |
| JLAB_RUN_URL | Optional - URL to JLab run dates lookup JSON service (used by date picker) |
| KEYCLOAK_SU_IDP | Optional - If specified a Switch User (SU) link will appear next to login with the kc_idp_hint. Useful when default login uses SPNEGO/Kerberos or perhaps WebAuthn. |
| KEYCLOAK_HEADLESS_IDP | Optional - A Keycloak IDP can only have one SPNEGO attempt, so if you need an additional one it can be done in the background on click of "login" link by defining this additional IDP here |
| KEYCLOAK_BACKEND_SERVER_URL | Scheme, host name, and port of Keycloak used by the user authorization cache service (may differ from KEYCLOAK_FRONTEND_SERVER_URL in proxy situations or with Docker) |
| KEYCLOAK_FRONTEND_SERVER_URL | Optional (Unless SU_IDP or HEADLESS_IDP) - Scheme, host name, and port of public Keycloak (may differ from confidential host:port in proxy situations (often Docker with localhost) |
| KEYCLOAK_REALM | Keycloak realm name to use with background IDP and SU and also with user authorization cache service |
| KEYCLOAK_RESOURCE | Keycloak resource to use with user authorization cache service |
| KEYCLOAK_SECRET | Keycloak secret to use with user authorization cache service |
| LOGBOOK_SERVER_URL | Scheme, host name and port of Jefferson Lab logbook server |
| FRONTEND_SERVER_URL | Scheme, host name, and port of outermost proxy host (for use in hyperlinks in generated emails and log entries) |
| PUPPET_SHOW_SERVER_URL | Scheme, host name, and port of Puppet Show server used by the html-to-image and html-to-pdf app relative path Convert service |
| RESOURCE_LOCATION | Optional - If undefined then defaults to LOCAL (serve files locally). Other option is CDN, which looks for minified/combined files on shared Content Delivery Network (CDN) server - Nice for when multiple apps use same resources to have warm cache. |
| SERVER_MESSAGE | Optional - Banner message at top of all pages - useful to tag test environment or provide global announcement |
At runtime smoothness apps use the following per-app namespaced environment variables (prefix set in web.xml context init param):
| Name | Description |
|---|---|
| (PREFIX)_FEEDBACK_SENDER_ADDRESS | Email address to set as the sender (separate from the "from" field) when a feedback message is submitted by a user |
| (PREFIX)_FEEDBACK_TO_ADDRESS_CSV | Comma Separated Values of email addresses to notify when a feedback message is submitted by a user |
| (PREFIX)_CONTENT_CONTACT | Optional - Person to contact for help with app content |
| (PREFIX)_TECHNICAL_CONTACT | Optional - Person to contact for help with app not working as expected |
| (PREFIX)_DOC_CSV | Optional - Comma separated doc items. Doc item is a URL and Label separated with the pipe symbol |
This project is built with Java 17 (compiled to Java 11 bytecode), and uses the Gradle 7 build tool to automatically download dependencies and build the project from source:
git clone https://github.com/JeffersonLab/smoothness
cd smoothness
gradlew build
Note: If you do not already have Gradle installed, it will be installed automatically by the wrapper script included in the source
Note for JLab On-Site Users: Jefferson Lab has an intercepting proxy
Note: The dependency jars are expected to be installed into Wildfly directly to keep the application war size small and reuse components. See provided-setup.sh and docker-server.env.
See: Docker Development Quick Reference
In order to iterate rapidly when making changes it's often useful to run the app directly on the local workstation, perhaps leveraging an IDE. In this scenario run the service dependencies with:
docker compose -f deps.yaml up
Note: The local install of Wildfly should be configured to proxy connections to services via localhost and therefore the environment variables should contain:
KEYCLOAK_BACKEND_SERVER_URL=http://localhost:8081
FRONTEND_SERVER_URL=https://localhost:8443
Further, the local DataSource must also leverage localhost port forwarding so the standalone.xml connection-url field should be: jdbc:oracle:thin:@//localhost:1521/xepdb1.
The server and app setup scripts can be used to setup a local instance of Wildfly.
Since this is a monorepo there are actually two projects: the weblib and the demo of the weblib. Further, both projects have a Java distributable (demo war and weblib jar), plus there is a demo Docker image.
Dependencies (libraries) generally should be installed directly into Wildfly as opposed to being bundled inside a war file, but the smoothness weblib itself should not and must be packaged inside the war file of each app using the lib. This is necessary as the smoothness weblib is incompatible as a JBoss Module, plus this bundling makes development of the lib easier as it allows iteration without constantly updating weblib code installed in Wildfly. Since the demo has a dependency on the weblib, either all artifacts needed for both subprojects need to tagged together, else two separate releases would be needed as a release corresponds to a git tag and Docker images are built using the Git tag context. We use a shared release.
- During development the build is run locally to ensure everything is working. You can use deps.yaml Docker Compose in concert with a local Wildfly instance to quickly iterate.
- To confirm the new demo Docker image is good, run the docker build and test locally:
docker compose -f build.yaml build demo --no-cache --progress=plain
...
docker compose -f build.yaml up
- Bump the version number in the VERSION file and commit and push to GitHub (using Semantic Versioning).
- 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. A war file artifact is attached to the release.
- The Publish artifact GitHub Action to create a deployment artifact on maven central.
- The Publish docs GitHub Action to create javadocs.
- The Publish docker image GitHub Action to create a new demo Docker image, and bump the compose.override.yaml to use the new image.
- The Deploy to JLab GitHub Action to deploy to the JLab test environment.
- Copy updated minified JS and CSS to any CDN as needed.
At JLab this app is found at ace.jlab.org/smoothness-demo and internally at acctest.acc.jlab.org/smoothness-demo. However, those servers are proxies for wildfly5.acc.jlab.org and wildflytest5.acc.jlab.org respectively. A deploy script is provided to automate wget and deploy. Example:
/root/setup/deploy.sh smoothness-demo v1.2.3
JLab Internal Docs: InstallGuideWildflyRHEL9