\chapter{Deployment}
\label{deployment}

\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.

\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.

\section{Persistent Application Home}
\label{portal-home}
Portal resolves its home directory in this order:
\begin{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}.

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.

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{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}.

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.

\subsection{Encrypted Database Passwords}
\label{mysql-root-password}
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}.

\section{Reverse Proxy}
\label{conf-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}
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}
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.