A starting point for NR application teams. Spring Boot 4 backend, React 19 frontend, Oracle DB.

Frontend

Backend

• Docker Compose or Podman Compose
• VPN (Cisco Secure Client) — required to reach the DB and Jasper server
• hosts file entries for the DB and Jasper server — ask your team for the values

1. Configure your environment

cp .env.example .env

Open .env and fill in the required values:

Use single quotes if a value contains special characters: PASSWORD='p@ss!'

.env.example defaults to SPRING_PROFILES_ACTIVE=prod, which mirrors OpenShift: all of the variables above are required (the Jasper URLs have no defaults). If you don't have DB or Jasper credentials yet, set SPRING_PROFILES_ACTIVE=local instead — the local profile boots with empty fallbacks for Jasper/Cognito, mock auth enabled, and DEBUG logging, so the app starts without any integrations configured.

2. Connect VPN, then start

By default, docker compose up runs the frontend as a Vite dev server with hot-module reloading (via docker-compose.override.yml). The source tree is bind-mounted so edits on the host reload live.

# Docker
docker compose up --build

# Podman
podman compose up --build

The backend is not exposed directly. All /api/* traffic is proxied through the frontend container to the backend.

Running the production image locally

To run the production Caddy build (static files, no HMR) instead of the dev server:

docker compose -f docker-compose.yml up --build

Common commands

# Stop and remove containers
docker compose down

# View logs (all services)
docker compose logs -f

# View logs for one service
docker compose logs -f backend

# Rebuild a single service
docker compose up --build backend

# Stop without removing containers
docker compose stop

For local development, use mock mode — no Cognito login required. Mock mode has two halves, and both must be on:

With the backend half off (and no JWT vars configured), the frontend will show a fake logged-in user but every API call will be rejected with 401. The mock user's roles are controlled by AUTH_MOCK_ROLES (default ADMIN).

Running with real Cognito auth locally

1. Set AUTH_MOCK_ENABLED=false in .env and fill in the JWT vars.
2. Edit frontend/public/amplify-config.js, set "mockUser": false, and replace the REPLACE_ME placeholders with your Cognito values:

window.amplifyConfig = {
  "appEnv": "dev",
  "idpName": "DEV-IDIR",
  "region": "ca-central-1",
  "userPoolId": "ca-central-1_XXXXXXXXX",
  "userPoolClientId": "XXXXXXXXXXXXXXXXXXXXXXXXXX",
  "cognitoDomain": "nrs-XXXX.auth.ca-central-1.amazoncognito.com",
  "oauthScopes": ["openid", "profile", "email"],
  "redirectSignIn": "http://localhost:3000/",
  "redirectSignOut": "http://localhost:3000/logout",
  "mockUser": false,
  "famClientId": "CSP"
};

In OpenShift, Cognito config is injected at runtime via a ConfigMap — the amplify-config.js placeholder file in the image is overwritten by a volume mount. No rebuild is required when Cognito values change.

If your machine routes traffic through a corporate TLS proxy (e.g. Zscaler), the JVM inside the backend container needs to trust the proxy's root certificate or outbound HTTPS calls will fail with SSLHandshakeException.

This is a local development concern only. Certificate files are git-ignored (/backend/certs/*), so they are never committed and never present in CI/CD builds.

How it works

The backend Dockerfile has a dedicated build stage that imports every certificate file found in backend/certs/ into the JRE's trust store before the final image is assembled. Supported extensions: .cer, .pem, .crt. Empty or missing files are silently skipped.

Adding a certificate

1. Export the corporate root certificate from your browser or certificate manager (DER/PEM format).
2. Drop the file into backend/certs/ — e.g. backend/certs/zscaler.cer.
3. Rebuild the backend image:

docker compose up --build backend

The filename (without extension) becomes the alias in the trust store. Multiple certificates are supported — add one file per certificate.

Only the .gitkeep placeholder is tracked in git. Do not force-add cert files to git.

Deployments to OpenShift are fully automated through GitHub Actions — no manual steps are needed once the secrets and variables are configured.

Pipeline overview

Oracle init container

The backend pod uses an init container (ghcr.io/bcgov/nr-forest-client/common:prod) that runs before the app starts. It connects to the Oracle host on port 1543 (TCPS) using KEYSTORE_SECRET to fetch and write an Oracle wallet into a shared volume (/cert). The main container mounts this volume and the entrypoint script merges the wallet cert into the JVM trust store at startup.

GitHub Secrets & Variables

The following secrets and variables must be configured on the repository for the pipeline to work.

Repository secrets

Environment secrets (scoped to test and prod — override the repo-level OC_TOKEN)

Repository variables