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

```bash
# 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:

```bash
# 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](https://console.cloud.google.com/)
   - 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

```bash
# 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**:
```bash
# 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**:
```bash
# 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**:
```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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.