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

Feature/doc update #3

Merged
iparenteau merged 2 commits from feature/doc_update into develop 2026-09-04 17:19:20 -05:00
Conversation 0 Commits 2 Files Changed 91
+489 -822
91 changed files with 489 additions and 822 deletions
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.gitignore
+17 -14
View File
@@ -2,15 +2,15 @@
.idea
.project
.settings
portal_client/dist/
portal_client/.angular/
portal_client/nbproject/private/
portal_client/node/
portal_client/node_modules/
portal_client/test_out/
portal_client/temp/
portal_client/dist/
portal_client/.angular/
portal_client/nbproject/private/
portal_client/node/
portal_client/node_modules/
portal_client/test_out/
portal_client/temp/
portal_webapp/.externalToolBuilders/
npm-debug.log
npm-debug.log
phantomjs
tags
*.DS_Store
@@ -22,9 +22,12 @@ tags
**/.tern-project
**/*.iml
**/git.properties
/filerepo_api/
**/*.aux
**/*.bbl
**/*.blg
**/*.log
**/*.out
/filerepo_api/
**/*.aux
**/*.bbl
**/*.blg
**/*.log
**/*.out
/.run/
/out/
*.awk
Jenkinsfile
Vendored
+34
View File
@@ -66,6 +66,30 @@ pipeline {
}
}
stage('Build LaTeX') {
when { branch pattern: 'release/**', comparator: 'GLOB' }
steps {
script {
String gitCredentials = scm.userRemoteConfigs[0].credentialsId
if (!gitCredentials) { error('Release builds require an SCM SSH credential with permission to push tags') }
sshagent(credentials: [gitCredentials]) {
sh 'mkdir -p target && sh scripts/release-notes.sh generate "$BUILD_VERSION" > target/release-notes.md'
}
}
sh 'awk -f scripts/release-notes.awk target/release-notes.md > docs/src/appendix/ReleaseNotes.tex'
dir('docs/src') {
sh '''
mkdir -p ../../target/latex
# Repeat to resolve cross-references and the table of contents.
for pass in 1 2 3; do
pdflatex -file-line-error -interaction=nonstopmode -halt-on-error -output-directory=../../target/latex portal.tex
done
'''
}
archiveArtifacts artifacts: 'target/latex/portal.pdf,target/release-notes.md,docs/src/appendix/ReleaseNotes.tex', fingerprint: true
}
}
stage('Deploy') {
when { expression { env.DEPLOY_BUILD == 'true' } }
steps {
@@ -74,6 +98,16 @@ pipeline {
}
}
}
stage('Tag release') {
when { branch pattern: 'release/**', comparator: 'GLOB' }
steps {
script {
sshagent(credentials: [scm.userRemoteConfigs[0].credentialsId]) {
sh 'sh scripts/release-notes.sh publish "$BUILD_VERSION"'
}
}
}
}
}
post {
README.md
+6
View File
@@ -161,6 +161,12 @@ Supply your hostname, TLS certificates, and HTTP-to-HTTPS redirect in the surrou
[Jenkinsfile](Jenkinsfile) defines a multibranch pipeline that checks out source, assigns a build version, updates a shared OWASP cache, runs `mvn clean verify`, publishes Java test results, archives JARs, and conditionally publishes Maven artifacts to Nexus.
The `Build LaTeX` stage runs only on branches matching `release/**` and compiles `docs/src/portal.tex` with three `pdflatex` passes to resolve references and the table of contents. The agent needs `pdflatex` on `PATH` and the document's LaTeX packages installed; neither `latexmk` nor Perl is required. Compilation errors fail the stage. The same stage saves `target/latex/portal.pdf` with fingerprinting before workspace cleanup.
Every successful `release/**` build records a release with an immutable Git tag named `portal-release-${BUILD_VERSION}`. The `Build LaTeX` stage also generates and archives `target/release-notes.md`, listing commit subjects and hashes since the nearest earlier release tag reachable from the current commit. The first recorded release includes the full history; a rebuild without new commits reports no source changes. Before compiling, the same stage uses `awk` to generate `docs/src/appendix/ReleaseNotes.tex`, which `portal.tex` includes immediately after the Revisions appendix. The generated TeX is archived alongside the PDF and Markdown. Commit text is escaped for LaTeX. Local builds use a placeholder until release notes are generated. The agent needs `awk` on its path. Notes are generated from Git history, so their detail depends on the commit messages.
The final `Tag release` stage pushes the tag only after the preceding build, PDF, and applicable Maven deployment stages succeed. Notes archived before a later failure are build artifacts, not a completed release marker. Failed builds do not publish a new release tag. The helper fetches release tags and expands shallow history before comparison. Jenkins needs the SSH Agent plugin, `ssh-agent` on the agent, a trusted Git server host key, and the checkout SCM SSH credential with permission to push tags. Tag conflicts fail the build; existing remote tags are never overwritten. Existing releases without this tag prefix are not comparison baselines.
| Branch | Version | Publish to Nexus |
| --- | --- | --- |
| `release/<version>` | `<version>.<build-number>-RELEASE` | Yes |
docs/src/Architecture.tex
+5 -8
View File
@@ -9,7 +9,7 @@
\label{architecture}
\section{Overview}
The overall architecture of the \portal system is shown in Figure~\ref{fig:arch-portal}. The server provides services for the entire system while the client allows users to interact with
The overall architecture of the \portal system is shown in Figure~\ref{fig:arch-portal}. The diagram shows the logical components; the client assets and embedded HTTP server are packaged together in the executable JAR. The server provides services for the entire system while the client allows users to interact with
the server to schedule tasks and checkout git repositories.
\begin{figure}[htbp]
@@ -57,9 +57,8 @@ of security against these threats. This section outlines issues involved in \por
\end{enumerate}
\end{enumerate}
Note also the data transferred between client and server is not considered confidential (with the exception of password or other authentication information). Thus encrypting the data
on the network is is not necessary.
Use HTTPS for all client traffic, including authenticated API calls and realtime connections. Session cookies and operational data must remain protected throughout the session.
There are several threats that \portal should counter. Specifically:
\begin{enumerate}
@@ -77,8 +76,6 @@ of security against these threats. This section outlines issues involved in \por
\portal can be configured to run on a single server. A typical setup is as follows:
\begin{enumerate}
\item Connections come on port 80 or 443 to either an \command{NGINX} or \command{apache} proxy
\item The proxy will direct connections to the \command{tomcat} server which hots the \portal application
\item \command{Tomcat} will interact with the \command{MySQL} database to store/retrieve information
\item The proxy will direct connections to embedded Tomcat \TomcatVersion\ in the Spring Boot \SpringBootVersion\ application
\item The application uses Hibernate and Spring Data JPA to access persistent H2 by default, or an explicitly configured external MySQL database
\end{enumerate}
docs/src/Client.tex
+7 -38
View File
@@ -10,9 +10,7 @@
\section{Requirements}
\Client\ is a set of javascript/html libraries that is executed for the user to interact with the \Server. The code uses various 3rd party libraries such as AngularJS, Angular-Material, JQuery, and inhouse
written code to render the web pages to the user. It sends REST commands to the server and waits for a response in which the information requested will be displayed. It also subscribes to the server on a
web socket to receive asynchronous messages from the server.
\Client\ is an Angular \AngularVersion\ application written in TypeScript and HTML. Angular Material provides UI components, RxJS handles asynchronous data, and application services send JSON requests to the backend. STOMP over SockJS delivers realtime messages.
\subsection{Functional Requirements}
@@ -50,8 +48,7 @@ The following is recommended for clients connecting to the server:
\item Latest Chrome, Edge or Firefox browser
\end{itemize}
The application renders best on Chrome, Edge or Firefox, and Internet Explorer should not be used. With that being said, if Internet Explorer is the only option, it should be the latest version (IE11).
It to be noted that there might be some rendering issues using IE11 as it handles rendering html/javascript differently than what is recommended by industry standards.
Use a browser supported by Angular's browser baseline, such as Chrome, Edge, Firefox, or Safari. Internet Explorer is unsupported.
\subsubsection{Security}
@@ -76,42 +73,14 @@ Data is passed between the client and server as a json formatted string.
\subsubsection{Internationalization}
\Client\ javascript/html pages are all written in US English. There are no plans to change this currently.
\Client\ TypeScript and HTML sources are all written in US English. There are no plans to change this currently.
\section{Design \& Architecture}
The application uses Angular components and services, Angular Material controls, and the Angular router. Login, dashboard, and feature pages load on demand. Authentication and permission guards control navigation; the server enforces authorization for API requests.
\Client\ makes use of various 3rd party and inhouse libraries to present the user with a rich experience. It takes advantage of current industrial standard libraries to render the pages
(AngularJS and Angular-Material).
\subsection*{AngularJS}
AngularJS is a JavaScript-based open-source front-end web application framework mainly maintained by Google and by a community of individuals and corporations to address many of the challenges encountered
in developing single-page applications. The JavaScript components complement Apache Cordova, a framework used for developing cross-platform mobile apps. It aims to simplify both the development and the
testing of such applications by providing a framework for client-side model–view–controller (MVC) and model–view–viewmodel (MVVM) architectures, along with components commonly used in rich Internet applications.
The AngularJS framework works by first reading the HTML page, which has additional custom tag attributes embedded into it. Angular interprets those attributes as directives to bind input or output parts of
the page to a model that is represented by standard JavaScript variables. The values of those JavaScript variables can be manually set within the code, or retrieved from static or dynamic JSON resources.
\subsubsection*{Angular-Material}
AngularJS Material is both a UI Component framework and a reference implementation of Google's Material Design Specification. This project provides a set of reusable, well-tested, and accessible
UI components based on Material Design.
Material Design is a specification for a unified system of visual, motion, and interaction design that adapts across different devices and different screen sizes.
The client is served at \filename{/portal/client/} and uses hash-based routing. HTTP requests and realtime connections use the same origin and the \filename{/portal} backend context.
\section{Compiling}
Angular CLI \AngularCliVersion\ compiles TypeScript and bundles the client. Maven provisions Node.js \NodeVersion\ and npm \NpmVersion, installs dependencies with \command{npm ci}, then runs the build and Vitest tests. Output from \filename{portal\_client/dist} is copied into the Spring Boot JAR under \filename{static/client}.
The client does not require compiling but instead all client code is incorperated into the final \filename{war} file by copying the contents into it during server build. The only special functionality
is during build, the client's \filename{index.html} is rewritten to included the 3rd party references located in the \filename{assets.js} file then copied over to the final product.
The initial-bundle warning budget is 500 kB. Rebuild the backend after changing client assets so the executable JAR includes the new output. See Chapter~\ref{development} for local commands and development-server limitations.
docs/src/Deployment.tex
+29 -87
View File
@@ -1,109 +1,51 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE : Deployment.tex
% SUBJECT : Document describing deployment issues in Patch Repository.
% AUTHOR : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Deployment}
\label{deployment}
This chapter describes how to build and deploy a \portal system. The audience for this chapter is \portal administrators and power users. This chapter also contains information that
may be of use to \portal developers since developers will need to configure a working \portal system for testing and development purposes.
\portal is packaged as an executable Spring Boot JAR with embedded Tomcat \TomcatVersion. The deployment host needs Java \JavaVersion\ and a writable persistent application home. New installations use H2; an external MySQL server is optional.
\portal comes packaged as a \command{war} file. It is recommended to use \command{Tomcat} to host the web application.
\section{Build and Start}
Follow Section~\ref{dev-setup} to check out and build the application with \command{mvn clean install}. Deploy the JAR from \filename{portal\_webapp/target} and run it under your service manager:
\begin{lstlisting}
java -Dportal.home=/var/lib/portal -jar portal_webapp-1.0.0-RELEASE.jar
\end{lstlisting}
Use the actual artifact version in the filename. Open \url{http://localhost:8080/portal/}. To change the HTTP port, append \command{--server.port=8081}. The frontend assumes the \filename{/portal} context path; changing it requires updating client paths and rebuilding.
\portal interacts with a \command{MySQL} database. It is important to know the root username and password to the mysql server.
Upon start up the server will copy \filename{portal.properties} to the tomcat conf directory. It might initially fail as the defaults could be incorrect
(see Appendix~\ref{sample-portal.properties}). It is possible to create this file in the conf directory before start up and change the configuration values accordingly.
The only value that should need changing is the MySQL root password. See Subsection~\ref{mysql-root-password} to encrypt the root password
\section{Checking out and building web application}
Remote into the web server that is going to host the web application. It is recommended for the server that is going to host the application should have Tomcat, MySQL and Apache or
NGINX installed as services and configured as needed. While this is recommended, those services do not have to be all on the same machine. Configuration changes will need to be made
in the \filename{settings.xml} file (see~\ref{settings.xml}) to point to the proper tomcat and mysql instances.
The following is a list of software that are required to be installed and on be on the system environment path or user path for the build process to work:
\section{Persistent Application Home}
\label{portal-home}
Portal resolves its home directory in this order:
\begin{enumerate}
\item Maven \MavenVersion\ \cite{maven}
\item Java \JavaVersion\ \cite{java}
\item Ant \AntVersion\ \cite{ant}
\end{enumerate}
\item JVM property \command{-Dportal.home=/path/to/portal}.
\item Environment variable \command{PORTAL\_HOME}.
\item \filename{\$\{user.home\}/.portal}.
\end{enumerate}
On Windows, use an absolute path such as \command{-Dportal.home=D:/Portal/data}. Place JVM properties before \command{-jar}.
Two projects need to be checkout out from the git repository. The \portal project and the locusworks-commons project.
The home directory contains \filename{portal.properties}, the AES seed, \filename{portal-loggers.properties}, logs, temporary key files, and the default H2 database under \filename{data/}. Preserve this directory when replacing the JAR. Encrypted configuration depends on the AES seed, so back them up together.
Section~\ref{dev-setup} describes how to checkout the \portal project
The bundled \filename{portal.properties} initializes and reconciles persistent Portal settings. Spring Boot's \filename{application.properties} configures the context path, session timeout, multipart limits, and JPA behavior. See Appendix~\ref{sample-portal.properties}.
Section~\ref{locusworks-commons} descrives how to checkout and build the \command{locusworks-commons} library. This library is needed to build the main web application
\section{Database Configuration}
New installations default to \command{dbType=h2}, using persistent H2 \HtwoVersion\ in MySQL compatibility mode. Existing installations retain their configured database type. H2 uses \command{h2Url}, \command{h2Username}, and \command{h2Password}.
To build the project issue the command \command{mvn clean install antrun:run@warcopy} (if tomcat is not running) or \command{mvn clean install tomcat7:redeploy}
(if tomcat is currently running). This might take awhile as it will download the required libraries from the internet and deploy the war file to the tomcat server.
For external MySQL Server \MySQLVersion, set \command{dbType=mysql} and configure \command{dbHost}, \command{dbPort}, \command{dbUsername}, \command{dbPassword}, \command{dbRootUser}, and \command{dbRootPassword}. Connector/J \MySQLConnectorVersion\ is bundled in the application. Runtime Flyway migrations use the root connection; normal application access uses the application connection.
Once the build has completed and deployed verify in the logs the application has come up with no errors. The log files can be found in the tomcat home directory under
\filename{logs/portal.out}
\section{Encrypted MySQL Root Password}
\subsection{Encrypted Database Passwords}
\label{mysql-root-password}
To encrypted the mysql root password first checkout and compile the \command{locusworks-commons} library (See section~\ref{locusworks-commons} to perform the task).
Once the commons library has been downloaded and installed perform the following.
\begin{legal}
\item Navigate to the \command{.m2} directory located in the home directory
\item Navigate to \filename{repository/net/locusworks/locusworks-commons/\locusworksCommonsVersion}
\item Execute the following command\newline
\command{java -cp locusworks-commons-\locusworksCommonsVersion.jar net.locusworks.commons.crypto.AES <root-password>}\newline
Where ``root-password'' is the MySQL root password
\end{legal}
Once the properties file has been modified/created, start tomcat and the application should start up as normal.
Nonblank database password values in \filename{portal.properties} are read as encrypted values. Use Portal's configuration facilities to save encrypted credentials with the installation's AES seed. Do not substitute plaintext passwords into the persistent file. Restart the application after changing database configuration.
\section{Seed File}
\label{seed-file}
The \command{aesSeedFile} setting identifies the seed used for encrypted credentials and configuration. Its default location is \filename{\$\{portal.home\}/portal.tomcat}; this filename does not require an external Tomcat installation. Restrict access to the service account and preserve the seed with the database and configuration backups. Use the application's seed-change operation to re-encrypt stored values when rotating the seed (Section~\ref{aesSeed}). See Appendix~\ref{sample-seed-file}.
All protected data such as passwords and private keys are encrypted using AES. To increase security, the AES key relies on a seed\footnotemark\
file (see Appendex~\ref{sample-seed-file}). This file is loaded into java's \filename{SecureRandom} class to generate the AES key.
The \filename{portal.properties} (see Appendex~\ref{sample-portal.properties}) specifies where this seed file is located. This file should be in a protected area with strict access.
During the course of operations it might be necessary for the seed file to be changed. This can be done in the application provided the user has the proper permissions to do so
(See Chapter~\ref{aesSeed}). The process will update the seed file and all protected data using the new seed.
Some legacy operating systems do not support setting seeds within a random number generator such as \filename{SecureRandom}; therefore, legacy systems running \portal will fall back
to using the key defined within the code itself.
This can pose a security so it is advise to upgrade the server in which the application runs on to a newer operating system.
\footnotetext{A seed is a number or vector used to initialize a pseudorandom number generator. It will generate the same output every time if the same seed is used}
\section{Configuring Tomcat}
\section{Reverse Proxy}
\label{conf-tomcat}
Tomcat cannot run on port 80 or 443 unless it is running as root which is not ideal. It is suggested to use a proxy service like \command{NGINX} or \command{Apache} to proxy 80 or 443
traffic to redirect to tomcat.
Place NGINX or Apache in front of embedded Tomcat to terminate HTTPS and forward \filename{/portal/} to port 8080. Preserve the context path and configure WebSocket upgrade forwarding for realtime connections. Match proxy upload limits to the application's default 10 MB limit.
\subsection{NGINX}
NGINX can be configured to proxy 80 or 443 traffic to the tomcat server to host up the content. It can also be used to store the SSL/TLS certificates for https
\begin{enumerate}
\item In the default \command{/etc/nginx/conf.d} directory add a file called \filename{portal.conf}
\item Populate it with the values that can be found in Appendix~\ref{sample-nginx.conf}
\item Save the file
\item Modify \filename{/etc/nginx.conf}
\item In the http section of the conf file add \command{include /etc/nginx/conf.d/portal.conf}
\item Restart NGINX
\item Navigate to the url. It should redirect to 443 and serve up the application content
\end{enumerate}
Put the map in the NGINX \command{http} context and the location in your site's HTTPS server block. Appendix~\ref{sample-nginx.conf} provides the forwarding directives. Supply your hostname, certificates, and HTTP-to-HTTPS redirect in the surrounding site configuration.
\subsection{Apache}
Like NGINX apache can also be configured to proxy and or 443 traffic to the tomcat server and be used to store the SSL/TLS certificates.
\begin{enumerate}
\item In the default \command{/etc/apache2/} directory add a file called \filename{httpd.conf}
\item Populate it with the values that can be found in Appendix~\ref{sample-httpd.conf}
\item Save the file
\item Restart Apache (httpd)
\item Navigate to the url. It should redirect to 443 and serve up the application content
\end{enumerate}
Enable \command{mod\_proxy}, \command{mod\_proxy\_http}, and the TLS modules. Configure HTTP and WebSocket forwarding as shown in Appendix~\ref{sample-httpd.conf}, along with the site's certificates and redirect.
\section{Deployment Helper}
\filename{scripts/deploy-server.sh} copies the built JAR to \filename{deploy/portal.jar} by default. \command{PORTAL\_DEPLOY\_DIR} changes the destination; \command{PORTAL\_SERVICE} requests a systemd service restart after copying. In this helper, \command{PORTAL\_HOME} means the source checkout. Set the runtime data directory with \command{-Dportal.home} in the Java service command to keep the two locations distinct.
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.
docs/src/Introduction.tex
+1 -1
View File
@@ -18,7 +18,7 @@ to be updated before local execution can be performed.
\begin{enumerate}
\item \bold{\Client}
The client (written in javascript and html) is used by the user to create scheduled tasks, git repositories and general configuration of the \portal.
The client (written in TypeScript and HTML using Angular \AngularVersion) is used by the user to create scheduled tasks, git repositories and general configuration of the \portal.
\item \bold{\Server}
The server (written in Java v\JavaVersion) manages the activity of the entire \portal system.
\end{enumerate}
docs/src/Server.tex
+8 -28
View File
@@ -62,8 +62,8 @@ Currently there is no statistics tracking done by the \Server. It is a possiblit
\Server\ is written in Java and does not depend on a certain operating system or operatying system functions. IT will run on any platform that meets the following requirements:
\begin{enumerate}
\item Supports Java \JavaVersion
\item Supports MySQL \MySQLVersion\ (only if mysql is to be ran on the same server as the application)
\item Supports Tomcat \TomcatVersion
\item Provides writable storage for persistent H2 \HtwoVersion\ or access to external MySQL Server \MySQLVersion
\item Runs the executable Spring Boot \SpringBootVersion\ JAR with embedded Tomcat \TomcatVersion
\end{enumerate}
\subsubsection{Performance}
@@ -71,7 +71,7 @@ Beceause slow performance on the host server does impact the performance, \Serve
\begin{itemize}
\item 16 GB of RAM
\item Dual Core CPU running at 2 GHZ or greater
\item 8 GB of RAM allocated to the Tomcat Service
\item 8 GB of RAM allocated to the Portal Java process
\item 25 GB of hard drive space.
\end{itemize}
@@ -81,12 +81,9 @@ Beceause slow performance on the host server does impact the performance, \Serve
The main server acts as the central connection point for every client, including the API and custom scripts, and most actions require authentication from each of these clients; therefore, security in \Server\
is a high priority.
Every client must authenticate with \Server. Once authenticated, actions from the client are generally considered to be non-sensitive, so SSL is not necessary once a session has been established. It is
recommended to either configure tomcat or the proxy service to use SSL/TLS to encrypt the web traffic between the client and server.
Protected API operations require an authenticated session and the appropriate permissions. Configure HTTPS at the reverse proxy for the entire session, including realtime traffic.
Passwords will be stored as a salted hash in a MySQL database column. Once \Server\ receives the password from the client, it performs a SHA-1 hash with salt on it. Since the hash is considered irreversible,
it would be impossible to log in using that hash if one were somehow able to steal it. The database should be on an the same machine or on an isolated network with no access allowed except for the server, so
packet sniffing efforts are not likely to produce results.
User passwords are stored as hashes using the Locusworks \command{HashSalt} library. Database credentials and other recoverable secrets use the application's encryption service. Restrict database and application-home access to the service account and authorized administrators.
\subsubsection{User Characteristics}
@@ -120,25 +117,8 @@ The \Server\ can handle serveral different types of clients and all clients wish
The server is the only connection point that will pass information back to the client.
\section{Compiling}
Run \command{mvn clean install} from the repository root with JDK \JavaVersion. Maven compiles the Java sources, runs tests, resolves dependencies, and packages \filename{portal\_webapp/target/portal\_webapp-1.0.0-RELEASE.jar}. Use the corresponding filename when the project version changes.
\Server\ is written in Java, which is a compiled language. Java files (\filename{*.java}) are compiled to \filename{*.class}. Any errors during compile time will cause the overall build to fail.
Even with a successful build, it could still potentially fail to run. The only way to test if the program will successfully run is to provide 100\% coverage via unit testing.
\footnote{Please see the section on testing.}
Eclipse's Java EE plugin is used to develop the JAVA code. Projects can be imported to Eclipse and executed from there. The program is compiled into a \filename{.war} file and cannot be directly ran from Eclipse.
It is possible to configure Eclipse to attach to the tomcat instance and control the instance from there which will cause the program to start and stop.
To compile and copy the \filename{war} file to the tomcat directory when the tomcat instance is not running perform the following commands (provided proper permissions to copy the file to the tomcat directory):
\newline
\command{mvn clean install antrun:run@warcopy}
To compile and redeploy the \filename{war} file to tomcat when tomcat is running perform the follow commands (provided the manager-script role as been assigned and specified)\newline
\command{mvn clean install tomcat7:redeploy}
\newline
All 3rd party JAVA libraries will be downloaded and incorporated into the build. There is no need to manually download the 3rd party libraries.
Start the application with \command{java -jar <path-to-jar>}. Spring Boot starts embedded Tomcat and serves both the API and the compiled Angular client. Configure the persistent application home as described in Section~\ref{portal-home}. The application can also be run or debugged from an IDE through \command{net.locusworks.portal.PortalApplication}.
A successful build verifies compilation and the available tests; integration testing is still needed for deployment-specific databases, remote scripts, mail, and proxy configuration.
docs/src/ToolsLibraries.tex
+61 -224
View File
@@ -1,244 +1,81 @@
\chapter{Tools \& Libraries}
\label{toolslibraries}
This chapter describes the tools and libraries used in the \portal development environment. Both where to get the necessary components and how to set them up are covered here.
This chapter is only of interest to \portal developers. If you are a \portal player or administrator you do not need to read this chapter. Instead the details for setting up the
components of a working \portal system are described in Chapter~\ref{deployment} on Deployment.
This chapter describes the tools and libraries configured for \portal. Versions come from the root and module \filename{pom.xml} files, the Spring Boot dependency BOM, \filename{portal\_client/package-lock.json}, and \filename{Jenkinsfile}. The npm lockfile records installed versions; \filename{package.json} declares the permitted ranges. Update this chapter and \filename{macros.tex} when those inputs change.
The following list reflects the tools and libraries used by the \portal developers.
\section{Build and Runtime Versions}
\begin{center}
\begin{tabular}{|L{0.39\textwidth}|L{0.49\textwidth}|}
\hline
\bold{Component} & \bold{Configured version} \\ \hline
Java & \JavaVersion \\ \hline
Maven & 3.9.x; Jenkins uses \MavenVersion \\ \hline
Spring Boot & \SpringBootVersion \\ \hline
Spring Framework & \SpringVersion (Boot-managed) \\ \hline
Embedded Tomcat & \TomcatVersion \\ \hline
Hibernate ORM & \HibernateVersion (Boot-managed) \\ \hline
Quartz Scheduler & \QuartzVersion (Boot-managed) \\ \hline
H2 database & \HtwoVersion \\ \hline
MySQL Connector/J & \MySQLConnectorVersion \\ \hline
External MySQL Server & \MySQLVersion \\ \hline
Flyway core and MySQL support & \FlywayVersion \\ \hline
JGit and JGit SSH integration & \JGitVersion \\ \hline
JSch (mwiede fork) & \JSchVersion \\ \hline
Locusworks Commons & \locusworksCommonsVersion \\ \hline
Application Logger & 2.0.2-RELEASE \\ \hline
\end{tabular}
\end{center}
\begin{itemize}
\item Eclipse \EclipseVersion
\item NetBeans \NetBeansVersion
\item Java \JavaVersion
\item Maven \MavenVersion
\item Ant \AntVersion
\item AngularJs \AngularJsVersion
\item Spring \SpringVersion
\item Hibernate \HibernateVersion
\item Quartz \QuartzVerson
\item JSch \JSchVersion
\item JGit \JGitVersion
\item Node.js \NodeVersion
\item npm \NpmVersion
\item Flyway \FlywayVersion
\item Tomcat \TomcatVersion
\end{itemize}
\section{Java and Maven}
The backend compiles with Java release \JavaVersion. Run \command{mvn -v} to confirm Maven is using the intended JDK. Maven resolves Java dependencies from its local repository and the configured remote repositories, including Locusworks Nexus. A separate build of Locusworks Commons is unnecessary when its published artifacts are available.
\section{Eclipse}
Eclipse\cite{eclipse} provides IDEs and platforms for nearly every language and architecture such as Java, C/C++, JavaScript and PHP IDEs. It is built on extensible platforms for
creating desktop, Web and cloud IDEs. These platforms deliver the most extensive collection of add-on tools available for software developers.
Run \command{mvn clean install} from the repository root. The reactor builds the Angular client and Java modules, runs tests and dependency checks, and packages the executable Spring Boot JAR. See Chapter~\ref{development} for setup and Chapter~\ref{deployment} for runtime configuration.
The \portal uses Eclipse freely to develop both the client and server side code. Eclipse is not needed to build the application. The offical version of Eclipse used by the \portal
project is \EclipseVersion. Other nearby versions are likely to work as long as it supports Java \JavaVersion
An IDE with Java \JavaVersion, Maven, and TypeScript support can import the project. IntelliJ IDEA, Eclipse, or Apache NetBeans may be used; the build does not pin or require an IDE version. A standalone Ant installation is unnecessary. The database module retains Maven AntRun 3.2.0 configuration for optional entity-source cleanup.
\section{NetBeans}
NetBeans\cite{netbeans} is an integrated development environment (IDE) for Java. NetBeans allows applications to be developed from a set of modular software components called modules.
NetBeans runs on Microsoft Windows, macOS, Linux and Solaris. In addition to Java development, it has extensions for other languages like PHP, C, C++ and HTML5, Javadoc and Javascript.
Applications based on NetBeans, including the NetBeans IDE, can be extended by third party developers.
\section{Angular and Frontend Tools}
\begin{center}
\begin{tabular}{|L{0.39\textwidth}|L{0.49\textwidth}|}
\hline
\bold{Component} & \bold{Configured or locked version} \\ \hline
Angular, Material and CDK & \AngularVersion \\ \hline
Angular CLI and build tools & \AngularCliVersion \\ \hline
Node.js & \NodeVersion \\ \hline
npm & \NpmVersion \\ \hline
TypeScript & 6.0.3 \\ \hline
RxJS & 7.8.2 \\ \hline
tslib & 2.8.1 \\ \hline
STOMP client & 7.3.0 \\ \hline
SockJS client & 1.6.1 \\ \hline
Vitest & 4.1.11 \\ \hline
jsdom & 28.1.0 \\ \hline
\end{tabular}
\end{center}
The \portal uses NetBeans to generate the database entity classes for use as it is more robust than what Eclipse provides. See Chapter~\ref{development} section~\ref{netbeans} for
more information
The client uses Angular components, TypeScript, Angular Material, and RxJS. Angular CLI compiles and bundles the application. STOMP over SockJS carries realtime messages. Node.js is a build tool; the deployed application serves the generated assets through Spring Boot.
\section{Java}
Java is the language the server is written in \cite{java}.
\portal uses extensive features that are provided in version \JavaVersion, therefore; previous versions of java will not be able to compile the server code.
\section{Maven}
Maven is utilized for the build process \cite{maven}. It dynamically downloads the required libraries as specified in the \filename{pom.xml}
files as to reduce the size of the overall projects. The downloaded libraries are stored within the users home directory under \filename{.m2/repository}.
First maven will look inside the local repository for the required library and if its not found, it will download it from the internet automatically. With that being said,
an active internet connection is required to build the web application for the first time. It is possible to configure the \filename{pom.xml} files for offline builds but requires
the libraries to be pre staged in the local repository or a service such as Nexus.
To build the web application, be in the root project folder and issue the commaond \command{mvn install}. This will start the download process and run through various tasks to build
and verify the application. If any part of the process fails to complete (such as a failed java compile or invalid javascript) the build will be terminated and will not continue until
the errors are corrected.
The \portal utilizes Maven version \MavenVersion for its build process. It is possible to use older versions of Maven as long as it is version 3.0+
\section{Ant}
Ant\cite{ant} is only utilized to copy the war file to the tomcat directory if tomcat is not currently running. The maven command \command{antrun:run@warcopy} is the command that will
invoke the ant process. \portal utilizes ant version \AntVersion but older versions of Ant will work since the process of copying files has not changed
\section{AngularJs}
AngularJs\cite{angularjs} is extensively used inside the client html code along with various other 3rd party javascript libraries. The list of 3rd party libraries used in the client
can be found in \filename{assets.js}. It is not necessary to download the AngularJs library as it will be downloaded automatically along with the other vendor libraries during the build
process. npm is utilized to do this task and place references to the files inside the \filename{index.html} during build. AngularJs is specifically called out because of how much it does
inside the client and developers should be familiar with it. \portal utlizes version \AngularJsVersion of AngularJs as specified in the \filename{package.json} file.
\section{Spring}
Spring Framework is the workhorse library of the server\cite{spring}. It drives every aspect of the server, from client authentication, page permissions and database transactions.
It is responsible for converting json strings passed from the client to java objects in which can be utilized in the spring services. Spring operates on the Model View Controller aspect
(MVC) in which the client requests information and spring returns the model to be displayed on the client page.
The typical workflow for spring can be shown in Figure~\ref{fig:spring-flow}
\begin{figure}[htbp]
\centering
\scalebox{0.6}{\includegraphics*{figures/spring-flow.png}}
\caption{Spring Workflow}
\label{fig:spring-flow}
\end{figure}
Spring security is utilized to make sure users do not access portions of the website they are not permitted to view. This is done through permission rules setup in the code and through
an authorization token which is assigned to the user during login. The authentication token tells the security provider which part of the website the user has access to.
The authentication token is populated with information that is retrieved from the permissions tables based on the users group permissions.
Spring websocket is utilized for the server to pass information back to the client asynchronously. Every time a user logins in they are automatically subscribed to the system websocket
channel and their own private channel so the user can receive personal websocket messages and system wide websocket messages. This allows for the client to update the users screen when
other users change something on the website. Without websockets the user would not know what has changed by other users unless they refresh their browser. During login, the website
checks to see if websockets is allowed (some web site providers might block websockets). If the check passes normal processes can continue. If it fails, the site will fall back into a
degredated state in which the user will not be able to get all the changes as specified above.
Spring CRUD Repository is utilized for querying the database. Developers do not need to worry about creating SQL statements as the repository will take care of that for them.
It allows for create, read, update, and delete operations on the table the repository references. This is done through JPQL (java persistence query language) and Spring annotations.
Developers should consult the Spring JPA guide if more spring query methods are needed during development. The guide can be found at
\url{https://docs.spring.io/spring-data/jpa/docs/current/reference/html/}
\portal utilizes Spring Framework version \SpringVersion. The developer does not need to worry about downloading this library is it will automatically be downloaded through maven during
build time.
\section{Hibernate}
Hibernate ORM\cite{hibernate} enables developers to more easily write applications whose data outlives the application process. As an Object/Relational Mapping (ORM) framework,
Hibernate is concerned with data persistence as it applies to relational databases (via JDBC). Hibernate maps database tables to Java objects called Java Persistence Objects (JPO).
This allows developers to create normal objects and act on them like a regular object but the changes will then persist to the database once the object has been saved. \portal utilizes
Hibernate through the use of Spring which uses Hibernate in the background for persistence. The JPO objects are also referenced in the Spring CRUD Repositories. These objects are the
objects the developer will use when doing CRUD operations (Create/Read/Update/Delete).
\portal utilizes Hibernate ORM version \HibernateVersion. The developer does not need to worry about downloading this library is it will automatically be downloaded through maven
during build time.
\section{Quartz Scheduler}
Quartz Scheduler\cite{quartz} is a richly featured, open source job scheduling library that can be integrated within virtually any Java application - from the smallest stand-alone
application to the largest e-commerce system. Quartz can be used to create simple or complex schedules for executing tens, hundreds, or even tens-of-thousands of jobs; jobs whose tasks
are defined as standard Java components that may execute virtually anything you may program them to do. The Quartz Scheduler includes many enterprise-class features, such as support for
JTA transactions and clustering.
Quartz is freely usable, licensed under the Apache 2.0 license.
Sample uses of job scheduling with Quartz:
\begin{itemize}
\item \bold{Driving Process Workflow:} As a new order is initially placed, schedule a Job to fire in exactly 2 hours, that will check the status of that order, and trigger a
warning notification if an order confirmation message has not yet been received for the order, as well as changing the order's status to ``awaiting intervention''.
\item \bold{System Maintenance:} Schedule a job to dump the contents of a database into an XML file every business day (all weekdays except holidays) at 11:30 PM.
\item Providing reminder services within an application.
\end{itemize}
\portal utilizes Quartz Scheduler version \QuartzVerson to schedule all the tasks to be completed. The developer does not need to worry about downloading this library is it will automatically be downloaded through maven
during build time.
\section{JSch}
JSch\cite{jsch} is a pure Java implementation of SSH2.
JSch allows you to connect to an sshd server and use port forwarding, X11 forwarding, file transfer, etc., and you can integrate its functionality into your own Java programs.
JSch is licensed under BSD style license.
\portal utilizes JSch version \JSchVersion. The developer does not need to worry about downloading this library is it will automatically be downloaded through maven during build time.
\section{JGit}
JGit\cite{jgit} i is a pure Java implementation of the Git version control system. Git is a distributed SCM, which means every developer has a full copy of all history of every revision
of the code, making queries against the history very fast and versatile.
\portal utilizes JGit version \JGitVersion. The developer does not need to worry about downloading this library is it will automatically be downloaded through maven during build time.
\section{Node.js}
Node.js\cite{nodejs} is a JavaScript runtime built on Chrome's V8 JavaScript engine. Node.js uses an event-driven, non-blocking I/O model that makes it lightweight and efficient.
Node.js is used to assemble and verify the client javascript and html. Node.js stores the 3rd party vendor libraries in the \filename{portal\_client} project folder under
\filename{node\_modules} folders. Typically when using Node.js, there is a Node.js server running that serves up these 3rd party libraries to the client, but \portal does not use a
node.js server to do this. Instead during compile time, the process looks at the \filename{assets.js} file to see which 3rd party libraries are needed and appends these files to the
\filename{index.html} file for refence by the client.
Once the \filename{index.html} file has been written it is copied to the rest of the client code, then utilizing \command{jshint}, the javascript is checked for any errors. It uses
'strict' checking to make sure there is proper syntax in the javascript such as semi-colons in the right place and proper closing tags. If the javascript check fails the whole build will
fail and a message will tell the developer where the javascript error is.
Node.js is also used for live reloading of the client code. Utilizing \command{grunt}, the developer can make local changes to the client code and see the changes live on the website.
This is done through a proxy service that points to the local content instead of the deployed content (as long as the deployed content is on the same machine as the developer is on).
This allows the developer to make changes and not have to rebuild the whole application to see the client side changes (See Section~\ref{grunt} for more details).
\portal utilizes version \NodeVersion\ of Node.js. It is possible to use older versions of Node.js but it not recommended for security concerns.
\section{npm}
\section{Node.js and npm}
\label{npm2}
npm is the package manager used to download third-party JavaScript libraries declared in \filename{package.json}. Packages are installed in
\filename{portal\_client/node\_modules}.
Frontend Maven Plugin 2.0.2 installs Node.js \NodeVersion\ and npm \NpmVersion\ into \filename{portal\_client/node}. Maven runs \command{npm ci}, \command{npm run build}, and \command{npm test}. A global Node.js or npm installation is unnecessary for Maven builds.
During build time, Maven downloads Node.js and npm locally, then installs the exact dependency tree recorded in \filename{package-lock.json}.
Commit both npm manifests when changing dependencies. The \command{allowScripts} entries approve specific native build helpers and must be reviewed when those packages change. SockJS is an explicitly permitted CommonJS dependency. The STOMP package uses a TypeScript mapping to its ESM entry because its browser export selects UMD. See Section~\ref{npm} for local commands.
To install dependencies, run \command{npm install}. To add a new package, run
\command{npm install <package-name> --save} and commit both package files.
\section{Spring Boot, Hibernate and Quartz}
Spring Boot \SpringBootVersion\ manages the Spring Framework, Spring Security, Spring Data JPA, Hibernate, mail, and Quartz dependencies. Spring MVC exposes the HTTP API, Spring Security maintains authenticated sessions, and Spring WebSocket provides realtime messaging. Spring Data repositories and Jakarta Persistence entities provide database access through Hibernate. Quartz schedules script jobs.
See~\ref{npm} for more details.
The root POM explicitly overrides the embedded Tomcat and MySQL driver versions. Keep related Tomcat modules aligned when updating that override. Use \command{mvn dependency:tree} to inspect the resolved Java dependencies.
\portal utilizes version \NpmVersion of npm.
\section{Databases and Flyway}
New installations use persistent H2 \HtwoVersion\ in MySQL compatibility mode. External MySQL is optional. Connector/J \MySQLConnectorVersion\ requires MySQL Server \MySQLVersion; the driver version is distinct from the database server version.
\section{Flyway}
Flyway\cite{flyway} is an open source database migration tool. It strongly favors simplicity and convention over configuration. It is based around 7 basic commands: Migrate, Clean,
Info, Validate, Undo, Baseline and Repair. Migrations can be written in SQL (database-specific syntax (such as MySQL, MSSQL, Oracle) is supported) or Java (for advanced data transformations
or dealing with LOBs). It has a Command-line client, a Java API (also works on Android) for migrating the database on application startup and a Maven plugin.
Flyway \FlywayVersion\ provides runtime schema migrations through the core and MySQL modules. The Maven Flyway configuration is under plugin management; a normal build does not automatically migrate a production database. Preserve already-applied migration scripts and add new scripts for schema changes. Back up persistent data before deploying a version with migrations.
\portal utilizes the sql syntax migration along with java implementaiton and maven plugin. It is not necessary to download flyway as maven will download the required lbraries automatically
during build time.
\section{JGit and JSch}
JGit \JGitVersion\ provides repository operations. Its SSH integration uses the maintained \command{com.github.mwiede:jsch} dependency at version \JSchVersion. Maven resolves these libraries automatically.
Flyway allows for easy database migrations between versions from older versions of the software to new version (but not from newer to older). This allows for every deployment of the web
application to perform the migraiton if needed to keep the database up to date. Flyway looks into the specified migration folder to execute migration scripts. These scripts can range from
table creation, to adding data and modifying existing tables/data. \portal utilizes Flyway at two different times. The first time is during build flyway is executed to do the required
migrations. The second time is during applcation startup to perform any migrations that need to happen on a production enviornment.
Flyway creates a table within the application table schema to keep track of which migrations have been applied. It also creates a checksum for each file. During migration,
flyway will check the checksum of the file against a database entry. If no entry exists the migration is performed and an entry is entered into the flyway table. If the checksum
matches, that migration is skipped as its already been applied. If the checksum does not match the entry, an error will be thrown and the build/startup will fail. This is to ensure that
no previous migration files have been modified. All new modifications to existing migrations should be performed in another migration script.
The flyway maven plugin allows developers to perform clean, migrate, repair, info, and validate commands. Below are the maven commands that can be executed for various flyway processes
\begin{itemize}
\item \command{mvn flyway:clean}\newline
Clean drops all objects in the configured schemas. Clean is a great help in development and test. It will effectively give you a fresh start, by wiping your configured schemas
completely clean. All objects (tables, views, procedures, \ldots) will be dropped. Needless to say: \bold{do not use against your production DB!}
\item \command{mvn flyway:migrate}\newline
Migrate migrates the schema to the latest version. Flyway will create the schema history table automatically if it doesn�t exist. Migrate is the centerpiece of the Flyway workflow.
It will scan the filesystem or your classpath for available migrations. It will compare them to the migrations that have been applied to the database. If any difference is found, it
will migrate the database to close the gap. Migrate should preferably be executed on application startup to avoid any incompatibilities between the database and the expectations
of the code.
\item \command{mvn flyway:repair}\newline
Repair repairs the schema history table. Repair is your tool to fix issues with the schema history table. It has two main uses:
\begin{itemize}
\item Remove failed migration entries (only for databases that do NOT support DDL transactions)
\item Realign the checksums, descriptions and types of the applied migrations with the ones of the available migrations
\end{itemize}
\item \command{mvn flyway:info}\newline
Info prints the details and status information about all the migrations. Info lets developers know where they stand. At a glance they will see which migrations have already been
applied, which other ones are still pending, when they were executed and whether they were successful or not.
\item \command{mvn flyway:validate}\newline
Validate validates the applied migrations against the available ones. Validate helps developers verify that the migrations applied to the database match the ones available locally.
This is very useful to detect accidental changes that may prevent you from reliably recreating the schema.
\end{itemize}
\portal utilizes version \FlywayVersion of flyway. The developer does not need to worry about downloading this library is it will automatically be downloaded through maven during build time.
\section{Tomcat}
\section{Embedded Tomcat}
\label{tomcat2}
Apache Tomcat\cite{tomcat}, often referred to as Tomcat Server, is an open-source Java Servlet Container developed by the Apache Software Foundation (ASF). Tomcat implements several
Java EE specifications including Java Servlet, JavaServer Pages (JSP), Java EL, and WebSocket, and provides a "pure Java" HTTP web server environment in which Java code can run.
Tomcat is developed and maintained by an open community of developers under the auspices of the Apache Software Foundation, released under the Apache License 2.0 license, and is
open-source software.
While \portal was developed to run on tomcat, it is possible to be ran on other servers that support \filename{.war} files such as JBOSS, TomEE, and Wildfly.
Once tomcat is installed on the host server, the only configuration that needs to change is adding a user to the manager-script role. This user should be specified in
\filename{conf/tomcat-users.xml} file under the tomcat home directory. This user and the corresponding password should be the same one as reflected in the \filename{settings.xml}
file (see Reference~\ref{sample-settings.xml} and Section~\ref{settings.xml}). This will allow the application to redeploy to tomcat without having to shutdown deploy and startup tomcat
after a successful build.
The developer just has to issues the command \command{mvn tomcat7:redeploy} to deploy the application to tomcat.
\portal utilizes version \TomcatVersion of Tomcat. Older or newer versions of tomcat can be used but it is not recommend to go any lower than tomcat 7
Tomcat \TomcatVersion\ runs inside the Spring Boot executable JAR. No separate Tomcat installation, manager account, or deployment plugin is required. Configure the HTTP port through Spring Boot and terminate public HTTPS at a reverse proxy as described in Chapter~\ref{deployment}.
\section{Verification Tools}
Java tests use JUnit 4.13.2 and Maven Surefire 3.5.6. Frontend tests use Vitest through Angular CLI. OWASP Dependency-Check 13.0.0 runs during Maven's verify phase. Its npm audit includes development dependencies; the Node Package Analyzer skips native development packages that are not deployed. OSS Index is opt-in with credentials. Because Dependency-Check has \command{failOnError=false}, review its reports even after a successful build.
docs/src/UserGuide.tex
+1 -1
View File
@@ -8,7 +8,7 @@
\chapter{User Guide}
\label{userGuide}
This documetions how the user uses various aspects of the \portal.
This chapter describes the user workflows in \portal. Screenshots show the earlier interface and are retained as workflow illustrations; the current Angular Material interface may differ in layout and controls.
\input{guides/Login}
\input{guides/ScriptTab}
docs/src/api/ConfigurationAPI.tex
+6 -2
View File
@@ -17,7 +17,7 @@ The following will get a specified configuration value if that value is present
\ApiData{\input{api/sample/request/getConfValReq}}{\input{api/sample/response/getConfValResp}}
\subsection{Get Configuration}
The following will get the current configuration values associated with the server as specified in the file \filename{\$PORTAL\_HOME/portal.properties}
The following will get the current configuration values associated with the server as specified in the file \filename{portal.properties} in the resolved application home (Section~\ref{portal-home})
\begin{apimethod}
{Get Configuration}
{config/getConfiguration.do}
@@ -31,7 +31,7 @@ The following will get the current configuration values associated with the serv
\ApiData{\input{api/sample/None}}{\input{api/sample/response/getConfResp}}
\subsection{Save Configuration}
The following will save the server configuration values to \filename{\$PORTAL\_HOME/portal.properties}. All the parameters are option as they all do not need to be populated, just the ones that need to be changed
The following will save the server configuration values to \filename{portal.properties} in the resolved application home (Section~\ref{portal-home}). All the parameters are option as they all do not need to be populated, just the ones that need to be changed
\begin{apimethod}
{Save Configuration}
{config/saveConfiguration.do}
@@ -39,6 +39,10 @@ The following will save the server configuration values to \filename{\$PORTAL\_H
{Yes}
\begin{itemize}
\item \Optional{filepath}{File path to where the files are stored on the server}
\item \Optional{dbType}{Database type: h2 (default) or mysql}
\item \Optional{h2Url}{H2 JDBC connection URL}
\item \Optional{h2Username}{H2 database username}
\item \Optional{h2Password}{H2 database password; encrypted when saved}
\item \Optional{dbUsername}{Username granted access to the portal tables}
\item \Optional{dbPassword}{Password for the portal database user}
\item \Optional{dbRootUser}{Root username for the database.}
docs/src/api/GitAPI.tex
+2 -2
View File
@@ -29,8 +29,8 @@ The following will add/edit a git repository
\item \Required{scm}{The git repository url to clone}
\item \Required{branch}{The branch to checkout}
\item \Required{directory}{Local directory to clone into (doesn't need to exist)}
\item \Required{credentials}{The credentials to use. Requires the following:}\newline
\begin{itemize}
\item \Required{credentials}{The credentials to use. Requires the following:}
\begin{itemize}
\item \Required{uid}{Unique identifer of the credentials to use.}
\end{itemize}
\end{itemize}
docs/src/api/PermissionsAPI.tex
+4 -3
View File
@@ -15,7 +15,8 @@ The following section will describe adding a permission category
\item \Required{name}{Unique name of the permission group }
\item \Required{displayName}{Name to be displayed in the permissions list}
\item \Required{enabled}{Whether or not the permission group is enabled}
\item \Required{permissions}{permissions to add. The allowed permissions area aleady predefined by the server. Below are the required parameters that have to be set inside the permissions list.\newline \begin{itemize}
\item \Required{permissions}{permissions to add. The allowed permissions area aleady predefined by the server. Below are the required parameters that have to be set inside the permissions list.
\begin{itemize}
\item \Required{permissionId}{Id of the permission to add}
\item \Required{allowed}{whether or not the permission is enabled or not}
\end{itemize}}
@@ -37,8 +38,8 @@ The following section will describe updating a permission category
\item \Required{name}{Unique name of the permission group }
\item \Required{enabled}{Whether or not the permission group is enabled}
\item \Required{permissions}{permissions to add. The allowed permissions area aleady predefined by the server.
Below are the required parameters that have to be set inside the permissions list.\newline
\begin{itemize}
Below are the required parameters that have to be set inside the permissions list.
\begin{itemize}
\item \Required{permissionId}{Id of the permission to add}
\item \Required{allowed}{whether or not the permission is enabled or not}
\end{itemize}}
docs/src/api/ScriptAPI.tex
+30 -30
View File
@@ -61,29 +61,29 @@ The following will a a local script to the system
\item \Required{command}{The command to execute}
\item \Optional{baseDirectory}{Local directory to start the command in}
\item \Optional{outputDirectory}{Directory to place any output into}
\item \Optional{parameters}{Paremetrs to be used with the command}\newline
\begin{itemize}
\item \Optional{parameters}{Paremetrs to be used with the command}
\begin{itemize}
\item \Required{parameter}{The parameter to be used}
\end{itemize}
\item \Optional{schedule}{Time and frequency the script should execute}\newline
\begin{itemize}
\item \Optional{schedule}{Time and frequency the script should execute}
\begin{itemize}
\item \Required{frequency}{How often the script should trigger}
\item \Required{startDatetime}{When the schedule should start to trigger}
\item \Optional{endDatetime}{When the schedule should end}
\item \Optional{maxExecution}{Number of executions before schedule stops}
\end{itemize}
\Optional{scriptVariables}{Environment variables specific to the script}\newline
\begin{itemize}
\item \Optional{scriptVariables}{Environment variables specific to the script}
\begin{itemize}
\item \Required{name}{Name of the variable}
\item \Required{value}{Value of the variable}
\end{itemize}
\Optional{scriptChain}{Follow-on scripts to execute after parent script finishes}\newline
\begin{itemize}
\item \Optional{scriptChain}{Follow-on scripts to execute after parent script finishes}
\begin{itemize}
\item \Required{childScript}{Id of the child script to execute}
\item \Required{exitStatus}{Exit status of the parent to trigger child script}
\end{itemize}
\Optional{scriptEmails}{Email to send once script finishes}\newline
\begin{itemize}
\item \Optional{scriptEmails}{Email to send once script finishes}
\begin{itemize}
\item \Required{emailName}{Name of the email template to send}
\item \Required{recipients}{List of recipients to send the email to. Requires email address}
\end{itemize}
@@ -116,37 +116,37 @@ The following will a remote script to the system
\begin{itemize}
\item \Required{name}{Unique name of the script}
\item \Required{scriptType}{``REMOTE''}
\item \Required{remote}{The remote connection information}\newline
\begin{itemize}
\item \Required{remote}{The remote connection information}
\begin{itemize}
\item \Required{scriptCredentials}{The uid of the credentials to use}
\item \Required{url}{the IP address or url to connect to}
\item \Required{port}{The port to connect to}
\end{itemize}
\item \Optional{baseDirectory}{Remote directory to start the command in}
\item \Optional{outputDirectory}{Directory to place any output into}
\item \Optional{parameters}{Paremetrs to be used with the command}\newline
\begin{itemize}
\item \Optional{parameters}{Paremetrs to be used with the command}
\begin{itemize}
\item \Required{parameter}{The parameter to be used}
\end{itemize}
\item \Optional{schedule}{Time and frequency the script should execute}\newline
\begin{itemize}
\item \Optional{schedule}{Time and frequency the script should execute}
\begin{itemize}
\item \Required{frequency}{How often the script should trigger}
\item \Required{startDatetime}{When the schedule should start to trigger}
\item \Optional{endDatetime}{When the schedule should end}
\item \Optional{maxExecution}{Number of executions before schedule stops}
\end{itemize}
\Optional{scriptVariables}{Environment variables specific to the script}\newline
\begin{itemize}
\item \Optional{scriptVariables}{Environment variables specific to the script}
\begin{itemize}
\item \Required{name}{Name of the variable}
\item \Required{value}{Value of the variable}
\end{itemize}
\Optional{scriptChain}{Follow-on scripts to execute after parent script finishes}\newline
\begin{itemize}
\item \Optional{scriptChain}{Follow-on scripts to execute after parent script finishes}
\begin{itemize}
\item \Required{childScript}{Id of the child script to execute}
\item \Required{exitStatus}{Exit status of the parent to trigger child script}
\end{itemize}
\Optional{scriptEmails}{Email to send once script finishes}\newline
\begin{itemize}
\item \Optional{scriptEmails}{Email to send once script finishes}
\begin{itemize}
\item \Required{emailName}{Name of the email template to send}
\item \Required{recipients}{List of recipients to send the email to. Requires email address}
\end{itemize}
@@ -179,8 +179,8 @@ The following will a scp script to the system
\begin{itemize}
\item \Required{name}{Unique name of the script}
\item \Required{scriptType}{``SCP''}
\item \Required{scp}{The remote connection information}\newline
\begin{itemize}
\item \Required{scp}{The remote connection information}
\begin{itemize}
\item \Required{fromCredentials}{The uid of the credentials for the machine retriving file from}
\item \Required{fromHost}{the IP address or url to connect to or ``LOCAL'' if the file is from the server}
\item \Required{fromPort}{The port to connect to or 0 if the file is ``LOCAL''}
@@ -190,20 +190,20 @@ The following will a scp script to the system
\end{itemize}
\item \Optional{baseDirectory}{Remote to look for the file}
\item \Optional{outputDirectory}{Directory to place any files into}
\item \Optional{schedule}{Time and frequency the script should execute}\newline
\begin{itemize}
\item \Optional{schedule}{Time and frequency the script should execute}
\begin{itemize}
\item \Required{frequency}{How often the script should trigger}
\item \Required{startDatetime}{When the schedule should start to trigger}
\item \Optional{endDatetime}{When the schedule should end}
\item \Optional{maxExecution}{Number of executions before schedule stops}
\end{itemize}
\Optional{scriptChain}{Follow-on scripts to execute after parent script finishes}\newline
\begin{itemize}
\item \Optional{scriptChain}{Follow-on scripts to execute after parent script finishes}
\begin{itemize}
\item \Required{childScript}{Id of the child script to execute}
\item \Required{exitStatus}{Exit status of the parent to trigger child script}
\end{itemize}
\Optional{scriptEmails}{Email to send once script finishes}\newline
\begin{itemize}
\item \Optional{scriptEmails}{Email to send once script finishes}
\begin{itemize}
\item \Required{emailName}{Name of the email template to send}
\item \Required{recipients}{List of recipients to send the email to. Requires email address}
\end{itemize}
docs/src/api/sample/None.tex
+1 -1
View File
@@ -1 +1 @@
None
None
docs/src/api/sample/SuccessResp.tex
-2
View File
@@ -1,8 +1,6 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"success":true,
"body":true
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addCredSshKeyReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"username": "iparenteau",
@@ -8,4 +7,3 @@
"key": "-----BEGIN RSA PRIVATE KEY-----...-----END RSA PRIVATE KEY-----"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addCredUnameReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"username": "foo",
@@ -7,4 +6,3 @@
"credentialType": "PASSWD",
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addEmailTemplateReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"emailName": "Script Status 2",
@@ -6,4 +5,3 @@
"emailMessage": "<p>Script ${script_name} finished with an exit code of ${exit_status}</p>",
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addEnvVarsReq.tex
+1 -3
View File
@@ -1,9 +1,8 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
"isNew": true
},
{
@@ -13,4 +12,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addGitRepoReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"name": "Stig Apply",
@@ -10,4 +9,3 @@
}
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addPermGroupReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"name": "test",
@@ -16,4 +15,3 @@
]
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addScriptLocalReq.tex
+1 -3
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"name": "tomcat running",
@@ -21,7 +20,7 @@
}],
"scriptVariables": [{
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
}],
"scriptChain": [{
"childScript": 3,
@@ -35,4 +34,3 @@
}],
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addScriptRemoteReq.tex
+1 -3
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"name": "tomcat running",
@@ -25,7 +24,7 @@
}],
"scriptVariables": [{
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
}],
"scriptChain": [{
"childScript": 3,
@@ -39,4 +38,3 @@
}],
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addScriptScpReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"name": "scp script",
@@ -36,4 +35,3 @@
}],
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/addUserReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"password": "bar",
@@ -10,4 +9,3 @@
"effectiveDate": "2018-04-03T19:54:39.929Z",
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteCredsReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"uid": "161415ae-07fd-427e-9bf8-3d08a2af7722",
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteEmailTemplateReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 4
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteEnvVarsReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -9,4 +8,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteFileReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 6
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteGitRepoReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 5
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deletePermGroupReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"name": "TEST"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteScriptReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 4,
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteScriptScheduleReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"jobId": "a3bf7cac-bba5-4cd4-bdfa-9fdbcbf08e25",
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/deleteUserReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"email": "bar@locusworks.net",
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/getConfValReq.tex
+1 -3
View File
@@ -1,6 +1,4 @@
\begin{minipage}[t]{0.45\textwidth}
\footnotetext{Send the key name to the server}
\noindent\textit{Send the key name to the server}\par
\begin{lstlisting}[language=JSON]
userExpirationDays
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/getScriptStatusReq.tex
+1 -3
View File
@@ -1,6 +1,4 @@
\begin{minipage}[t]{0.45\textwidth}
\footnotetext{Send the job id to the server}
\noindent\textit{Send the job id to the server}\par
\begin{lstlisting}[language=JSON]
459db38f-317f-40ad-bcf1-692c0404e7ac
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/loginReq.tex
-2
View File
@@ -1,8 +1,6 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"username":"foo",
"password":"bar"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/purgeLogReq.tex
-2
View File
@@ -1,8 +1,6 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"purgeStartDate": "2018-02-07T05:00:00.000Z",
"purgeEndDate": "2018-03-26T04:00:00.000Z"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/runScriptReq.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 4,
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/updatePermGroupReq.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"name": "test",
@@ -15,4 +14,3 @@
]
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/request/updateSeedReq.tex
+1 -3
View File
@@ -1,6 +1,4 @@
\begin{minipage}[t]{0.45\textwidth}
\footnotetext{Send the seed text to the server}
\noindent\textit{Send the seed text to the server}\par
\begin{lstlisting}[language=JSON]
This is a seed text
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addCredSshKeyResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 6,
@@ -11,4 +10,3 @@
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addCredUnameResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 5,
@@ -9,4 +8,3 @@
"credentialType": "PASSWD"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addEmailTemplateResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 4,
@@ -9,4 +8,3 @@
"dateCreated": 1524165482009
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addEnvVarsResp.tex
+1 -3
View File
@@ -1,10 +1,9 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
"id": 6,
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
"createdBy": 1,
"lastUpdated": 1524158738000,
"dateCreated": 1524158738000,
@@ -21,4 +20,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addGitRepoResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 5,
@@ -18,4 +17,3 @@
"createdBy": "Portal Admin"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addPermGroupResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 3,
@@ -27,4 +26,3 @@
]
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addScriptLocalResp.tex
+1 -3
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 4,
@@ -35,7 +34,7 @@
"scriptVariables": [{
"id": 1,
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
"createdBy": 1,
"lastUpdated": 1524226391000,
"dateCreated": 1524226391000,
@@ -68,4 +67,3 @@
}],
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addScriptRemoteResp.tex
+1 -3
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 4,
@@ -29,7 +28,7 @@
}],"scriptVariables": [{
"id": 1,
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
"createdBy": 1,
"lastUpdated": 1524226391000,
"dateCreated": 1524226391000,
@@ -71,4 +70,3 @@
},
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addScriptScpResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 7,
@@ -48,4 +47,3 @@
}],
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/addUserResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 3,
@@ -14,4 +13,3 @@
"enabled": true
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/deleteCredsResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 8,
@@ -8,4 +7,3 @@
"credentialType": "PASSWD"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/deleteEnvVarsResp.tex
+1 -3
View File
@@ -1,10 +1,9 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
"id": 6,
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
"createdBy": 1,
"lastUpdated": 1524158738000,
"dateCreated": 1524158738000,
@@ -21,4 +20,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/deletePermGroupResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 3,
@@ -27,4 +26,3 @@
]
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/deleteScriptScheduleResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 6,
@@ -13,4 +12,3 @@
"script": 4
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getAllCredsResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -17,4 +16,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getAllLogsResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -30,4 +29,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getAllPermsResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -17,4 +16,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getAllReposResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -20,4 +19,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getAllScriptsResp.tex
+1 -3
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[{
"id": 4,
@@ -35,7 +34,7 @@
"scriptVariables": [{
"id": 1,
"name": "JAVA_HOME",
"value": "C:\Program Files\Java\jdk1.8.0_152",
"value": "C:/Program Files/Java/jdk-21",
"createdBy": 1,
"lastUpdated": 1524226391000,
"dateCreated": 1524226391000,
@@ -68,4 +67,3 @@
}],
}]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getAllUsersResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -29,4 +28,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getConfResp.tex
+6 -4
View File
@@ -1,16 +1,18 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"logLevel": "INFO",
"userExpirationDays": "3650",
"dbRootPassword": "Em46JDIzVOWBgGFqxDrqnw==",
"dbType": "h2",
"h2Url": "jdbc:h2:file:C:/Users/user/.portal/data/portal;MODE=MySQL;DATABASE_TO_LOWER=TRUE;DEFAULT_NULL_ORDERING=HIGH;NON_KEYWORDS=VALUE;DB_CLOSE_ON_EXIT=FALSE;INIT=CREATE SCHEMA IF NOT EXISTS portal",
"h2Username": "sa",
"h2Password": "",
"dbHost": "localhost",
"dbPort": "3306",
"dbRootUser": "root",
"dbUsername": "portalAdmin",
"filepath": "C:\\tempStorage",
"dbPassword": "CWg48+h4q7iK4ICGaDhRd10EMQfFgthm3FjhkLd6gis="
"aesSeedFile": "C:/Users/user/.portal/portal.tomcat"
"dbPassword": "CWg48+h4q7iK4ICGaDhRd10EMQfFgthm3FjhkLd6gis=",
"aesSeedFile": "C:/Users/user/.portal/portal.tomcat"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getConfValResp.tex
-2
View File
@@ -1,7 +1,5 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"userExpirationDays": 3650
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getCredTypesResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -13,4 +12,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getEmailTemplateResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -13,4 +12,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getLoggersResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -19,4 +18,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getPermCatResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -53,4 +52,3 @@
},
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getPermGroupResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -57,4 +56,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getScheduleFreqResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -43,4 +42,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getScriptScheduleStatusResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -23,4 +22,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getScriptTypesResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -18,4 +17,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/getSmtpConfigResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
[
{
@@ -28,4 +27,3 @@
}
]
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/isLoggedInResp.tex
-2
View File
@@ -1,8 +1,6 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"success":false,
"body":null
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/loginResp.tex
-2
View File
@@ -1,4 +1,3 @@
\begin{minipage}[t]{0.45\textwidth}
\begin{lstlisting}[language=JSON]
{
"id": 1,
@@ -29,4 +28,3 @@
"page": "dashboard"
}
\end{lstlisting}
\end{minipage}
docs/src/api/sample/response/purgeLogResp.tex
+1 -3
View File
@@ -1,9 +1,7 @@
\begin{minipage}[t]{0.45\textwidth}
\footnotetext{The return value in body is the number of logs that were purged}
\noindent\textit{The return value in body is the number of logs that were purged}\par
\begin{lstlisting}[language=JSON]
{
"success":true,
"body":13
}
\end{lstlisting}
\end{minipage}
docs/src/appendix/ApacheAppendex.tex
+9 -8
View File
@@ -1,10 +1,11 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE : ApacheAppendix.tex
% SUBJECT : ApacheApendex.
% AUTHOR : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Apache Configuration}
\label{sample-httpd.conf}
\lstinputlisting[caption=httpd.conf]{figures/httpd.conf}
For Apache HTTP Server 2.4.47 or newer, \command{mod\_proxy\_http} can forward WebSocket upgrades. Enable \command{mod\_proxy}, \command{mod\_proxy\_http}, \command{mod\_headers}, and the TLS modules. Place these directives in your HTTPS virtual host, with your hostname and certificates configured separately:
\begin{lstlisting}[caption={Apache forwarding directives}]
ProxyRequests Off
ProxyPreserveHost On
RequestHeader set X-Forwarded-Proto "https"
ProxyPass /portal/ http://127.0.0.1:8080/portal/ upgrade=websocket
ProxyPassReverse /portal/ http://127.0.0.1:8080/portal/
\end{lstlisting}
Redirect the HTTP site to HTTPS. Match proxy request limits and timeouts to the application. Consult \url{https://httpd.apache.org/docs/2.4/mod/mod_proxy_http.html} for the installed Apache version's upgrade handling.
docs/src/appendix/NginxAppendex.tex
+22 -8
View File
@@ -1,10 +1,24 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE : Architecture.tex
% SUBJECT : Document describing architecture issues in the entire Patch Repository system.
% AUTHOR : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{NGINX Configuration}
\label{sample-nginx.conf}
\lstinputlisting[caption=portal.conf]{figures/portal.conf}
Place the map in the \command{http} context and the location in your site's HTTPS server block. Configure your hostname, TLS certificates, and HTTP-to-HTTPS redirect in the surrounding site configuration. This forwards the application context and supports WebSocket upgrades.
\begin{lstlisting}[caption={NGINX forwarding directives}]
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
# Inside the HTTPS server block:
location /portal/ {
client_max_body_size 10m;
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_read_timeout 600s;
}
\end{lstlisting}
See \url{https://nginx.org/en/docs/http/websocket.html} for WebSocket forwarding details.
docs/src/appendix/PropertiesAppendex.tex
+27 -8
View File
@@ -1,10 +1,29 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE : Architecture.tex
% SUBJECT : Document describing architecture issues in the entire Patch Repository system.
% AUTHOR : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Portal Properties File}
\label{sample-portal.properties}
\lstinputlisting[caption=portal.properties]{figures/portal.properties}
Portal initializes persistent settings from its bundled defaults. The file lives in the resolved application home (Section~\ref{portal-home}). New installations use \command{dbType=h2}; existing installations retain their configured database type. The following excerpt shows the current non-secret defaults:
\begin{lstlisting}[caption={Portal database and runtime settings}]
userExpirationDays=3650
logLevel=INFO
dbType=h2
h2Url=jdbc:h2:file:${portal.home}/data/portal;MODE=MySQL;DATABASE_TO_LOWER=TRUE;DEFAULT_NULL_ORDERING=HIGH;NON_KEYWORDS=VALUE;DB_CLOSE_ON_EXIT=FALSE;INIT=CREATE SCHEMA IF NOT EXISTS portal
h2Username=sa
h2Password=
dbHost=localhost
dbPort=3306
dbUsername=portalAdmin
dbRootUser=root
caCertFile=${user.home}/cacerts.jks
aesSeedFile=${portal.home}/portal.tomcat
\end{lstlisting}
The database and certificate password values are omitted from this excerpt. Preserve installation-specific encrypted values and use Portal's configuration facilities to change them. Do not copy ciphertext from a different installation with a different seed.
Spring Boot settings are packaged separately in \filename{application.properties}:
\begin{lstlisting}[caption={Spring Boot settings}]
spring.application.name=portal
server.servlet.context-path=/portal
server.servlet.session.timeout=540m
spring.jpa.open-in-view=false
spring.jpa.hibernate.ddl-auto=none
spring.servlet.multipart.max-file-size=10MB
spring.servlet.multipart.max-request-size=10MB
\end{lstlisting}
docs/src/appendix/ReleaseNotes.tex
+5
View File
@@ -0,0 +1,5 @@
% Jenkins replaces this placeholder before compiling release documentation.
\chapter{Release Notes}
\label{release-notes}
Release notes are generated during the Jenkins \command{Build LaTeX} stage on
\command{release/**} branches. Build a release to include its changes here.
docs/src/appendix/Revisions.tex
+3 -2
View File
@@ -8,9 +8,10 @@
\chapter{Revision History}
\label{revisions}
\begin{center}
\begin{tabular}{|C{0.1\textwidth}|C{0.5\textwidth}|C{0.15\textwidth}|C{0.15\textwidth}|}
\begin{tabular}{|C{0.1\textwidth}|C{\dimexpr0.6\linewidth-8\tabcolsep-5\arrayrulewidth\relax}|C{0.15\textwidth}|C{0.15\textwidth}|}
\hline
\bold{Revision Number} & \bold{Comment} & \bold{Date} & \bold{Name} \\ \hline
2.0 & Align tool versions, Angular client, executable Spring Boot deployment, H2 defaults, and build instructions with the current project & 4 September, 2026 & Locusworks \\ \hline
1.0 & Initial documentation draft & 10 April, 2018 & Isaac Parenteau \\ \hline
\end{tabular}
\end{center}
\end{center}
docs/src/appendix/SettingsAppendex.tex
+14 -9
View File
@@ -1,10 +1,15 @@
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% FILE : Architecture.tex
% SUBJECT : Document describing architecture issues in the entire Patch Repository system.
% AUTHOR : (C) Copyright 2018 by Locusworks
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Sample Settings.xml}
\chapter{Sample Maven Settings}
\label{sample-settings.xml}
\lstinputlisting[language=XML, caption=settings.xml]{figures/settings.xml}
Use these server IDs when Nexus authentication is required. Supply the referenced environment variables locally. Add \command{nexus-release} and \command{nexus-snapshot} entries with deployment credentials when publishing artifacts.
\begin{lstlisting}[language=XML,caption={User Maven settings.xml}]
<settings xmlns="http://maven.apache.org/SETTINGS/1.2.0">
<servers>
<server>
<id>locusworks-public</id>
<username>${env.NEXUS_USERNAME}</username>
<password>${env.NEXUS_PASSWORD}</password>
</server>
</servers>
</settings>
\end{lstlisting}
The Nexus URL is configured in the project POM. Maven settings do not configure the application's runtime database or embedded Tomcat. An optional server named \command{oss-index} supplies credentials for the opt-in dependency analyzer.
docs/src/guides/AESSeed.tex
+2 -2
View File
@@ -19,7 +19,7 @@ The following case allows a user to change the seed value. Upon saving, the serv
\centering
\scalebox{0.75}{\includegraphics*{figures/menu.png}}
\caption{Menu}
\label{fig:menu}
\label{fig:menu-aesseed}
\end{figure}
\begin{figure}[!htp]
@@ -32,7 +32,7 @@ The following case allows a user to change the seed value. Upon saving, the serv
\begin{usecase}
{CHANGE AES Seed Value}
{Authenticated User with change aes seed permission}
{The user is viewing the aes seed dialog after selecting it from the menu. Reference figure~\ref{fig:menu}}
{The user is viewing the aes seed dialog after selecting it from the menu. Reference figure~\ref{fig:menu-aesseed}}
\begin{enumerate}
\item User inputs new seed value. This can be any input. See Figure~\ref{fig:aes-seed}
\item User will be presented with a confirmation box.
docs/src/guides/Configuration.tex
+4 -4
View File
@@ -1,13 +1,13 @@
\section{Configuration Settings}
\label{configuration}
The configuration settings (located in the menu drop down to right hand corner. See figure~\ref{fig:menu}) controls various aspects of the server during start up. Any changes made here will not take effect until server restart.
The configuration settings (located in the menu drop down to right hand corner. See figure~\ref{fig:menu-configuration}) controls various aspects of the server during start up. Any changes made here will not take effect until server restart.
\begin{figure}[!htb]
\centering
\scalebox{0.75}{\includegraphics*{figures/menu.png}}
\caption{Menu}
\label{fig:menu}
\label{fig:menu-configuration}
\end{figure}
\subsection{General Configuration}
@@ -36,7 +36,7 @@ General configuration tells the server where the upload files will be stored loc
\subsection{Database General Configuration}
Database general configuration tells the server which information to use to connect to the database with.
New installations use persistent H2 (\command{dbType=h2}). H2 settings are \command{h2Url}, \command{h2Username}, and \command{h2Password}. The host, port, and root-user fields below apply to external MySQL (\command{dbType=mysql}), which requires MySQL Server \MySQLVersion. See Section~\ref{portal-home} for the persistent configuration location. Existing installations keep their configured database type.
\begin{figure}[!htp]
\includegraphics*[width=\linewidth]{figures/config-db.png}
@@ -84,4 +84,4 @@ Database root configuration shows the root database user and password (the passw
\item A confirmation box will be displayed to the user letting them know the changes wont take effect until the server restarts
\item Upon clicking yes, the dialog boxes will disappear and a success message will be displayed
\end{enumerate}
\end{usecase}
\end{usecase}
docs/src/guides/EnvVarTab.tex
+1 -1
View File
@@ -1,7 +1,7 @@
\section{Environment Variables Tab}
\label{envvarTab}
The environment variables tab defines global environment variables that will be set on all script executions. These variables will be added to the local \command{PATH}.
This allows for all scripts to utilize the same enviornment variables without having to set these variables locally on the server for the tomcat user.
This allows for all scripts to utilize the same enviornment variables without having to set these variables locally on the server for the Portal service account.
The rest of this section describes how to perform various actions on the the Enviornment Variables Tab. See Figure~\ref{fig:envvar-tab}
docs/src/guides/LogLevel.tex
+4 -4
View File
@@ -1,7 +1,7 @@
\section{Log Level Settings}
\label{logLevel}
The server uses loggers for server events. These logs are stored under \filename{\$PORTAL\_HOME/logs}; by default, \filename{\$PORTAL\_HOME} is \filename{\${user.home}/.portal}.
The server uses loggers for server events. These logs are stored under \filename{\$PORTAL\_HOME/logs}; by default, \filename{\$PORTAL\_HOME} is \filename{\${user.home}/.portal}.
Each application component has a logger associated with it with the default log level of \command{INFO} which will show general information to highlight progress. Each log level has an assigned level of importants with \command{OFF} being the most important and \command{ALL} being the least important. When determining what the log, the event to be logged compares itself to the logger and what its level is set at. If the event being logged is less important than the current log level for the component, that event will be ignored. If it is greater than or equal to the current level, the event will be logged.
@@ -27,7 +27,7 @@ The level of importances from greatest to least is
\subsection{Changing log levels}
The following case allows a user to change the log level for server components. Upon saving the log levels, the component will now respects its new level and log according.
NOTE: These values are persisted. Upon server restart, the server will see if there is an entry for the logger and set the log level accordingly; otherwise, it will use the default value. The location for the persisted portal logging file is \filename{\$PORTAL\_HOME/portal-loggers.properties}.
NOTE: These values are persisted. Upon server restart, the server will see if there is an entry for the logger and set the log level accordingly; otherwise, it will use the default value. The location for the persisted portal logging file is \filename{\$PORTAL\_HOME/portal-loggers.properties}.
When displaying the log levels, the levels are displayed in alphabetical order based off the component name
@@ -35,7 +35,7 @@ When displaying the log levels, the levels are displayed in alphabetical order b
\centering
\scalebox{0.75}{\includegraphics*{figures/menu.png}}
\caption{Menu}
\label{fig:menu}
\label{fig:menu-loglevel}
\end{figure}
\begin{figure}[!htp]
@@ -48,7 +48,7 @@ When displaying the log levels, the levels are displayed in alphabetical order b
\begin{usecase}
{CHANGE LOG LEVELS}
{Authenticated User with change log level permission}
{The user is viewing the log levels after selecting it from the menu. Reference figure~\ref{fig:hash-alg}}
{The user is viewing the log levels after selecting it from the menu. Reference figure~\ref{fig:log-levels}}
\begin{enumerate}
\item User pages through the tabs to find the component to change the log level
\item User chooses which level to set the log to (see table~\ref{tab:logLevels})
docs/src/guides/SMTP.tex
+2 -2
View File
@@ -1,13 +1,13 @@
\section{SMTP Settings}
\label{smtp}
The SMTP configuration (located in the menu drop down to right hand corner. See figure~\ref{fig:menu}) controls sending emails for scripts that have email templates associated with them.
The SMTP configuration (located in the menu drop down to right hand corner. See figure~\ref{fig:menu-smtp}) controls sending emails for scripts that have email templates associated with them.
\begin{figure}[!htb]
\centering
\scalebox{0.75}{\includegraphics*{figures/menu.png}}
\caption{Menu}
\label{fig:menu}
\label{fig:menu-smtp}
\end{figure}
\subsection{General Configuration}
docs/src/macros.tex
+53 -96
View File
@@ -28,38 +28,44 @@
\newcommand{\Gray}[1]{\textcolor{gray}{#1}}
\newcommand{\Red}[1]{\textcolor{red}{#1}}
\newcommand{\Required}[2]{
\makebox[3.3cm][l]{\texttt{\bold{\Red{#1}}}}: \begin{minipage}[t]{7cm}#2\end{minipage}
% Keep parameter descriptions in the surrounding list so they can wrap and
% continue onto another page, including nested parameter lists.
\newcommand{\Required}[2]{\texttt{\bold{\Red{#1}}}: #2}
\newcommand{\Optional}[2]{\texttt{\bold{\Gray{#1}}}: #2}
% Reserve room for a sample heading and its first few lines.
\newcommand{\SampleSpace}{%
\ifdim\dimexpr\pagegoal-\pagetotal\relax<6\baselineskip
\newpage
\fi
}
\newcommand{\Optional}[2]{
\makebox[3.35cm][l]{\texttt{\bold{\Gray{#1}}}}: \begin{minipage}[t]{7cm}#2\end{minipage}
% Full-width samples allow long JSON responses to paginate naturally.
\newcommand{\ApiData}[2]{%
\par\medskip\SampleSpace\noindent\bold{Sample Request}\par\nopagebreak
#1\par\medskip\SampleSpace\noindent\bold{Sample Response}\par\nopagebreak
#2\par\medskip
}
\newcommand{\ApiData}[2] {
\begin{tabular}{| C{0.5\textwidth} | C{0.5\textwidth} |} \hline
\bold{Sample Request} & \bold{Sample Response} \\ \hline
#1 & #2 \\ \hline
\end{tabular}
}
\newcommand{\locusworksCommonsVersion}{1.0.0-RELEASE\xspace}
\newcommand{\EclipseVersion}{Oxygen.2 Release (4.7.2)\xspace}
\newcommand{\JavaVersion}{21\xspace}
\newcommand{\MavenVersion}{3.5.3\xspace}
\newcommand{\AntVersion}{1.9.10\xspace}
\newcommand{\AngularJsVersion}{1.6.9\xspace}
\newcommand{\SpringVersion}{5.0.5-RELEASE\xspace}
\newcommand{\NodeVersion}{24.20.0\xspace}
\newcommand{\NpmVersion}{12.0.2\xspace}
\newcommand{\HibernateVersion}{5.2.16.Final\xspace}
\newcommand{\FlywayVersion}{5.0.7\xspace}
\newcommand{\MySQLVersion}{5.7\xspace}
\newcommand{\TomcatVersion}{9.0.121\xspace}
\newcommand{\QuartzVerson}{2.3.0\xspace}
\newcommand{\JSchVersion}{0.1.54\xspace}
\newcommand{\JGitVersion}{4.11.0.201803080745-r\xspace}
\newcommand{\NetBeansVersion}{8.2\xspace}
% Versions match the project POMs, Spring Boot BOM, frontend lockfile and Jenkinsfile.
\newcommand{\locusworksCommonsVersion}{3.0.1-RELEASE\xspace}
\newcommand{\JavaVersion}{21\xspace}
\newcommand{\MavenVersion}{3.9.16\xspace}
\newcommand{\AngularVersion}{22.1.5\xspace}
\newcommand{\AngularCliVersion}{22.1.7\xspace}
\newcommand{\SpringBootVersion}{4.1.1\xspace}
\newcommand{\SpringVersion}{7.0.9\xspace}
\newcommand{\NodeVersion}{24.20.0\xspace}
\newcommand{\NpmVersion}{12.0.2\xspace}
\newcommand{\HibernateVersion}{7.4.5.Final\xspace}
\newcommand{\FlywayVersion}{13.5.0\xspace}
\newcommand{\HtwoVersion}{2.4.240\xspace}
\newcommand{\MySQLVersion}{8.4 or newer\xspace}
\newcommand{\MySQLConnectorVersion}{26.7.0\xspace}
\newcommand{\TomcatVersion}{11.0.25\xspace}
\newcommand{\QuartzVersion}{2.5.2\xspace}
\newcommand{\JSchVersion}{2.28.7\xspace}
\newcommand{\JGitVersion}{7.7.1.202607240634-r\xspace}
\let\Oldsection\section
\renewcommand{\section}{\FloatBarrier\Oldsection}
@@ -71,74 +77,25 @@
\renewcommand{\subsubsection}{\FloatBarrier\Oldsubsubsection}
% An environment for displaying api methods.
% This environment takes four parameters:
% \param #1: The name of the api method.
% \param #2: The endpoint url.
% \param #3: if its a post or get operations.
% \param #4: if the method requires authentication.
%
% The body of the environment is the required parameters.
\newsavebox{\ApiName} % Create some boxes to hold the necessary text.
\newsavebox{\ApiUrl} % We need to do this because we can't use the
\newsavebox{\ApiMethod} % environment parameters in the 'end' definition.
\newsavebox{\ApiAuthReq}
\newsavebox{\ApiRequired}
% Metadata tables account for padding and borders. The body remains outside
% the table so long procedures and parameter lists can break across pages.
\newenvironment{apimethod}[4]
{
\sbox{\ApiName}{\bfseries #1} % The name is easy.
\sbox{\ApiUrl}{\vspace{2mm}#2\vspace{2mm}}
\sbox{\ApiMethod}{\vspace{2mm}#3\vspace{2mm}} % The actor is easy.
\sbox{\ApiAuthReq}{\vspace{2mm}#4\vspace{2mm}}
\begin{lrbox}{\ApiRequired} % The environment body becomes the action.
\begin{minipage}{1\textwidth}\vspace{2mm}
}{
\vspace{2mm}
\end{minipage}
\end{lrbox}
% Now spew forth the table using the information collected above.
\begin{tabular}{|p{0.25\textwidth}||p{0.745\textwidth}|} \hline
\multicolumn{2}{|c|}{\usebox{\ApiName}} \\ \hline
Endpoint URL & \usebox{\ApiUrl} \\ \hline
Method & \usebox{\ApiMethod} \\ \hline
Requires Authentication & \usebox{\ApiAuthReq} \\ \hline
Parameters & \usebox{\ApiRequired} \\ \hline
\end{tabular}
}
{\par\medskip\noindent
\begin{tabular}{|L{\dimexpr.27\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|L{\dimexpr.73\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|}\hline
\multicolumn{2}{|p{\dimexpr\linewidth-2\tabcolsep-2\arrayrulewidth\relax}|}{\bold{#1}}\\\hline
Endpoint URL & \command{#2}\\\hline
Method & #3\\\hline
Requires Authentication & #4\\\hline
\end{tabular}\par\nobreak\smallskip
\noindent\bold{Parameters}\par\nopagebreak
}{\par\medskip}
% An environment for displaying use cases.
% This environment takes three parameters:
% \param #1: The name of the use case.
% \param #2: The actor who participates in the use case.
% \param #3: The context in which the use case executes.
%
% The body of the environment is the action associated with the use case.
\newsavebox{\UseCaseName} % Create some boxes to hold the necessary text.
\newsavebox{\UseCaseActor} % We need to do this because we can't use the
\newsavebox{\UseCaseContext} % environment parameters in the 'end' definition.
\newsavebox{\UseCaseAction}
\newenvironment{usecase}[3]
{
\sbox{\UseCaseName}{\bfseries #1} % The name is easy.
\sbox{\UseCaseActor}{\vspace{2mm}#2\vspace{2mm}}
\begin{lrbox}{\UseCaseContext} % Format the context in a minipage.
\begin{minipage}{0.825\textwidth}
#3
\end{minipage}
\end{lrbox}
\begin{lrbox}{\UseCaseAction} % The environment body becomes the action.
\begin{minipage}{0.825\textwidth}\vspace{2mm}
}{
\vspace{2mm}
\end{minipage}
\end{lrbox}
% Now spew forth the table using the information collected above.
\begin{tabular}{|R{0.1\textwidth}||L{0.85\textwidth}|} \hline
\multicolumn{2}{|c|}{\usebox{\UseCaseName}} \\ \hline
Actor & \usebox{\UseCaseActor} \\ \hline
Context & \usebox{\UseCaseContext} \\ \hline
Action & \usebox{\UseCaseAction} \\ \hline
\end{tabular}
}
{\par\medskip\noindent
\begin{tabular}{|L{\dimexpr.15\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|L{\dimexpr.85\linewidth-2\tabcolsep-1.5\arrayrulewidth\relax}|}\hline
\multicolumn{2}{|p{\dimexpr\linewidth-2\tabcolsep-2\arrayrulewidth\relax}|}{\bold{#1}}\\\hline
Actor & #2\\\hline
Context & #3\\\hline
\end{tabular}\par\nobreak\smallskip
\noindent\bold{Action}\par\nopagebreak
}{\par\medskip}
docs/src/portal.tex
+8 -4
View File
@@ -17,6 +17,8 @@
\usepackage[title]{appendix}
\usepackage[margin=1.0in]{geometry}
\usepackage[section]{placeins}
\usepackage[T1]{fontenc}
\usepackage{lmodern}
\usepackage{listings}
\usepackage{hyperref}
\usepackage{rotating}
@@ -44,6 +46,7 @@
% Layout adjustment
%---------------------------
\pagestyle{headings}
\setlength{\emergencystretch}{3em}
\setlength{\parindent}{0em}
\setlength{\parskip}{1.75ex plus0.5ex minus0.5ex}
@@ -84,6 +87,7 @@
%\author{Locusworks}
%\date{21 March, 2018}
%\maketitle
\hypersetup{pageanchor=false}
\begin{titlepage}
\centering
\includegraphics[width=\textwidth]{figures/portal.png}
@@ -91,6 +95,7 @@
{
\bfseries\Large
\portal Documentation \\
Java \JavaVersion\ / Spring Boot \SpringBootVersion\ / Angular \AngularVersion \\
\today \\
}
\vfill
@@ -102,6 +107,7 @@
% Table of contents
%-------------------
\pagenumbering{roman}
\hypersetup{pageanchor=true}
\tableofcontents
\newpage
\pagenumbering{arabic}
@@ -130,8 +136,6 @@
\input{appendix/PropertiesAppendex}
\input{appendix/SeedFileAppendex}
\input{appendix/Revisions}
\input{appendix/ReleaseNotes}
\bibliographystyle{plain}
\bibliography{references}
\end{document}
\end{document}
scripts/release-notes.sh
+56
View File
@@ -0,0 +1,56 @@
#!/bin/sh
# Release markers refer to source commits, not Maven's workspace version edits.
set -eu
mode=${1:-}
version=${2:-}
tag="portal-release-$version"
if [ -z "$version" ] || ! git check-ref-format "refs/tags/$tag"; then
echo 'Usage: sh scripts/release-notes.sh generate|publish VERSION' >&2
exit 1
fi
commit=$(git rev-parse HEAD)
case "$mode" in
generate)
# Fetch failures must not masquerade as a first release.
if [ "$(git rev-parse --is-shallow-repository)" = true ]; then
git fetch --unshallow origin
fi
git fetch origin 'refs/tags/portal-release-*:refs/tags/portal-release-*'
previous=$(git describe --tags --abbrev=0 --match 'portal-release-*' --exclude "$tag" HEAD 2>/dev/null || true)
range=HEAD
if [ -n "$previous" ]; then
range="$previous..HEAD"
fi
changes=$(git log --reverse --format='- %s (`%h`)' "$range" --)
printf '# Changes in %s\n\nSource commit: `%s`\n\n' "$version" "$commit"
if [ -n "$previous" ]; then
printf 'Since release tag `%s` (nearest release in this branch history).\n\n' "$previous"
else
printf 'First recorded release: includes all available source history.\n\n'
fi
if [ -n "$changes" ]; then
printf '%s\n' "$changes"
else
printf 'No source changes since the previous release.\n'
fi
;;
publish)
if git show-ref --verify --quiet "refs/tags/$tag"; then
if [ "$(git rev-parse "refs/tags/$tag^{commit}")" != "$commit" ]; then
echo "Release tag $tag already identifies another commit" >&2
exit 1
fi
else
git -c user.name='Jenkins' -c user.email='jenkins@locusworks.net' \
tag -a "$tag" "$commit" -m "Release $version"
fi
# Never overwrite a remote release marker.
git push origin "refs/tags/$tag:refs/tags/$tag"
;;
*)
echo 'Usage: sh scripts/release-notes.sh generate|publish VERSION' >&2
exit 1
;;
esac