Skip to content

REVERSE_PROXY_SETUP.md

Latest commit

 

History

History
169 lines (133 loc) · 4.4 KB

REVERSE_PROXY_SETUP.md

File metadata and controls

169 lines (133 loc) · 4.4 KB
Raw

Reverse Proxy / Kong Setup Guide

This document provides configuration examples for deploying WWebJS API behind reverse proxies like Kong, Nginx, or other load balancers.

Environment Variables

The following environment variables have been added to support reverse proxy deployments:

# Base path for mounting all routes (optional)
BASE_PATH=/api/v1/whatsapp

# Enable trust proxy for proper IP forwarding (required for reverse proxy)
TRUST_PROXY=true

Kong Configuration

Basic Kong Route Setup

# Kong route configuration
routes:
  - name: wwebjs-api
    paths: ["/api/v1/whatsapp"]
    strip_path: true  # Important: removes the prefix before forwarding
    preserve_host: false
    protocols: ["http", "https"]
    service: wwebjs-service

services:
  - name: wwebjs-service
    url: http://wwebjs-api:3000
    connect_timeout: 60000
    write_timeout: 60000
    read_timeout: 60000

Kong with WebSocket Support

# Kong route for WebSocket connections
routes:
  - name: wwebjs-websocket
    paths: ["/api/v1/whatsapp/ws"]
    strip_path: true
    protocols: ["ws", "wss"]
    service: wwebjs-websocket-service

services:
  - name: wwebjs-websocket-service
    url: http://wwebjs-api:3000

Nginx Configuration

upstream wwebjs_backend {
    server wwebjs-api:3000;
}

server {
    listen 80;
    server_name api.yourdomain.com;

    location /api/v1/whatsapp/ {
        proxy_pass http://wwebjs_backend/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        
        # Timeouts for long-running operations
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

Docker Compose with Reverse Proxy

version: '3.8'

services:
  wwebjs-api:
    image: avoylenko/wwebjs-api:latest
    container_name: wwebjs-api
    restart: always
    environment:
      # Reverse proxy configuration
      - BASE_PATH=/api/v1/whatsapp
      - TRUST_PROXY=true
      
      # Other configurations
      - BASE_WEBHOOK_URL=https://api.yourdomain.com/api/v1/whatsapp/localCallbackExample
      - API_KEY=your_secure_api_key
      - ENABLE_LOCAL_CALLBACK_EXAMPLE=false
      - ENABLE_SWAGGER_ENDPOINT=true
    volumes:
      - ./sessions:/usr/src/app/sessions
    networks:
      - api-network

  nginx:
    image: nginx:alpine
    container_name: nginx-proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
    depends_on:
      - wwebjs-api
    networks:
      - api-network

networks:
  api-network:
    driver: bridge

API Endpoint Examples

With BASE_PATH=/api/v1/whatsapp configured:

Original endpoints:

  • GET /session/start/ABCD
  • GET /client/getContacts/ABCD
  • WebSocket: ws://localhost:3000/ws/ABCD

Behind reverse proxy:

  • GET https://api.yourdomain.com/api/v1/whatsapp/session/start/ABCD
  • GET https://api.yourdomain.com/api/v1/whatsapp/client/getContacts/ABCD
  • WebSocket: wss://api.yourdomain.com/api/v1/whatsapp/ws/ABCD

Important Notes

  1. Strip Path: Always configure your reverse proxy to strip the base path before forwarding to the application
  2. Trust Proxy: Set TRUST_PROXY=true to ensure proper IP detection for rate limiting
  3. WebSocket Headers: Ensure X-Forwarded-Host header is properly forwarded for WebSocket connections
  4. Timeouts: Configure appropriate timeouts for WhatsApp operations which can take time
  5. HTTPS: Use HTTPS in production and update BASE_WEBHOOK_URL accordingly

Troubleshooting

Common Issues:

  1. 404 Errors: Check if strip_path is enabled in your reverse proxy
  2. WebSocket Connection Failed: Ensure WebSocket upgrade headers are properly forwarded
  3. Rate Limiting Issues: Verify TRUST_PROXY=true is set and X-Forwarded-For header is forwarded
  4. Webhook Callbacks: Update BASE_WEBHOOK_URL to use the external domain with base path

Testing:

# Test API endpoint
curl https://api.yourdomain.com/api/v1/whatsapp/ping

# Test WebSocket connection
wscat -c wss://api.yourdomain.com/api/v1/whatsapp/ws/test