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

Updated tex files with latest information about the program

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

No files matched your search

docs/src/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.