Initial commit

docs/src/Deployment.tex

@@ -0,0 +1,109 @@
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+% FILE    : Deployment.tex
+% SUBJECT : Document describing deployment issues in Patch Repository.
+% AUTHOR  : (C) Copyright 2018 by Northrop Grumman
+%
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+\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 comes packaged as a \command{war} file. It is recommended to use \command{Tomcat} to host the web application. 
+
+\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:
+\begin{enumerate}
+  \item Maven \MavenVersion\ \cite{maven}
+  \item Java \JavaVersion\ \cite{java}
+  \item Ant \AntVersion\ \cite{ant}
+\end{enumerate}  
+
+Two projects need to be checkout out from the git repository. The \portal project and the ngas-commons project. 
+
+Section~\ref{dev-setup} describes how to checkout the \portal project
+
+Section~\ref{ngas-commons} descrives how to checkout and build the \command{ngas-commons} library. This library is needed to build the main web application 
+
+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.
+
+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}
+\label{mysql-root-password}
+
+To encrypted the mysql root password first checkout and compile the \command{ngas-commons} library (See section~\ref{ngas-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/com/ngas/ngas-commons/\ngasCommonsVersion}
+	\item Execute the following command\newline
+	\command{java -cp ngas-commons-\ngasCommonsVersion.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.
+
+\section{Seed File}
+\label{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}
+\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.
+
+\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}
+
+\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}
+