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, and financial reports.
2. Database: PostgreSQL (via pg connection pool) with automatic JSON fall-back 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
   

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).

---

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
     

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 Details

• Automatic Table Creation: On server boot, the backend runs initPgDatabase() to verify/create app_portal_state.
• Automatic State Recovery: If PostgreSQL contains existing data, the portal state is loaded directly from PostgreSQL. If empty, baseline seed data is written to 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.