vip-coordinator/DEPLOYMENT.md

🚀 VIP Coordinator - Docker Hub Deployment Guide

📋 Quick Start

Prerequisites

• Docker and Docker Compose installed
• Google Cloud Console account (for OAuth setup)

1. Download and Configure

# Pull the project
git clone <your-dockerhub-repo-url>
cd vip-coordinator

# Copy environment template
cp .env.example .env.prod

# Edit with your configuration
nano .env.prod

2. Required Configuration

Edit .env.prod with your values:

# Database Configuration
DB_PASSWORD=your-secure-database-password

# Domain Configuration (update with your domains)
DOMAIN=your-domain.com
VITE_API_URL=https://api.your-domain.com/api

# Google OAuth Configuration (from Google Cloud Console)
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret
GOOGLE_REDIRECT_URI=https://api.your-domain.com/auth/google/callback

# Frontend URL
FRONTEND_URL=https://your-domain.com

# Admin Configuration
ADMIN_PASSWORD=your-secure-admin-password

3. Google OAuth Setup

1. Create Google Cloud Project:

   • Go to Google Cloud Console
   • Create a new project

2. Enable Google+ API:

   • Navigate to "APIs & Services" > "Library"
   • Search for "Google+ API" and enable it

3. Create OAuth Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth 2.0 Client IDs"
   • Application type: "Web application"
   • Authorized redirect URIs: https://api.your-domain.com/auth/google/callback

4. Deploy

# Start the application
docker-compose -f docker-compose.prod.yml up -d

# Check status
docker-compose -f docker-compose.prod.yml ps

# View logs
docker-compose -f docker-compose.prod.yml logs -f

5. Access Your Application

• Frontend: http://your-domain.com (or http://localhost if running locally)
• Backend API: http://api.your-domain.com (or http://localhost:3000)
• API Documentation: http://api.your-domain.com/api-docs.html

6. First Login

• Visit your frontend URL
• Click "Continue with Google"
• The first user becomes the system administrator
• Subsequent users need admin approval

🔧 Configuration Details

Environment Variables

Variable	Required	Description	Example
DB_PASSWORD	✅	PostgreSQL database password	SecurePass123!
DOMAIN	✅	Your main domain	example.com
VITE_API_URL	✅	API endpoint URL	https://api.example.com/api
GOOGLE_CLIENT_ID	✅	Google OAuth client ID	123456789-abc.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET	✅	Google OAuth client secret	GOCSPX-abcdef123456
GOOGLE_REDIRECT_URI	✅	OAuth redirect URI	https://api.example.com/auth/google/callback
FRONTEND_URL	✅	Frontend URL	https://example.com
ADMIN_PASSWORD	✅	Admin panel password	AdminPass123!

Optional Configuration

• AviationStack API Key: Configure via admin interface for flight tracking
• Custom Ports: Modify docker-compose.prod.yml if needed

🏗️ Architecture

Services

• Frontend: React app served by Nginx (Port 80)
• Backend: Node.js API server (Port 3000)
• Database: PostgreSQL with automatic schema setup
• Redis: Caching and real-time updates

Security Features

• JWT tokens with automatic key rotation (24-hour cycle)
• Non-root containers for enhanced security
• Health checks for all services
• Secure headers and CORS configuration

🔐 Security Best Practices

Required Changes

1. Change default passwords: Update DB_PASSWORD and ADMIN_PASSWORD
2. Use HTTPS: Configure SSL/TLS certificates for production
3. Secure domains: Use your own domains, not the examples
4. Google OAuth: Create your own OAuth credentials

Recommended

• Use strong, unique passwords (20+ characters)
• Enable firewall rules for your server
• Regular security updates for the host system
• Monitor logs for suspicious activity

🚨 Troubleshooting

Common Issues

OAuth Not Working:

# Check Google OAuth configuration
docker-compose -f docker-compose.prod.yml logs backend | grep -i oauth

# Verify redirect URI matches exactly in Google Console

Database Connection Error:

# Check database status
docker-compose -f docker-compose.prod.yml ps db

# View database logs
docker-compose -f docker-compose.prod.yml logs db

Frontend Can't Connect to Backend:

# Verify backend is running
curl http://localhost:3000/api/health

# Check CORS configuration
docker-compose -f docker-compose.prod.yml logs backend | grep -i cors

Health Checks

# Check all service health
docker-compose -f docker-compose.prod.yml ps

# Test API health endpoint
curl http://localhost:3000/api/health

# Test frontend
curl http://localhost/

Logs

# View all logs
docker-compose -f docker-compose.prod.yml logs

# Follow specific service logs
docker-compose -f docker-compose.prod.yml logs -f backend
docker-compose -f docker-compose.prod.yml logs -f frontend
docker-compose -f docker-compose.prod.yml logs -f db

🔄 Updates and Maintenance

Updating the Application

# Pull latest changes
git pull origin main

# Rebuild and restart
docker-compose -f docker-compose.prod.yml down
docker-compose -f docker-compose.prod.yml up -d --build

Backup Database

# Create database backup
docker-compose -f docker-compose.prod.yml exec db pg_dump -U postgres vip_coordinator > backup.sql

# Restore from backup
docker-compose -f docker-compose.prod.yml exec -T db psql -U postgres vip_coordinator < backup.sql

📚 Additional Resources

• API Documentation: Available at /api-docs.html when running
• User Roles: Administrator, Coordinator, Driver
• Flight Tracking: Configure AviationStack API key in admin panel
• Support: Check GitHub issues for common problems

🆘 Getting Help

1. Check this deployment guide
2. Review the troubleshooting section
3. Check Docker container logs
4. Verify environment configuration
5. Test with health check endpoints

---

VIP Coordinator - Streamlined VIP logistics management with modern containerized deployment.