# Pulse Application Local Development
## Getting Started
These instructions will get you a copy of the Pulse application and set up your environment for local front-end (AngularJS) and back-end (Spring Boot) development.
### Prerequisites
Before we can build/run the application, we need to first do the following:
1. Clone the Pulse repo. You know where to find it if you're reading this :-)
2. Download and install NodeJs & NPM and install. Node should be at v11.12.0 and NPM should be at version 6.7.0.
3. Download and install OpenSSL if it isn't already on your machine.
4. Download and install Java SDK 1.8 (any minor version is fine).
5. Add the following line to `~/.bash_profile` to make sure your `JAVA_HOME` environment variable is set to the Java 8 installation:
```
export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)
```
The ~/.bash_profile file is a configuration file for configuring user environments. The users can modify the default settings and add any extra configurations in it.
https://www.thegeekdiary.com/what-is-the-purpose-of-bash_profile-file-under-user-home-directory-in-linux/
6. Reload your bash profile by running `source ~/.bash_profile`.
7. Download and install Maven (only if you want to build from command line instead of IDE).
### Create self-signed SSL certificate
These steps need to be completed in order for the front-end to properly communicate with the back-end using HTTPS protocol, and will also prevent any security-related errors/warnings in your browser when running the application locally.
1. In a new terminal window, create a new directory (outside of your working directory for Pulse) called `crypto` and navigate to this directory.
```
mkdir crypto && cd crypto
```
2. Run the following to generate a new self-signed certificate:
```
openssl req -x509 -newkey rsa:2048 -keyout key.pem -out cert.pem -days 10950 -subj /CN=localhost -reqexts SAN -extensions SAN -config <(cat /etc/ssl/openssl.cnf <(printf '[SAN]\nsubjectAltName=DNS:localhost,IP:127.0.0.1'))
```
3. When prompted, enter the password `localdev`.
4. You should now have a new certificate file called `cert.pem` and a new key file called `key.pem`.
5. Copy these two files to the root of the front-end Angular app directory, where `server.js` is located (as of 10/17/2019, this is `src/main/webapp/app`). Make sure these files are not checked into Git. Alternatively, you can tell the ExpressJS server to pull the certificates directly from the `crypto` directory by creating an environment variable called `PULSE_CERT_DIR` pointing to the path of the `crypto` dir. One way to do this is to append the following line to `~/.bash_profile` on your machine:
```
export PULSE_CERT_DIR=""
```
6. Import your new cert file into the cert store on your OS, and set the cert to be always trusted. For Windows, do a Google search for the procedure. For Mac OS, execute the following steps:
1. Open up the Keychain Access app.
2. In the 'Keychains' panel on the left, right click the 'System' keychain and click 'Unlock Keychain "System"'.
3. With the 'System' keychain selected, click on 'Certificates' in the 'Category' panel on the left.
4. Click File -> Import items... (or press Command + Shift + I) and open the new `cert.pem` file you created.
5. You should now see a new certificate listed with name 'localhost'.
6. Double click the 'localhost' cert, expand the carrot next to 'Trust', and select 'When Using This Certificate: Always Trust'.
7. Convert the two PEM files into a single PKCS12 file, which will be used by Spring Boot. Still in the `crypto` directory, run the following command:
```
openssl pkcs12 -export -in cert.pem -inkey key.pem -out cert.p12 -name localhost -passin pass:localdev -passout pass:localdev
```
8. This should generate a new file called `cert.p12`. Copy this file into your Spring Boot resources folder (`src/main/resources`). Make sure this file is not checked into Git. Alternatively, you can tell Spring Boot to pull the certificate directly from your `crypto` directory by adding the following JVM arg when starting the application locally:
```
-Dserver.ssl.key-store=/cert.p12
```
### Building Front-end Angular application
1. Change directories to the front-end Angular app directory, where `package.json` is located (as of 10/17/2019 this is `src/main/webapp/app`).
2. If you are running this on the GPC network, you will need to run the following commands first in order to not get blocked installing certain packages:
```
git config --global url.https://github.com/.insteadOf git://github.com/ && git config --global http.sslVerify false && npm config set strict-ssl false
```
3. If this is your first time building the front-end since checking out the repository, you will need to run the following to initialize your `node_modules` folder:
```
npm install -f --no-optional -dd
```
4. After that has completed, the following command can be used whenever you want to build the application: (git\PulseUI\src\main\webapp\app)
```
npm run build-all-devqa
```
This command will run the `npm install` command (from step 3) to install any packages that have been added to `package.json` since the last build, and will then run webpack to create the deployment bundles (will be found in `src/main/webapp/app/dist`).
### Running Front-end Angular application
1. Change directories to the front-end Angular app directory, where `package.json` is located (as of 10/17/2019 this is `src/main/webapp/app`).
2. Run the following command to start the ExpressJS server, webpack build process, and webpack watchers: (If running in MAC OS)
* **US Pulse System**
* `npm run start-local-dev`
* The front-end application will be accessible from: https://localhost:3000
* **UAP Pulse System**
* `npm run start-local-dev-uap`
* The front-end application will be accessible from: https://localhost:4000
2. Run the following command to start the ExpressJS server, webpack build process, and webpack watchers: (If running in Windows OS)
If running in Windows please use command : npm run start-server within Directory to the front-end Angular app directory, where `package.json` is located (as of 10/17/2019 this is `src/main/webapp/app`)
NOTE --
After running this, you should be able to simply refresh your browser after changing and saving any javascript or HTML files. Note that Webpack might take a few seconds to update if there is a javascript change.
NOTE: For whichever Pulse system you choose to run, make sure a back-end service of the same Pulse system is running as well, in order to ensure the proxying of HTTP requests are handled correctly. For example, if you want to run the US Pulse system in the front-end, make sure your back-end service is running with the us-dev, us-qa, us-prod, or us-dr Spring profiles. You can run both Pulse systems at the same time if you wish, since they are hosted on separate ports. You would just need to run each NPM command in separate terminal windows.
### Building/Running Back-end Spring Boot application
To run the Spring Boot application, I recommend using an IDE like Spring Tool Suite or IntelliJ because of their seamless Spring Boot integration. Simply add a new run configuration pointing to the main class `com.napa.pulse.PulseBootApplication`. Make sure the JRE used for this project is 1.8.
If you prefer to build and run from the command line instead, run the following commands from the root directory of the project:
```
mvn clean install
java -Dspring.profiles.active= -jar target/pulseui-*.jar
```
where `` is the Spring profile you want to run. If you do not specify a profile, it will default to `us-dev`.
As a reminder, if you wanted to reference an external directory for your SSL certificate, you will also need to add the following JVM argument:
```
-Dserver.ssl.key-store=/cert.p12
```
Otherwise, make sure `cert.p12` is copied to `src/main/resources`.
#### Spring Profiles
Regardless of how you choose to start the application (IDE or command line), you can configure at runtime what environment (i.e. dev, qa, prod, dr) and system (i.e. US or UAP) the application should point to by specifying a Spring Profile. This should be an option in the IDE's Spring Boot run configuration, or can be specified on the command line by adding the JVM arg `-Dspring.profiles.active=`.
The following profiles can be used:
* us-dev (active by default)
* us-qa
* us-prod
* us-dr
* uap-dev
* uap-qa
* uap-prod
* uap-dr
The configuration files for these profiles can be found in `src/main/resources/application-.properties.`
Note: there are 3 levels of `application-XXX.properties` files, each being progressivly more specific to a given environment or system:
1. *Shared (i.e. `application.properties`)* - These are the properties that are shared by all profiles.
2. *Environment level (i.e. dev, qa, prod, dr)* - These properties are shared for a given database environment, regardless of the system (i.e. US or UAP). You do not need to explicitly select these profiles; they will be selected automatically based on which environment+system profile you choose.
3. *Environment+System level (e.g. us-dev, uap-dev, us-qa, uap-qa, etc.)* - These properties are specific to a given environment (i.e. dev, qa, prod, dr) and system (i.e. US or UAP). You should specify exactly one of these profiles at runtime. These profiles will automatically load the properties from the appropriate Environment level profile.
When you start the application, the URL for the back-end API will be different based on the *system* chosen:
* **US** - https://localhost:6443/api
* **UAP** - https://localhost:7443/api
The two different systems are hosted on separate ports to allow you to run both simultaneously if you wish.