Deployment

The middleware runs as a single Spring Boot WAR on embedded Tomcat, behind Nginx for SSL termination. Production lives at https://server.zra.co.zm/pckzra.

Prerequisites

Build

mvn clean package
# Produces the deployable artifact under target/

Run

java -jar target/taxint-chrilan-middleware-1.0.0.jar

# Verify:
# API:        http://localhost:8181/pckzra/api/taxint/health
# Swagger UI: http://localhost:8181/pckzra/swagger-ui.html
# Web portal: http://localhost:8181/pckzra/

Flyway runs migrations automatically on startup (baseline-on-migrate: true, validate-on-migrate: true). Hibernate validates entity/schema alignment (ddl-auto: validate) and fails fast on drift.

Production layout

Internet (HTTPS)
   │
   ▼
Nginx  ── SSL termination, forwards to ──▶  Spring Boot @ 0.0.0.0:8181, context /pckzra
   │                                              │
   │                                              ├──▶ MariaDB 192.168.0.50:3306/pckmiddle
   │                                              ├──▶ Chrilan  https://zra.abc.co.zm/smartinv
   │                                              ├──▶ Oracle STS / IDM (menus, JWT, PKCE)
   │                                              └──▶ Whapi https://gate.whapi.cloud
   ▼
server.zra.co.zm/pckzra

• The app binds 0.0.0.0:8181 with context path /pckzra.
• forward-headers-strategy: native makes the app trust X-Forwarded-* from Nginx so generated URLs keep the public host and scheme.
• CORS is restricted to https://server.zra.co.zm.

Docker

A Dockerfile and docker-compose.yml are included in the repository for containerized deployment:

docker build -t pck-middleware .
docker run -p 8181:8181 pck-middleware

Database setup (fresh environment)

CREATE DATABASE pckmiddle CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'chrilan'@'%' IDENTIFIED BY '<strong-password>';
GRANT ALL PRIVILEGES ON pckmiddle.* TO 'chrilan'@'%';
FLUSH PRIVILEGES;
-- Flyway applies V001–V008 automatically on first startup

Deployment checklist

1. Build passes (mvn clean package) with tests green.
2. Database reachable; credentials valid; Flyway history clean.
3. Outbound network verified to Chrilan, Oracle STS/IDM and Whapi.
4. auth.jwt.validation-enabled set deliberately for the environment (false for UAT, true for enforced production).
5. Default admin credentials rotated; portal admin users created with WhatsApp numbers.
6. Stores registered with exact SellerNames and Chrilan API keys.
7. Nginx proxying and SSL certificate valid for server.zra.co.zm.
8. Smoke test: health endpoint, then a test invoice from one store, verified in Reports.

Rollback

Keep the previous WAR artifact available. Because Flyway migrations are forward-only, verify any new migration is backward-compatible with the previous application version before deploying. The deployment governance records in the repository track each release batch.

Runtime tuning