portal-webapp/README.md

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:

<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

    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

	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