Dominion/COOLIFY.md

Coolify Deployment & Port Allocation Fixes

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 on port 3000.

---

🛑 Resolving "Bind for 0.0.0.0:3000 failed: port is already allocated"

Cause of the Error

When deploying in Coolify or a multi-container Docker host, port 3000 on the host machine is frequently already taken by Coolify's internal service, another app, or a reverse proxy. Explicitly binding host port 3000:3000 causes Docker daemon to crash with: Error response from daemon: Bind for 0.0.0.0:3000 failed: port is already allocated

How It Is Fixed in This Repository

In docker-compose.yml, direct host port binding (ports: - "3000:3000") has been replaced with container exposure (expose: - "3000").

Coolify's Traefik reverse proxy routes external web traffic directly into the container on port 3000 via Docker's internal container network. No host port allocation is required!

---

🔧 Coolify UI Configuration Steps

1. Set Container / Destination Port:
   • In Coolify UI under Settings -> Port or Destination Port: Set to 3000.
2. Set Health Check:
   • Path: /api/health
   • Port: 3000
   • Type: HTTP or Docker native check

---

🚀 Quick Deployment Options in Coolify

Option A: Docker Compose Deployment (App + Dedicated PostgreSQL)

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

   NODE_ENV=production
   PORT=3000
   POSTGRES_PASSWORD=your_custom_secure_password
   
   # SMTP Email Settings (Optional)
   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 builds the app container (exposing port 3000) and provisions postgres:16-alpine.

---

Option B: Standalone Application Container (Coolify Managed PostgreSQL)

1. Create PostgreSQL Resource:
   • Click + Add Resource -> PostgreSQL.
   • Note internal connection string (e.g. postgresql://postgres:pass@postgres-host:5432/balance_sheet_db).
2. Create Dockerfile Application:
   • Add Git Repository as a Dockerfile Application.
   • Set Environment Variables:

     NODE_ENV=production
     PORT=3000
     DATABASE_URL=postgresql://postgres:pass@postgres-host:5432/balance_sheet_db
     

   • In Settings -> Exposed Port / Container Port: Set to 3000.
   • In Health Check: Set path to /api/health.
3. Deploy: Express connects directly to PostgreSQL and initializes required tables automatically.