📋 Deployment & Integration Guide

WHMCS Integration

This guide explains how the Booking Management System integrates with WHMCS for deployment.

Architecture Flow

┌─────────────┐
│   WHMCS     │ (Client purchases Booking product)
│   Portal    │
└──────┬──────┘
       │
       ├─→ Hetzner Module (creates VPS)
       │
       ├─→ Terraform Hook
       │   ├─ Provision server
       │   ├─ Install Docker
       │   └─ Setup PostgreSQL
       │
       ├─→ Ansible Playbook
       │   ├─ Clone this repo from GitLab
       │   ├─ Build Docker images
       │   ├─ Configure environment
       │   └─ Start services
       │
       └─→ GitLab CI/CD
           ├─ Run tests
           ├─ Build Docker images
           └─ Push to registry

Environment Variables Injected by WHMCS

When WHMCS triggers deployment, these variables are set:

# Identification
CUSTOMER_ID=12345                          # WHMCS Customer ID
CUSTOMER_DOMAIN=booking.theirclient.com    # Customer's domain
TENANT_ID=abc-def-123                      # Unique tenant identifier

# Database (Provisioned by Ansible)
DATABASE_URL=postgresql://user:pass@localhost/booking_12345

# Certificates (LetsEncrypt via Certbot)
SSL_CERT_PATH=/etc/letsencrypt/live/booking.theirclient.com
SSL_KEY_PATH=/etc/letsencrypt/live/booking.theirclient.com

# Stripe (Customer provides their own keys)
STRIPE_PUBLIC_KEY=pk_live_xxx
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx

# Email
ZEPTOMAIL_ACCOUNT_ID=xxx
ZEPTOMAIL_AUTH_TOKEN=xxx
ZEPTOMAIL_FROM_EMAIL=bookings@theirclient.com

# JWT
JWT_SECRET_KEY=<random generated by Ansible>
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

Docker Deployment

Images are built and tagged during CI/CD:

# Backend
registry.gitlab.inallweb.com/root/booking-management/backend:v1.0.0
registry.gitlab.inallweb.com/root/booking-management/backend:latest

# Frontend
registry.gitlab.inallweb.com/root/booking-management/frontend:v1.0.0
registry.gitlab.inallweb.com/root/booking-management/frontend:latest

Terraform Variables

Terraform receives:

variable "customer_id" {
  description = "WHMCS Customer ID"
  type        = string
}

variable "domain" {
  description = "Customer domain for booking service"
  type        = string
}

variable "backend_image" {
  description = "Backend Docker image URI"
  type        = string
}

variable "frontend_image" {
  description = "Frontend Docker image URI"
  type        = string
}

Ansible Playbook Tasks

1. Provision host

   • Install Docker & Docker Compose
   • Install PostgreSQL
   • Configure firewall

2. Deploy application

   • Clone this repository
   • Create .env from template with WHMCS variables
   • Pull Docker images from registry
   • Run docker-compose

3. Setup SSL

   • Generate LetsEncrypt certificate
   • Configure Nginx reverse proxy
   • Auto-renewal via certbot

4. Health checks

   • Verify backend is responding
   • Verify frontend loads
   • Check database connectivity
   • Validate Stripe integration

Local Development with WHMCS Variables

To test locally with WHMCS-like variables:

# Copy example env
cp .env.example .env

# Edit with test values
cat > .env << EOF
CUSTOMER_ID=test-123
CUSTOMER_DOMAIN=booking.local
TENANT_ID=tenant-abc-123
DATABASE_URL=sqlite:///./booking.db
STRIPE_PUBLIC_KEY=pk_test_xxx
STRIPE_SECRET_KEY=sk_test_xxx
ZEPTOMAIL_ACCOUNT_ID=test
ZEPTOMAIL_AUTH_TOKEN=test
EOF

# Run with docker-compose
docker-compose up

Troubleshooting

Container won't start

# Check logs
docker-compose logs backend

# Verify environment
docker-compose exec backend env | grep DATABASE_URL

# Test database connection
docker-compose exec backend python -c \
  "from src.booking_db import Base, engine; Base.metadata.create_all(bind=engine); print('OK')"

Frontend can't reach backend

# Verify both are running
docker-compose ps

# Check network
docker network ls
docker network inspect booking-management_default

# Test connectivity
docker-compose exec frontend curl http://backend:8000/health

Database migration issues

# Reset database (WARNING: loses data)
docker-compose exec postgres psql -U booking -c "DROP DATABASE booking_system;"
docker-compose exec postgres psql -U booking -c "CREATE DATABASE booking_system;"

# Recreate tables
docker-compose exec backend python -c \
  "from src.booking_db import Base, engine; Base.metadata.create_all(bind=engine)"

Manual Deployment (Without WHMCS)

For testing or standalone deployment:

# 1. Clone repository
git clone git@gitlab.inallweb.com:root/booking-management.git
cd booking-management

# 2. Setup environment
cp .env.example .env
# Edit .env with your values

# 3. Start services
docker-compose up -d

# 4. Verify
curl http://localhost:8000/health  # Backend
open http://localhost:3000          # Frontend

Production Considerations

• ✅ Use PostgreSQL (not SQLite)
• ✅ Configure SSL certificates
• ✅ Set strong JWT_SECRET_KEY
• ✅ Use Stripe live keys only in production
• ✅ Enable logging to file/ELK stack
• ✅ Setup automated backups
• ✅ Monitor container health
• ✅ Configure rate limiting
• ✅ Use strong database passwords
• ✅ Enable CORS properly