Dominion/COOLIFY.md

Coolify & PostgreSQL Deployment Guide

This application consists of:

1. Server Side: Node.js + Express backend (server.ts) serving REST APIs, managing authentication, ledger reconciliation, audit logs, FX rates, SMTP dispatching, and financial reports.
2. Database: PostgreSQL (via pg connection pool) with automatic JSON fallback backup.
3. Frontend: React SPA served directly via Express in production.

---

1. Quick Coolify Deployment Options

Option A: Docker Compose Deployment (Application + PostgreSQL in One Stack)

1. In Coolify Dashboard:
   • Click + Add Resource -> Docker Compose.
   • Point to your Git Repository or paste the contents of docker-compose.yml.
2. Environment Variables: Add the following in Coolify:

   NODE_ENV=production
   PORT=3000
   POSTGRES_PASSWORD=your_custom_secure_password
   
   # SMTP Email Dispatch Settings
   SMTP_HOST=smtp.your-server.com
   SMTP_PORT=587
   SMTP_USER=alerts@networkbank.com
   SMTP_PASS=your_smtp_password
   SMTP_FROM="Balance Sheet Portal <noreply@networkbank.com>"
   SMTP_USE_TLS=true
   

3. Deploy:
   • Coolify will build the app container and spin up a dedicated postgres:16-alpine database container with health checks and persistent volume storage (balance_sheet_postgres_data). The application uses expose: "3000" to avoid host port binding conflicts while allowing Coolify's reverse proxy (Traefik/Nginx) to route external web traffic.

---

Option B: Coolify Managed PostgreSQL + Standalone App Container

If you prefer using Coolify's built-in managed PostgreSQL database resource:

1. Create Database in Coolify:
   • Click + Add Resource -> PostgreSQL.
   • Coolify will provide an internal database connection URL (e.g., postgresql://postgres:pass@coolify-postgres-host:5432/balance_sheet_db).
2. Deploy App Service:
   • Add your Git repo as a Dockerfile application.
   • Set environment variable in Coolify UI:

     DATABASE_URL=postgresql://postgres:pass@coolify-postgres-host:5432/balance_sheet_db
     PORT=3000
     
     # SMTP Email Settings
     SMTP_HOST=smtp.your-server.com
     SMTP_PORT=587
     SMTP_USER=alerts@networkbank.com
     SMTP_PASS=your_smtp_password
     

3. Deploy:
   • The Express server will automatically connect to the PostgreSQL database, create the necessary table structures on boot, and store all portal state in PostgreSQL.

---

2. Server-Side Architecture & Configuration

• Internal Container Port: Application listens on 3000 inside the container (EXPOSE 3000).
• Conflict Prevention: Uses Docker Compose expose (3000 for app, 5432 for postgres) instead of direct host port bindings to eliminate host interface port allocation conflicts.
• SMTP Environment Overrides: SMTP configuration (SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_PASS, SMTP_FROM, SMTP_USE_TLS) is fully managed via environment variables.
• Automatic Table Creation: On server boot, the backend runs initPgDatabase() to verify/create app_portal_state.
• Automatic State Recovery: If PostgreSQL contains existing data, portal state is loaded directly from PostgreSQL.
• Resilient Fallback: If DATABASE_URL is omitted, the app gracefully operates using persistent JSON storage (/app/data/portal-data.json).
• Health Check: Express exposes GET /api/health for Docker container monitoring.