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 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
   HOST_PORT=8080             # Customize if host port 3000 is occupied by another app
   POSTGRES_HOST_PORT=5433    # Customize if host port 5432 is occupied by another database
   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 & Port Configuration

• Internal Container Port: Application listens on 3000 inside the container.
• Conflict Prevention: Host port mappings in docker-compose.yml use ${HOST_PORT:-8080}:3000 and ${POSTGRES_HOST_PORT:-5433}:5432. If port 3000 or 5432 is already used by another app on your server, simply set HOST_PORT or POSTGRES_HOST_PORT in your .env to any available port (e.g. 8080, 8081, 5433).
• 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.