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:
   ```env
   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:
     ```env
     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.