74 lines
7.7 KiB
TeX
74 lines
7.7 KiB
TeX
\chapter{Development}
|
|
\label{development}
|
|
|
|
This chapter describes the current Maven and Angular development workflow.
|
|
|
|
\section{Setup}
|
|
\label{dev-setup}
|
|
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.
|
|
|
|
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}
|
|
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.
|
|
|
|
\section{Maven Settings}
|
|
\label{settings.xml}
|
|
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}.
|
|
|
|
\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.
|
|
|
|
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.
|
|
|
|
\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.
|
|
|
|
\section{IDE and Database Entities}
|
|
\label{netbeans}
|
|
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.
|
|
|
|
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.
|
|
|
|
\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.
|
|
|
|
|
|
\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.
|
|
|
|
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.
|