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