From 87cca3b206fb9e74d86e1f99d335f12f3108bf4b Mon Sep 17 00:00:00 2001 From: Andres LeonRangel Date: Tue, 19 Dec 2023 22:50:24 +1300 Subject: [PATCH] git-cherrypick attempt update to README Signed-off-by: Andres LeonRangel --- Dockerfile | 21 ++++- README.md | 196 ++++++++++++++++++++++++++++++++--------------- build.gradle.kts | 146 +++++++++++++++++++++++++++++++++++ 3 files changed, 297 insertions(+), 66 deletions(-) create mode 100644 build.gradle.kts diff --git a/Dockerfile b/Dockerfile index 629b2f7..8af4c3d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,7 +1,22 @@ +# install Linux https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository +# Docker desktop https://docs.docker.com/desktop/install/ubuntu/ FROM tomcat:8-jdk8-corretto # https://hub.docker.com/layers/library/tomcat/7.0.109-jdk8-openjdk/images/sha256-489823486120d076cb576640c5819c6fa54948f470b46c54f02b48f462eb2c23 + +ARG APP_WAR_FILE_VERSION +ENV APP_WAR_FILE_VERSION=$APP_WAR_FILE_VERSION +ENV APP_WAR_FILE="Attendance" +ENV APP_WAR_FILE_PATH="build/libs/$APP_WAR_FILE-${APP_WAR_FILE_VERSION}" LABEL org.nz.itlatinos.image.authors="aleonrangel@outlook.co.nz" -ADD conf/tomcat-users.xml /usr/local/tomcat/conf +LABEL maintainer="andres.nz" +LABEL war.version="$APP_WAR_FILE_VERSION" +LABEL docker.image.build.command="docker build --build-arg APP_WAR_FILE_VERSION=$APP_WAR_FILE_VERSION --tag aleon1220/soa:latest ." -COPY target/AttendanceWebApp.war /usr/local/tomcat/webapps/ -LABEL maintainer="andres.nz" \ No newline at end of file +RUN printf "WAR version is $APP_WAR_FILE-$APP_WAR_FILE_VERSION" +RUN printf "Path to war file $APP_WAR_FILE_PATH" +# Tomcat Custom settings +# RUN echo ${PWD} && ls -lR # Debugging +# USER 1000 # considered permissions issue +COPY ${APP_WAR_FILE_PATH}.war /usr/local/tomcat/webapps +# COPY build/libs/AttendanceApp-0.7.2 /usr/local/tomcat/webapps/ +# https://forums.docker.com/t/docker-build-multistage-failed-to-compute-cache-key/134316/20 diff --git a/README.md b/README.md index ba0f356..e214339 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,57 @@ +- [Attendance WebApp](#attendance-webapp) + - [Introduction](#introduction) + - [GitHub Reports](#github-reports) + - [Security warnings](#security-warnings) + - [GitHub Vulnerability report](#github-vulnerability-report) + - [Attendance WebApp Architecture (re-architected)](#attendance-webapp-architecture-re-architected) + - [2018-Attendance WebApp high level Architecture](#2018-attendance-webapp-high-level-architecture) + - [Attendance WebApp UI](#attendance-webapp-ui) + - [Refer to the Wiki for details on the project](#refer-to-the-wiki-for-details-on-the-project) +- [Quickstart](#quickstart) +- [Local Setup](#local-setup) + - [Project general guidelines](#project-general-guidelines) + - [Maven Build](#maven-build) + - [Perform local testing](#perform-local-testing) + - [Gradle Test suite](#gradle-test-suite) + - [Use 1Password CLI to inject the secrets](#use-1password-cli-to-inject-the-secrets) + - [Execute the Gradle commands](#execute-the-gradle-commands) + - [Set the variables](#set-the-variables) + - [Docker Image Build](#docker-image-build) + - [Available Tomcat versions](#available-tomcat-versions) + - [Execute WebApp Container Execution](#execute-webapp-container-execution) + - [Docker execution by image version](#docker-execution-by-image-version) + - [Docker-compose](#docker-compose) + - [Editing project diagrams](#editing-project-diagrams) +- [References](#references) + # Attendance WebApp -# Introduction +## Introduction Attendance WebApp is a proof of concept to improve the way attendance is managed at AUT university. The application uses maven, J2EE, primefaces, gson. +```kotlin + maven { + url = uri("https://repository.primefaces.org") + } +``` The idea is that you have a short timeframe to submit a random generated code by the lecturer so that attendance can be registered in the system. The application is a proof of concept for Service orientation and Service interoperability in the cloud -> ## Security Warning - +## GitHub Reports +### Security warnings +> Security Warnings to check GitHub found 2 vulnerabilities on aleon1220/multi-cloud-WebApp-Attendance's default branch (2 moderate). To find out more, visit: [This project security report](https://github.com/aleon1220/multi-cloud-WebApp-Attendance/security) +### GitHub Vulnerability report +https://github.com/aleon1220/multi-cloud-WebApp-Attendance/security/dependabot ## Attendance WebApp Architecture (re-architected) -since this is a 2018 project a lot of things need to change +2018 project with a lot of things to change * Simplification of used services * Streamline app to use 100% rest and deprecate SOAP and WSDL @@ -40,99 +74,135 @@ since this is a 2018 project a lot of things need to change [95f44386]: https://github.com/aleon1220/multi-cloud-AttendWebApp/wiki/4-Architecture-and-Technical-Design "Project Wiki" -# Project general guidelines +# Quickstart +- Gradle Build Web Package +build and test the WebArchive file. Generates the .WAR file in `build/libs/*.war` +``` bash +gradle clean build --console plain --warning-mode all +``` +- Gradle Check the generated version from the build.gradle.kts +```bash +gradle getAppversion +``` +- Run WebApp +Run the tomcat server with the latest pre-built WAR web Archive file +Run from [Docker Hub](https://hub.docker.com/repository/docker/aleon1220/soa/general) +```bash +docker run -itd --publish 8080:8080 --name attendance_webapp_container aleon1220/soa:latest +``` + +# Local Setup +> Tested in Win11 with WSL, Github codespaces and Linux Ubuntu 22 + +## Project general guidelines -1. Installation process: project is Maven java project. Import in any IDE with the POM File. +1. Installation process: project a Java project JEE. Import in any IDE and build with gradle or maven. Build docker image and run 2. Software dependencies: dependencies are described in pom.xml file 3. Latest releases by using git tags 4. API references. API docs - -# Build and Test - +- Clone repo HTTPS ```bash -git clone repo -# import in IDE Eclipse suggested or use online IDE -# execute some of the unit tests -# Generate the .WAR file -mvn package -# Deploy WebArchive file in tomcat. Docker apps info below -deploy .WAR in tomcat +git clone https://github.com/aleon1220/multi-cloud-WebApp-Attendance.git ``` - -## Maven - -### Run the maven build Locally - -- build the project locally with a locally installed maven client - -> Tested in Win11 with WSL - +- Clone Repo SSH ```bash -mvn verify +git clone git@github.com:aleon1220/multi-cloud-WebApp-Attendance.git ``` +- open repo in chosen IDE +IDEs can be Eclipse, IntelliJ (suggested) or use online IDE (Github codespaces) -- Use a docker tag to select a target JDK - -> 8-jdk8-corretto +### Maven Build +> maven has been deprecated and moved to [maven](./maven) +### Perform local testing +### Gradle Test suite +#### Use 1Password CLI to inject the secrets +- as a pre-requisite you must have access to the shared vault +- login in the CLI ```bash -TOMCAT_DOCKER_TAG="8-jdk8-corretto" +# Linux Ubuntu tested 2023-12-10 +op signin ``` - -- build the container to the latest version tag - +- inject the secrets for testing Authentication property file ```bash -docker build --tag aleon1220/soa:latest . +op inject -i token_auth.properties.tpl -o token_auth.properties ``` -- Run the tomcat server with the pre-built WAR web Archive file - Use the tag latest or a particular version e.g. aleon1220/soa:v2 or aleon1220/soa:latest +- inject the secrets for Testing property file +```bash +op inject -i secrets.env.tpl -o secrets.env +``` +- inject the secrets for Testing docker-compose ```bash -docker run -itd --publish 8888:8080 --name attendance_webapp_container aleon1220/soa:latest +op inject -i .env.tpl -o .env ``` +#### Execute the Gradle commands +Should do validations +```bash +gradle check --warning-mode all +``` +#### Set the variables +#### Docker Image Build +- Build the app image with Docker. Deploy .WAR file in Tomcat refer to https://hub.docker.com/_/tomcat - -- Access container - ```bash -docker container exec -it aleon1220/soa /bin/bash +docker build --build-arg APP_WAR_FILE_VERSION=$APP_WAR_FILE_VERSION --tag aleon1220/soa:$APP_WAR_FILE_VERSION . ``` -- The URl is localhost:8888/AttendanceWebApp | [AttendanceWebApp](http://localhost:8888/AttendanceWebApp) - ---- - -## Build using maven docker container +#### Available Tomcat versions +if you need to edit the Dockerfile and upgrade the servlet container Tomcat version +- 7.0.109 = `TOMCAT_VERSION_DOCKER_TAG="7.0.109-jdk8-openjdk"` +- 9.0.78 = `TOMCAT_VERSION_DOCKER_TAG="9.0.78-jre8"` -Refer to maven docker official image https://hub.docker.com/_/maven -is best to have maven locally installed - -- Create a volume +> for particular versions check the image in Docker hub +### Execute WebApp Container Execution +#### Docker execution by image version +Test the immutable webapp from Docker ```bash -docker volume create --name maven-repo-volume +docker run -itd --publish 8080:8080 aleon1220/soa:$APP_WAR_FILE_VERSION ``` -- Docker container build using the volume above - +##### local development & executions +Test the container webapp after building the image locally ```bash -docker run -it -v maven-repo-volume:/root/.m2 maven mvn archetype:generate # will download artifacts +docker run -itd --publish 8080:8080 --name attendance_webapp_container aleon1220/soa:$APP_WAR_FILE_VERSION ``` - -- Docker container run and build using the maven image - +- Get the name of the running container +``` bash +CONTAINER_NAME=$(docker container ls --all --filter publish=8080 --format "{{.Names}}") +``` +- The URl is hostname:8080/$CONTEXT +- Get the context of the webapp ```bash -docker run -it --rm --name my-maven-project -v "$(pwd)":/usr/src/mymaven -w /usr/src/mymaven maven:3.3-jdk-8 mvn clean install +TOMCAT_URL="http://$(hostname):8080/Attendance-$APP_WAR_FILE_VERSION" +``` +- Access the Docker container via CLI +```bash +docker container exec -it $CONTAINER_NAME /bin/bash +``` +- clean up docker container environment +``` bash +docker stop $(docker ps --quiet) +docker rm $(docker container ls --all --quiet) ``` -- docker run build using bind volume mount - +#### Docker-compose +- inject the secrets for Testing docker-compose ```bash -docker run -it --name my-maven-project -v "$(pwd)":/usr/src/mymaven -w /usr/src/mymaven maven:3.3-jdk-8 mvn clean install +op inject -i .env.tpl -o .env +``` +- single variable +```bash +export LDAP_ADMIN_PASS=$(op read "op://uqbpxejq7gifvi6mg3c7xxokre/jvuj7juvlxlg7delckucvidqhi/password") ``` -## GitHub Vulnerability report +## Editing project diagrams +- go to [diagrams.net](https://app.diagrams.net/?src=about) +- open the file [project-diagrams.drawio](./project-diagrams.drawio) XML file with the diagrams +- Explore > export images to convinience and update this README -https://github.com/aleon1220/multi-cloud-WebApp-Attendance/security/dependabot +# References +- [free website templates](http://all-free-download.com/free-website-templates) \ No newline at end of file diff --git a/build.gradle.kts b/build.gradle.kts new file mode 100644 index 0000000..459d53d --- /dev/null +++ b/build.gradle.kts @@ -0,0 +1,146 @@ +import org.gradle.api.tasks.testing.logging.TestLogEvent + +plugins { + java + // id ("com.adarshr.test-logger") version "3.0.0" + // https://docs.gradle.org/7.3/dsl/org.gradle.api.tasks.bundling.War.html + war + id ("jacoco") + id("com.github.bjornvester.wsdl2java") version "2.0.2" +} + +repositories { + gradlePluginPortal() + google() + mavenCentral() +} + +dependencies { + implementation("org.primefaces.extensions:primefaces-extensions:6.0.0") + implementation("org.primefaces:primefaces:6.0") + implementation("com.sun.faces:jsf-api:2.2.12") + implementation("com.sun.faces:jsf-impl:2.2.12") + implementation("javax.json:javax.json-api:1.1") + implementation("javax.ws.rs:javax.ws.rs-api:2.1") + implementation("com.sun.jersey:jersey-client:1.19.4") + // https://github.com/google/gson library JSON serialization/deserialization + implementation("com.google.code.gson:gson:2.10.1") + // https://bitbucket.org/snakeyaml/snakeyaml/wiki/Documentation + // https://mavenlibs.com/maven/dependency/org.yaml/snakeyaml + implementation("org.yaml:snakeyaml:2.1") + implementation("org.apache.httpcomponents:httpclient:4.5.13") + implementation("org.glassfish.jersey.core:jersey-common:2.22.2") + implementation("javax.servlet:javax.servlet-api:3.1.0") + // QRFunctions + implementation("com.google.zxing:javase:3.5.1") + implementation("com.google.zxing:core:3.5.1") + // dependency below only needed if using the Java 8 version of @Generated (through "jdk8") on Java 9 or later + implementation("javax.annotation:javax.annotation-api:1.3.2") + implementation("io.github.threeten-jaxb:threeten-jaxb-core:2.1.0") // Use Java Date/Time API. Clunky GregorianCalendar class + // JUnit Jupiter API and Engine for unit testing + testImplementation("org.junit.jupiter:junit-jupiter-api:5.8.2") + testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.8.2") + testImplementation("org.junit.jupiter:junit-jupiter-api:5.7.0") + testRuntimeOnly("org.junit.jupiter:junit-jupiter-engine:5.7.0") + // Mockito for mocking in tests + testImplementation("org.mockito:mockito-core:4.5.1") + // Authentication + testImplementation("io.jsonwebtoken:jjwt:0.9.1") + // https://central.sonatype.com/artifact/com.unboundid/unboundid-ldapsdk + implementation("com.unboundid:unboundid-ldapsdk:6.0.11") +} + +group = "soa.nz.aut" +version = "0.7.3" +description = "Student Attendance WebApp" +java.sourceCompatibility = JavaVersion.VERSION_17 + +fun setWarVersion() { + // function body + project.version?.let { version -> + println("WAR Version is $version") + System.setProperty("APP_WAR_FILE_VERSION", version.toString()) + println("For local testing do APP_WAR_FILE_VERSION=" + version.toString() ) + println("Append to the .env file \n") + println("printf \"\$APP_WAR_FILE_VERSION \\n\" >> .env") + } +} + +fun getWarpackageVersion() { + // function body + project.version?.let { version -> + println("WAR Version is $version") + println("set variable with") + println("export APP_WAR_FILE_VERSION=" + version.toString()) + } +} + +tasks.register("getProjectInfo") { + description = "Obtains detailed info about the java web project" + setWarVersion() +} + +tasks.war { + archiveBaseName.set("Attendance") + webAppDirectory.set(file("src/main/webapp")) + // from("src/rootContent") // adds a file-set to the root of the archive + // webInf { from("src/additionalWebInf") } // adds a file-set to the WEB-INF dir. + // classpath(fileTree("additionalLibs")) // adds a file-set to the WEB-INF/lib dir. + // classpath(moreLibs) // adds a configuration to the WEB-INF/lib dir. + // webXml = file("src/someWeb.xml") // copies a file to WEB-INF/web.xml + doLast{ + setWarVersion() + println("WAR file version set") + } +} + +tasks { + named("jacocoTestReport") { + reports { + } + } + test { + useJUnitPlatform() + testLogging.events = setOf(TestLogEvent.FAILED, TestLogEvent.PASSED, TestLogEvent.SKIPPED) + } +} + +tasks.register("singleTestQRFunctionality") { + group = "Verification" + description = "Runs a test to create a local QR code" + filter { + includeTestsMatching("utilities.TestQRFunctions.createQRCodeLocally") + } +} + +tasks.register("mockOpenLDAP") { + description = "Runs openLDAP mock authentication testing" + group = "LDAP_Testing" + filter { + includeTestsMatching("TestLDAPAuthentication.testMockOpenLDAPAdminSearch") + } +} + +tasks.register("searchOpenLDAP") { + description = "Runs openLDAP search" + group = "LDAP_Testing" + filter { + includeTestsMatching("TestLDAPAuthentication.testOpenLDAPAdminSearch_withOpenLDAP") + } +} + +tasks.register("getAppversion") { + description = "Obtains WAR version from Gradle file" + getWarpackageVersion() +} + +wsdl2java { + // https://plugins.gradle.org/plugin/com.github.bjornvester.wsdl2java + bindingFile.set(layout.projectDirectory.file("src/main/bindings/bindings.xjb")) + + includes.set( + listOf( + "src/main/resources/wsdl/NumberConversion.wsdl" + ) + ) +} \ No newline at end of file