Dominion/COOLIFY.md

# Coolify Deployment & "No Available Server" Troubleshooting 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 on port `3000`.

---

## 🔧 Resolving "No Available Server" in Coolify

If Coolify displays **"No available server"** or Traefik returns a **503 / 502 error**, follow these exact fixes:

### 1. Fix Health Check Path & IPv4 Resolution (Included in codebase)
- **Cause**: Alpine Linux `wget` resolves `localhost` to IPv6 (`::1`), while Node Express binds to IPv4 (`0.0.0.0`). When `wget` fails, Docker marks the container `unhealthy`, causing Coolify Traefik to drop the container.
- **Fix**: The updated `Dockerfile` and `docker-compose.yml` use native Node.js HTTP checks against `http://127.0.0.1:3000/api/health`:
  ```bash
  node -e "require('http').get('http://127.0.0.1:3000/api/health', (r) => process.exit(r.statusCode === 200 ? 0 : 1))"
  ```
- **Coolify UI Setting**: Under your resource in Coolify -> **Health Check**:
  - **Path**: `/api/health`
  - **Port**: `3000`

### 2. Configure Exposed Port in Coolify UI
- **In Coolify Dashboard**:
  - Open your deployed application/stack.
  - Go to **Settings** -> **Exposed Port** (or **Port**).
  - Ensure the port is set to `3000`.

---

## 🚀 Deployment Methods 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. **Health Check Endpoint**: Set path to `/api/health` on port `3000`.
4. **Deploy**: Coolify builds the app and provisions `postgres:16-alpine`.

---

### Option B: Standalone Application Container (Using Coolify Managed PostgreSQL)

1. **Create PostgreSQL Resource**:
   - Click **+ Add Resource** -> **PostgreSQL**.
   - Note the database 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**: Set to `3000`.
   - In Health Check: Set path to `/api/health`.
3. **Deploy**: Express connects directly to PostgreSQL and initializes required tables automatically.