freightdesk/DEPLOYMENT.md

# FreightDesk — Deployment Guide

## Prerequisites

- Ubuntu 22.04+ VPS (minimum 2GB RAM, 2 vCPU)
- Domain pointed to VPS IP
- Coolify installed (or Docker + Docker Compose)
- Supabase project (self-hosted or cloud)

## Quick Start

### 1. Clone Repository

```bash
git clone http://forgejo-vil3xyowqk0qsh4hiqy77e3h.187.127.178.110.sslip.io/iamcoolvivek007/freightdesk.git
cd freightdesk/webapp
```

### 2. Environment Configuration

Create `.env` file:

```env
# Server
NODE_ENV=production
PORT=3000

# Supabase
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-role-key
SUPABASE_ANON_KEY=your-anon-key

# Session
SESSION_SECRET=generate-a-random-64-char-string-here
SESSION_MAX_AGE=86400000

# WhatsApp (optional — for receiving messages)
WHATSAPP_WEBHOOK_TOKEN=your-webhook-verify-token

# Payment Gateway (production)
RAZORPAY_KEY_ID=rzk_live_xxxxx
RAZORPAY_KEY_SECRET=xxxxx

# Email (optional — for notifications)
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
```

### 3. Install Dependencies

```bash
npm ci --production
```

### 4. Run Database Migrations

Run migrations 001 through 007 in order:

```bash
# Using Supabase CLI
supabase db push

# Or manually via SQL editor:
# Copy contents of supabase/migrations/001_initial_schema.sql and run
# Copy contents of supabase/migrations/002_whatsapp_parser.sql and run
# ... through 007_location_tracking.sql
```

### 5. Create Admin User

Visit `/setup` in your browser and create the admin account.

### 6. Start the Server

```bash
# Development
npm run dev

# Production
NODE_ENV=production node src/server.js
```

### 7. Coolify Deployment (Recommended)

1. In Coolify, create new application
2. Connect to your Forgejo repository
3. Set buildpack: `Dockerfile`
4. Set Dockerfile path: `/webapp/Dockerfile`
5. Add environment variables from `.env`
6. Set domain and enable SSL

## Docker

```bash
cd webapp
docker build -t freightdesk .
docker run -d \
  --name freightdesk \
  -p 3000:3000 \
  --env-file .env \
  --restart unless-stopped \
  freightdesk
```

## Docker Compose (Full Stack)

```yaml
version: '3.8'
services:
  app:
    build: ./webapp
    ports:
      - "3000:3000"
    env_file: .env
    restart: unless-stopped
    depends_on:
      - supabase

  # If self-hosting Supabase
  supabase:
    image: supabase/supabase-local:latest
    ports:
      - "5432:5432"    # PostgreSQL
      - "8000:8000"    # REST API
      - "4000:4000"    # Studio
    volumes:
      - supabase-data:/var/lib/supabase
    restart: unless-stopped

volumes:
  supabase-data:
```

## Post-Deployment Checklist

- [ ] Run all 7 migrations (001-007)
- [ ] Create admin account via /setup
- [ ] Configure SSL certificate
- [ ] Set up automated backups (Supabase: daily DB dump)
- [ ] Configure Coolify webhooks for auto-deploy on git push
- [ ] Set up monitoring (Prometheus /metrics endpoint at :3000/metrics)
- [ ] Configure Pino log aggregation
- [ ] Test WhatsApp parser with sample messages
- [ ] Test registration flow (shipper + driver)
- [ ] Test marketplace: post load → bid → accept
- [ ] Test payment escrow: deposit → hold → release → payout

## Migrations Summary

| # | File | What it adds |
|---|------|-------------|
| 001 | `001_initial_schema.sql` | Core tables: loads, shippers, vehicles, payments, users |
| 002 | `002_whatsapp_parser.sql` | Parser config, city list, known shippers |
| 003 | `003_soft_delete.sql` | Soft-delete columns on all tables |
| 004 | `004_audit_logging.sql` | Audit log table + triggers |
| 005 | `005_saas_marketplace.sql` | Bids, negotiations, ratings, notifications, marketplace fields |
| 006 | `006_payment_escrow.sql` | Escrow accounts, transactions, payouts, disputes |
| 007 | `007_location_tracking.sql` | Vehicle GPS location history |

## Troubleshooting

### App won't start
- Check `.env` has all required variables
- Verify Supabase connection: `curl $SUPABASE_URL/rest/v1/`
- Check logs: `docker logs freightdesk`

### Database errors
- Run migrations in order (001 → 007)
- Check Supabase service key has proper permissions
- Verify `pgcrypto` extension is enabled (for UUID generation)

### WhatsApp parser not working
- Ensure migration 002 ran (populates CITIES and parser config)
- Test via `/api/parser/test` endpoint

### Payment flow fails
- Ensure migration 006 ran
- Check escrow_accounts table exists
- Verify platform_config has default values

## Architecture

```
                          ┌─────────────────────┐
                          │   Nginx / Coolify   │
                          │     (SSL + Proxy)   │
                          └──────────┬──────────┘
                                     │
                          ┌──────────▼──────────┐
                          │   Node.js + Express  │
                          │   FreightDesk App    │
                          │   Port 3000          │
                          └──┬──────┬──────┬────┘
                             │      │      │
              ┌──────────────┘      │      └──────────────┐
              ▼                     ▼                     ▼
    ┌──────────────┐    ┌──────────────┐    ┌──────────────┐
    │  EJS Views   │    │  REST API    │    │  Supabase    │
    │  (templates) │    │  /api/*      │    │  PostgreSQL  │
    │  + Recharts  │    │  JSON        │    │  + Realtime  │
    │  CDN widgets │    │              │    │              │
    └──────────────┘    └──────────────┘    └──────────────┘

Routes:
  /              → Public landing page
  /login         → Admin login
  /setup         → Initial admin setup
  /dashboard     → Admin dashboard (EJS + Recharts)
  /loads         → Load management (admin)
  /shippers      → Shipper management
  /vehicles      → Vehicle management
  /payments      → Payment tracking
  /reports       → Reports
  /audit-logs    → Audit log viewer
  /invoices      → Invoice PDF generation
  /admin/moderation → User verification, payouts, disputes
  
  /register/shipper → Shipper self-registration
  /register/driver  → Driver self-registration
  /portal/*         → Shipper/driver portal (dashboard, loads, trips)
  
  /marketplace      → Browse/post loads, bidding
  /escrow           → Deposits, payouts, disputes
  
  /api/*            → REST API (JSON)
  /metrics          → Prometheus metrics
  /health           → Health check
```

## Support

- Forgejo: `http://forgejo-vil3xyowqk0qsh4hiqy77e3h.187.127.178.110.sslip.io/iamcoolvivek007/freightdesk`
- Issues: Create on Forgejo