locusworks/portal-webapp
3
0 Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Updated tex files with latest information about the program

Browse Source
This commit is contained in:
iparenteau committed 2026-09-04 17:15:15 -05:00
1 parent f0716b0073
commit 0f8db48407
91 files changed
+489 -822
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/src/Development.tex
+49 -99
View File
@@ -1,123 +1,73 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE : Development.tex
% SUBJECT : Document describing development issues in Patch Repository.
% AUTHOR : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Development}
\label{development}
This chapter describes how to develop, and build the \portal system. The audience for this chapter is \portal developers.
This chapter describes the current Maven and Angular development workflow.
\section{Setup}
\label{dev-setup}
This section describes how to setup the \portal environment to be able to build the web application
Install JDK \JavaVersion\ and Maven 3.9.x. Jenkins uses Maven \MavenVersion. Add your SSH public key to your Gitea account, then run:
\begin{lstlisting}
git clone ssh://gitea@gitea.locusworks.net:7999/locusworks/portal-webapp.git
cd portal-webapp
mvn -v
mvn clean install
java -jar portal_webapp/target/portal_webapp-1.0.0-RELEASE.jar
\end{lstlisting}
Use the corresponding JAR filename if the project version has changed. Open \url{http://localhost:8080/portal/}; the entry page redirects to \filename{/portal/client/}, which uses hash-based routing.
\subsection{Development}
\begin{enumerate}
\item Clone the repository from BigMac
\begin{enumerate}
\item Add developers public key to BigMac account
\item Clone the repository \newline
\command{git clone ``ssh://git@bigmac.locusworks.net:8010/saipt/portal-webapp.git''}
\end{enumerate}
\item Create/Edit \command{settings.xml} in the \command{.m2} located in the home directory. See Subsection~\ref{settings.xml}
\item \portal requires \command{locusworks-commons} library to be built prior to building the web application. See Subsection~\ref{locusworks-commons}
\item Change directories into the project and run \command{mvn clean install antrun:run@warcopy}. This could take some time to download the required libraries.
\item Start the tomcat server and navigate to \command{http://localhost:8080/portal/} to make sure the server comes up
\end{enumerate}
The build installs frontend dependencies from the lockfile, builds and tests the client, compiles and tests the Java modules, runs dependency checks, and installs the packaged artifacts locally. It does not publish to Nexus or start an application server.
\subsection{Locusworks Commons}
\label{locusworks-commons}
Locusworks Commons is a common library of functions that other java applications can take advantage of.
The parent POM references Locusworks Commons \locusworksCommonsVersion\ and Application Logger 2.0.2-RELEASE. Maven resolves the published artifacts from Locusworks Nexus. A separate source checkout is only needed when developing those libraries themselves.
To checkout the library:\newline
\command{git clone ``ssh://git@bigmac.locusworks.net:8010/saipt/locusworks-commons.git''}
To build:\newline
\command{mvn clean install}
Note: \command{locusworks-commons} needs to be built prior to building the main application
\section{npm}
\label{npm}
npm installs the client-side dependencies declared in \command{package.json}.
From \command{portal\_client}, run \command{npm install} to install dependencies. To add a client-side library, run \command{npm install <package-name> --save}.
Next include the appropriate file into the \command{assets.js} file inside \command{portal\_client} to make sure it will be injected into the \command{index.html} file during compile time.
The \command{assets.js} file specifies all the vendor libraries that have to be included in the client html during build.
\section{Grunt}
\label{grunt}
Grunt\cite{grunt} allows for live reloading of client code to reflect any changes done on the client javascript/html pages during development. This requires the application to be running
locally on port 8080. Grunt also has to be installed locally and on the users path to be able to execute properly.
To execute Grunt change directories to the client project \filename{portal\_client} and issue the command \command{grunt onlyServe}. This will start the proxy server and open a web browser
that points to the proxy process on \command{127.0.0.1 port 9000}. Navigating to this url will load content from the local client content and not from the deployed client content. Making
changes and saving the client code will automatically cause the site to refresh and will reflect the changes.
The deployed code is all minified and any javascript errors would not be easily debugged. Running grunt makes it reference the source material and allows the developer to debug the
javascript that was causing the errors and also show up properly in the development console within the browser.
\section{Settings.xml}
\section{Maven Settings}
\label{settings.xml}
Settings.xml allows for user specific keys to build the application. Each developer needs this file to build the application property
Configure repository credentials, when required, in your user \filename{.m2/settings.xml}. The dependency and plugin repository uses server ID \command{locusworks-public}. Publishing uses \command{nexus-release} and \command{nexus-snapshot}. See Appendix~\ref{sample-settings.xml} for a sample. The Nexus base URL defaults to \url{https://nexus.locusworks.net} and can be overridden with \command{-Dnexus.repo=https://your-nexus-host}.
Sample \command{settings.xml} file can be found in Appendex~\ref{sample-settings.xml}
\section{npm}
\label{npm}
Maven provisions Node.js \NodeVersion\ and npm \NpmVersion. From \filename{portal\_client}, use the local tools to install the exact locked dependency tree, build, and test.
\section{IDE}
PowerShell:
\begin{lstlisting}
.\node\node.exe .\node\node_modules\npm\bin\npm-cli.js ci
.\node\node.exe .\node\node_modules\npm\bin\npm-cli.js run build
.\node\node.exe .\node\node_modules\npm\bin\npm-cli.js test
\end{lstlisting}
Linux/macOS:
\begin{lstlisting}
./node/node ./node/node_modules/npm/bin/npm-cli.js ci
./node/node ./node/node_modules/npm/bin/npm-cli.js run build
./node/node ./node/node_modules/npm/bin/npm-cli.js test
\end{lstlisting}
With matching tools on \command{PATH}, use \command{npm ci}, \command{npm run build}, and \command{npm test}. To add or update a library, use \command{npm install <package-name>@<version>}, review the resulting changes, and commit both \filename{package.json} and \filename{package-lock.json}. Import packages in TypeScript; Angular CLI bundles the required code.
Most modern IDE's such as Eclipse, NetBeans, IntelliJ, can import existing maven projects. Once the project has been checked out, import into the IDE an existin maven project. Eclipse
allows SCM checkout directly from the IDE.
\section{Frontend Development Server}
\label{frontend-dev-server}
The \command{npm start} script runs Angular CLI's development server. There is no backend proxy configuration in this checkout: API and realtime requests expect the \filename{/portal} backend on the same origin. Use the packaged application for an integrated local run. Client output is written to \filename{portal\_client/dist} and copied into the backend JAR when it is built, so rebuild the backend after changing client assets.
\portal was developed using Eclipse \EclipseVersion\ and is the recommended IDE of choice.
\subsection{NetBeans}
\section{IDE and Database Entities}
\label{netbeans}
While the application was developed using Eclipse, the JPO\footnotemark\ classes were generated using NetBeans as they are well defined.
\footnotetext{Java Persistence Objects}
Import the root Maven project in an IDE supporting JDK \JavaVersion. The repository does not require a particular Eclipse, IntelliJ IDEA, or NetBeans version. Run or debug \command{net.locusworks.portal.PortalApplication} with the appropriate module classpath, or run the packaged JAR.
To generate the JPO objects load at least the portal\_database project into netbeans. Right click on \filename{net.locusworks.portal.database.entities} package and choose
\command{New -> Entities Classes From Database}
Database entities live in \filename{portal\_database/src/main/java}. They use Jakarta Persistence annotations. If using an IDE to generate entities, review the generated mappings and preserve repository-specific behavior; the old NetBeans 8.2 generation screenshots do not describe the current toolchain. Database schema changes belong in new Flyway migrations.
Set up the connect to connect to the portal database and choose Add All (but then remove \_flyway\_migration table) as shown in Figure~\ref{fig:netbeans-db} then click next
\section{Testing and Dependency Reports}
Run \command{mvn clean install} for the complete build. For the datasource test and its prerequisite Java modules, run \command{mvn -pl portal\_common -am test}. The datasource test uses isolated in-memory H2 with \command{portal.database.*} JVM overrides; it does not validate external MySQL. Java test results are written to each module's \filename{target/surefire-reports} directory. Frontend tests cover lazy login rendering and authentication redirects.
Dependency-Check reports are written to \filename{target/dependency-check-report.html} in the root and module directories. To enable OSS Index, configure a Maven server named \command{oss-index} with your username and API token, then run \command{mvn clean install -Dportal.ossIndexEnabled=true}.
\section{Jenkins}
The multibranch pipeline in \filename{Jenkinsfile} uses JDK \JavaVersion, Maven installation \command{maven-\MavenVersion}, and managed settings \command{locusworks-settings}. It assigns a build version, updates a shared OWASP cache, runs \command{mvn clean verify}, publishes Java test results, and archives JARs. Release branches and \command{develop} publish Maven artifacts to Nexus. Other branches only build and verify. Publishing artifacts does not restart the deployed application.
\begin{figure}[htbp]
\centering
\scalebox{0.5}{\includegraphics*{figures/netbeans-database.png}}
\caption{NetBeans Database Connection}
\label{fig:netbeans-db}
\end{figure}
\section{Changes Between Releases}
Each successful build on \command{release/**} records a release using an immutable Git tag with prefix \command{portal-release-} followed by its build version. Release notes are saved to \filename{target/release-notes.md}. The \command{Build LaTeX} stage converts them with \command{awk} into \filename{appendix/ReleaseNotes.tex} before compilation. The master document includes this generated appendix immediately after Revisions. The stage archives the PDF, Markdown, and generated TeX. The agent needs \command{awk} on its path. Local builds use a placeholder when release notes have not been generated. Notes list commit messages and hashes since the nearest earlier release tag in the current branch's history. The first recorded release includes the full history; a rebuild without new commits reports no source changes.
In the ``Entity Classes'' section, make sure generation type is set to either ``New'' or ``Recreate'' (this can be changed by choosing the \command{\ldots} below the class name).
Make sure ``Generate Named Query Annotations for Persistent Fields'' and ``Generate JAXB Annotations'' are not selected as shown in Figure~\ref{fig:netbeans-ec} then click next
\begin{figure}[htbp]
\centering
\scalebox{0.5}{\includegraphics*{figures/netbeans-entityclass.png}}
\caption{NetBeans Entity Classes}
\label{fig:netbeans-ec}
\end{figure}
\newpage
In the final window make sure the ``Collection Type'' is set to \command{java.util.list} and only ``Fully Qualified Database Table Names'' and ``Use Column Names in Relationships''
are selected as shown
in Figure~\ref{fig:netbeans-mo}.
This will generate all the JPO classes which map the database tables into java objects.
\begin{figure}[htbp]
\centering
\scalebox{0.5}{\includegraphics*{figures/netbeans-mapping.png}}
\caption{NetBeans Mapping Options}
\label{fig:netbeans-mo}
\end{figure}
The final \command{Tag release} stage pushes the tag after the build, documentation, and applicable Maven deployment succeed. Notes archived before a later failure do not mark a completed release. Jenkins needs the SSH Agent plugin, the \command{ssh-agent} executable, a trusted Git server host key, and an SCM SSH credential permitted to push tags. The helper fetches release tags and completes shallow history before comparing commits. Tag conflicts fail the build without overwriting existing remote tags.
\section{Building This Manual}
Jenkins runs the \command{Build LaTeX} stage after the application build only on branches matching \command{release/**}. PDF compilation and archiving are skipped on all other branches. The agent needs \command{pdflatex} on its path and the packages used by this manual. It compiles \filename{docs/src/portal.tex} three times, stopping on compilation errors, and writes the PDF to \filename{target/latex/portal.pdf}. The same stage archives that PDF with fingerprinting before workspace cleanup. This pipeline uses \command{pdflatex} directly; \command{latexmk} and Perl are unnecessary.
From \filename{docs/src}, run \command{pdflatex portal.tex} twice to resolve cross-references and the table of contents. This requires a LaTeX distribution with the packages listed in \filename{portal.tex}. When using a separate output and auxiliary directory, remove stale \filename{portal.aux} and \filename{portal.out} files from \filename{docs/src}; otherwise they can shadow the generated files and leave references unresolved on every pass. Keep the same output directory for subsequent passes. The Maven application build does not compile this manual.