# SETUP - Development
---
1. Clone the repository from BigMac:
	- Add your public key to BigMac account.
	- Clone the repository: `git clone "ssh://git@bigmac.locusworks.net:8010/saipt/portal-webapp.git"`
2. Create/Edit `settings.xml` in your `.m2` folder (see next section for example)
3. Change directories into the project and run `mvn clean install` (this may take a while).
4. Start the executable Spring Boot application with `java -jar portal_webapp/target/portal_webapp-1.0.0-RELEASE.jar`.
5. Browse to `http://localhost:8080/portal/`.

Application configuration is stored under `${user.home}/.portal` by default. Override this persistent location with the `PORTAL_HOME` environment variable or the `-Dportal.home=/path/to/portal` JVM property. The directory contains `portal.properties`, the AES seed, logger settings, logs, and temporary key files.

Local runs use a persistent H2 database by default. Set `dbType=mysql` in `portal.properties` only when an external MySQL server is intended; H2 and MySQL have separate connection and credential properties.

External MySQL deployments require MySQL Server 8.4 or newer with Connector/J 26.7.0.

## npm
---
npm is used to install the Angular client dependencies declared in `portal_client/package.json`.

The Maven build provisions the supported Node.js LTS and npm versions declared in the root `pom.xml`; a global installation is not required for Maven builds.

From `portal_client`, run `npm ci` for a reproducible install, `npm test` for unit tests, and `npm run build` for the production bundle. Angular CLI discovers application imports and static assets directly; no legacy asset-injection manifest is required.

The `allowScripts` entries in `package.json` approve specific versions of the native Angular build helpers. Review and renew those entries when upgrading the corresponding packages. SockJS remains an explicitly allowed CommonJS dependency for the server's SockJS transport. STOMP uses its ESM entry through the TypeScript path mapping because version 7.3.0's browser export selects UMD.

## Dependency checks

`mvn clean install` runs OWASP Dependency-Check. NVD, RetireJS, and the npm lockfile audit remain enabled; the npm audit includes development dependencies. The Node Package Analyzer skips development dependencies to avoid treating uninstalled native binaries for other platforms as missing application packages.

Sonatype OSS Index requires credentials and is opt-in. Configure a Maven `settings.xml` server with ID `oss-index`, your account username, and API token, then run `mvn clean install -Dportal.ossIndexEnabled=true` to include it.

## H2 tests
---
Tests use an isolated in-memory H2 database through the `portal.database.*` system-property overrides. Production continues to default to MySQL.

Run the common-module datasource test with:

`mvn -pl portal_common -am test`


## Settings.xml
---
If developing on the NGGN the proxy settings are needed to download the libraries

Sample:
```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.1.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd">
  <proxies>
    <proxy>
      <id>locusworks-proxy</id>
      <active>true</active>
      <protocol>http</protocol>
      <host>eastproxy.locusworks.net</host>
      <port>80</port>
      <username>(your MyID)</username>
      <password>(your login password)</password>
    </proxy>
    <proxy>
      <id>locusworks-proxy2</id>
      <active>true</active>
      <protocol>https</protocol>
      <host>eastproxy.locusworks.net</host>
      <port>80</port>
      <username>(your MyID)</username>
      <password>(your login password)</password>
    </proxy>
  </proxies>
  <servers>
    <server>
        <id>flyway-localhost</id>
        <username>root</username>
        <password>(mysql root password)</password>
    </server>
  </servers>
</settings>
```

## Running Spring Boot
---
The application is packaged as an executable JAR and does not require a separately installed application server. Spring Boot supplies the embedded web server. For production, NGINX or Apache can proxy ports 80 and 443 to the application on port 8080.

#### NGINX
1. In the default /etc/nginx/conf.d add a file called portal.conf

2. Populated it with the values below
``` conf
    proxy_cache_path /tmp/NGINX_cache/ keys_zone=backcache:10m;
    
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }
    
    upstream portal_app {
        # Use IP Hash for session persistence
        ip_hash;
    
        # List of Portal application instances
        server 127.0.0.1:8080;
    }
    
    server {
        listen 80;
        server_name portal.viprcenter.com;
        client_max_body_size 0;
    
        # Redirect all HTTP requests to HTTPS
        location / {
            return 301 https://$server_name$request_uri;
        }
    }
    
    server {
        listen 443 ssl http2;
        server_name portal.viprcenter.com;
        client_max_body_size 0;
    
        ssl_certificate     /etc/nginx/ssl/portal.viprcenter.com.crt;
        ssl_certificate_key /etc/nginx/ssl/portal.viprcenter.com.key;
    
        ssl_session_cache   shared:SSL:1m;
        ssl_prefer_server_ciphers on;
    
        # WebSocket configuration
        location / {
            proxy_pass http://portal_app;
            proxy_http_version 1.1;
            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 $remote_addr;
            proxy_set_header X-Forwarded-Host $remote_addr;
        }
    }
```

3. Save the file

4. Modify `/etc/nginx/nginx.conf` 

5. In the http section of the conf file add `include /etc/nginx/conf.d/portal.conf`

6. Restart NGINX

7. Navigate to the url. It should redirect to 443


#### Apache

1. In apaches `httpd.conf` file add the following
``` conf
	Listen 80    
	Listen 443
	
	<VirtualHost *:80>
	    RewriteEngine On
	    RewriteCond %{HTTP_HOST} ^(.*)$
	    RewriteRule ^(.*)$ https://%1$1 [R=Permanent,L,QSA]
	</VirtualHost>
	
	<VirtualHost *:443>
	    SSLEngine On
	    SSLCertificateFile /etc/apache/ssl/portal.viprcenter.com.crt
	    SSLCertificateKeyFile /etc/apache/ssl/portal.viprcenter.com.key
	
	    ProxyPreserveHost On
	    ProxyPass / http://127.0.0.1:8080/
	    ProxyPassReverse / http://127.0.0.1:8080/
	</VirtualHost>
```
2. Restart and try navigating