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

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

2. Environment Configuration

Create .env file:

# 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

npm ci --production

4. Run Database Migrations

Run migrations 001 through 007 in order:

# 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

# 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

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)

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