vip-coordinator/DEPLOYMENT.md

🚀 VIP Coordinator - Docker Hub Deployment Guide

Deploy the VIP Coordinator application on any system with Docker in just a few steps!

📋 Prerequisites

• Docker and Docker Compose installed on your system
• Domain name (optional, can run on localhost for testing)
• Google Cloud Console account for OAuth setup

🚀 Quick Start (5 Minutes)

1. Download Deployment Files

Create a new directory and download these files:

mkdir vip-coordinator
cd vip-coordinator

# Download the deployment files
curl -O https://raw.githubusercontent.com/your-repo/vip-coordinator/main/docker-compose.yml
curl -O https://raw.githubusercontent.com/your-repo/vip-coordinator/main/.env.example

2. Configure Environment

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

# Edit the configuration (use your preferred editor)
nano .env

Required Changes in .env:

• DB_PASSWORD: Change to a secure password
• ADMIN_PASSWORD: Change to a secure password
• GOOGLE_CLIENT_ID: Your Google OAuth Client ID
• GOOGLE_CLIENT_SECRET: Your Google OAuth Client Secret

For Production Deployment:

• DOMAIN: Your domain name (e.g., mycompany.com)
• VITE_API_URL: Your API URL (e.g., https://api.mycompany.com)
• GOOGLE_REDIRECT_URI: Your callback URL (e.g., https://api.mycompany.com/auth/google/callback)
• FRONTEND_URL: Your frontend URL (e.g., https://mycompany.com)

3. Set Up Google OAuth

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the Google+ API
4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client IDs"
5. Set application type to "Web application"
6. Add authorized redirect URIs:
   • For localhost: http://localhost:3000/auth/google/callback
   • For production: https://api.your-domain.com/auth/google/callback
7. Copy the Client ID and Client Secret to your .env file

4. Deploy the Application

# Pull the latest images from Docker Hub
docker-compose pull

# Start the application
docker-compose up -d

# Check status
docker-compose ps

5. Access the Application

• Local Development: http://localhost
• Production: https://your-domain.com

🔧 Configuration Options

Environment Variables

Variable	Description	Required	Default
DB_PASSWORD	PostgreSQL database password	✅	-
ADMIN_PASSWORD	Admin interface password	✅	-
GOOGLE_CLIENT_ID	Google OAuth Client ID	✅	-
GOOGLE_CLIENT_SECRET	Google OAuth Client Secret	✅	-
GOOGLE_REDIRECT_URI	OAuth callback URL	✅	-
FRONTEND_URL	Frontend application URL	✅	-
VITE_API_URL	Backend API URL	✅	-
DOMAIN	Your domain name	❌	localhost
AVIATIONSTACK_API_KEY	Flight data API key	❌	-
PORT	Backend port	❌	3000

Ports

• Frontend: Port 80 (HTTP)
• Backend: Port 3000 (API)
• Database: Internal only (PostgreSQL)
• Redis: Internal only (Cache)

🌐 Production Deployment

With Reverse Proxy (Recommended)

For production, use a reverse proxy like Nginx or Traefik:

# Nginx configuration example
server {
    listen 80;
    server_name your-domain.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl;
    server_name your-domain.com;
    
    # SSL configuration
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:80;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

server {
    listen 443 ssl;
    server_name api.your-domain.com;
    
    # SSL configuration
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

SSL/HTTPS Setup

1. Obtain SSL certificates (Let's Encrypt recommended)
2. Configure your reverse proxy for HTTPS
3. Update your .env file with HTTPS URLs
4. Update Google OAuth redirect URIs to use HTTPS

🔍 Troubleshooting

Common Issues

1. OAuth Login Fails

• Check Google OAuth configuration
• Verify redirect URIs match exactly
• Ensure HTTPS is used in production

2. Database Connection Issues

• Check if PostgreSQL container is healthy: docker-compose ps
• Verify database password in .env

3. Frontend Can't Reach Backend

• Verify VITE_API_URL in .env matches your backend URL
• Check if backend is accessible: curl http://localhost:3000/health

4. Permission Denied Errors

• Ensure Docker has proper permissions
• Check file ownership and permissions

Viewing Logs

# View all logs
docker-compose logs

# View specific service logs
docker-compose logs backend
docker-compose logs frontend
docker-compose logs db

# Follow logs in real-time
docker-compose logs -f backend

Health Checks

# Check container status
docker-compose ps

# Check backend health
curl http://localhost:3000/health

# Check frontend
curl http://localhost/

🔄 Updates

To update to the latest version:

# Pull latest images
docker-compose pull

# Restart with new images
docker-compose up -d

🛑 Stopping the Application

# Stop all services
docker-compose down

# Stop and remove volumes (⚠️ This will delete all data)
docker-compose down -v

📊 Monitoring

Container Health

All containers include health checks:

• Backend: API endpoint health check
• Database: PostgreSQL connection check
• Redis: Redis ping check
• Frontend: Nginx status check

Logs

Logs are automatically rotated and can be viewed using Docker commands.

🔐 Security Considerations

1. Change default passwords in .env
2. Use HTTPS in production
3. Secure your server with firewall rules
4. Regular backups of database volumes
5. Keep Docker images updated

📞 Support

If you encounter issues:

1. Check the troubleshooting section above
2. Review container logs
3. Verify your configuration
4. Check GitHub issues for known problems

🎉 Success!

Once deployed, you'll have a fully functional VIP Coordinator system with:

• ✅ Google OAuth authentication
• ✅ Mobile-friendly interface
• ✅ Real-time scheduling
• ✅ User management
• ✅ Automatic backups
• ✅ Health monitoring

The first user to log in will automatically become the system administrator.