Backup: 2025-06-07 18:32 - Production setup complete
[Restore from backup: vip-coordinator-backup-2025-06-07-18-32-production-setup-complete]
This commit is contained in:
314
SETUP_GUIDE.md
Normal file
314
SETUP_GUIDE.md
Normal file
@@ -0,0 +1,314 @@
|
||||
# VIP Coordinator Setup Guide
|
||||
|
||||
A comprehensive guide to set up and run the VIP Coordinator system.
|
||||
|
||||
## 🚀 Quick Start
|
||||
|
||||
### Prerequisites
|
||||
- Docker and Docker Compose
|
||||
- Google Cloud Console account (for OAuth)
|
||||
|
||||
### 1. Clone and Start
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd vip-coordinator
|
||||
make dev
|
||||
```
|
||||
|
||||
The application will be available at:
|
||||
- **Frontend**: http://localhost:5173
|
||||
- **Backend API**: http://localhost:3000
|
||||
- **API Documentation**: http://localhost:3000/api-docs.html
|
||||
|
||||
### 2. Google OAuth Setup (Required)
|
||||
|
||||
1. **Create Google Cloud Project**:
|
||||
- Go to [Google Cloud Console](https://console.cloud.google.com/)
|
||||
- Create a new project or select existing one
|
||||
|
||||
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: `http://localhost:3000/auth/google/callback`
|
||||
|
||||
4. **Configure Environment**:
|
||||
```bash
|
||||
# Copy the example environment file
|
||||
cp backend/.env.example backend/.env
|
||||
|
||||
# Edit backend/.env and add your Google OAuth credentials:
|
||||
GOOGLE_CLIENT_ID=your-client-id-here
|
||||
GOOGLE_CLIENT_SECRET=your-client-secret-here
|
||||
```
|
||||
|
||||
5. **Restart the Application**:
|
||||
```bash
|
||||
make dev
|
||||
```
|
||||
|
||||
### 3. First Login
|
||||
- Visit http://localhost:5173
|
||||
- Click "Continue with Google"
|
||||
- The first user to log in becomes the system administrator
|
||||
- Subsequent users need administrator approval
|
||||
|
||||
## 🏗️ Architecture Overview
|
||||
|
||||
### Authentication System
|
||||
- **JWT-based authentication** with Google OAuth
|
||||
- **Role-based access control**: Administrator, Coordinator, Driver
|
||||
- **User approval system** for new registrations
|
||||
- **Simple setup** - no complex OAuth configurations needed
|
||||
|
||||
### Database
|
||||
- **PostgreSQL** for persistent data storage
|
||||
- **Automatic schema initialization** on first run
|
||||
- **User management** with approval workflows
|
||||
- **VIP and driver data** with scheduling
|
||||
|
||||
### API Structure
|
||||
- **RESTful API** with comprehensive endpoints
|
||||
- **OpenAPI/Swagger documentation** at `/api-docs.html`
|
||||
- **Role-based endpoint protection**
|
||||
- **Real-time flight tracking** integration
|
||||
|
||||
## 📋 Features
|
||||
|
||||
### Current Features
|
||||
- ✅ **User Management**: Google OAuth with role-based access
|
||||
- ✅ **VIP Management**: Create, edit, track VIPs with flight information
|
||||
- ✅ **Driver Coordination**: Manage drivers and assignments
|
||||
- ✅ **Flight Tracking**: Real-time flight status updates
|
||||
- ✅ **Schedule Management**: Event scheduling with conflict detection
|
||||
- ✅ **Department Support**: Office of Development and Admin departments
|
||||
- ✅ **API Documentation**: Interactive Swagger UI
|
||||
|
||||
### User Roles
|
||||
- **Administrator**: Full system access, user management
|
||||
- **Coordinator**: VIP and driver management, scheduling
|
||||
- **Driver**: View assigned schedules (planned)
|
||||
|
||||
## 🔧 Configuration
|
||||
|
||||
### Environment Variables
|
||||
```bash
|
||||
# Database
|
||||
DATABASE_URL=postgresql://vip_user:vip_password@db:5432/vip_coordinator
|
||||
|
||||
# Authentication
|
||||
GOOGLE_CLIENT_ID=your-google-client-id
|
||||
GOOGLE_CLIENT_SECRET=your-google-client-secret
|
||||
JWT_SECRET=your-jwt-secret-key
|
||||
|
||||
# External APIs (Optional)
|
||||
AVIATIONSTACK_API_KEY=your-aviationstack-key
|
||||
|
||||
# Application
|
||||
FRONTEND_URL=http://localhost:5173
|
||||
PORT=3000
|
||||
```
|
||||
|
||||
### Docker Services
|
||||
- **Frontend**: React + Vite development server
|
||||
- **Backend**: Node.js + Express API server
|
||||
- **Database**: PostgreSQL with automatic initialization
|
||||
- **Redis**: Caching and real-time updates
|
||||
|
||||
## 🛠️ Development
|
||||
|
||||
### Available Commands
|
||||
```bash
|
||||
# Start development environment
|
||||
make dev
|
||||
|
||||
# View logs
|
||||
make logs
|
||||
|
||||
# Stop all services
|
||||
make down
|
||||
|
||||
# Rebuild containers
|
||||
make build
|
||||
|
||||
# Backend only
|
||||
cd backend && npm run dev
|
||||
|
||||
# Frontend only
|
||||
cd frontend && npm run dev
|
||||
```
|
||||
|
||||
### API Testing
|
||||
- **Interactive Documentation**: http://localhost:3000/api-docs.html
|
||||
- **Health Check**: http://localhost:3000/api/health
|
||||
- **Authentication Test**: Use the "Try it out" feature in Swagger UI
|
||||
|
||||
## 🔐 Security
|
||||
|
||||
### Authentication Flow
|
||||
1. User clicks "Continue with Google"
|
||||
2. Redirected to Google OAuth
|
||||
3. Google redirects back with authorization code
|
||||
4. Backend exchanges code for user info
|
||||
5. JWT token generated and returned
|
||||
6. Frontend stores token for API requests
|
||||
|
||||
### API Protection
|
||||
- All API endpoints require valid JWT token
|
||||
- Role-based access control on sensitive operations
|
||||
- User approval system for new registrations
|
||||
|
||||
## 📚 API Documentation
|
||||
|
||||
### Key Endpoints
|
||||
- **Authentication**: `/auth/*` - OAuth and user management
|
||||
- **VIPs**: `/api/vips/*` - VIP management and scheduling
|
||||
- **Drivers**: `/api/drivers/*` - Driver management and availability
|
||||
- **Flights**: `/api/flights/*` - Flight tracking and information
|
||||
- **Admin**: `/api/admin/*` - System administration
|
||||
|
||||
### Interactive Documentation
|
||||
Visit http://localhost:3000/api-docs.html for:
|
||||
- Complete API reference
|
||||
- Request/response examples
|
||||
- "Try it out" functionality
|
||||
- Schema definitions
|
||||
|
||||
## 🚨 Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
**OAuth Not Working**:
|
||||
- Verify Google Client ID and Secret in `.env`
|
||||
- Check redirect URI in Google Console matches exactly
|
||||
- Ensure Google+ API is enabled
|
||||
|
||||
**Database Connection Error**:
|
||||
- Verify Docker containers are running: `docker ps`
|
||||
- Check database logs: `docker-compose logs db`
|
||||
- Restart services: `make down && make dev`
|
||||
|
||||
**Frontend Can't Connect to Backend**:
|
||||
- Verify backend is running on port 3000
|
||||
- Check CORS configuration in backend
|
||||
- Ensure FRONTEND_URL is set correctly
|
||||
|
||||
### Getting Help
|
||||
1. Check the interactive API documentation
|
||||
2. Review Docker container logs
|
||||
3. Verify environment configuration
|
||||
4. Test with the health check endpoint
|
||||
|
||||
## 🔄 Production Deployment
|
||||
|
||||
### Prerequisites for Production
|
||||
|
||||
1. **Domain Setup**: Ensure your domains are configured:
|
||||
- Frontend: `https://bsa.madeamess.online`
|
||||
- API: `https://api.bsa.madeamess.online`
|
||||
|
||||
2. **SSL Certificates**: Configure SSL/TLS certificates for your domains
|
||||
|
||||
3. **Environment Configuration**: Copy and configure production environment:
|
||||
```bash
|
||||
cp .env.production .env.prod
|
||||
# Edit .env.prod with your secure values
|
||||
```
|
||||
|
||||
### Production Deployment Steps
|
||||
|
||||
1. **Configure Environment Variables**:
|
||||
```bash
|
||||
# Edit .env.prod with secure values:
|
||||
# - Change DB_PASSWORD to a strong password
|
||||
# - Generate new JWT_SECRET and SESSION_SECRET
|
||||
# - Update ADMIN_PASSWORD
|
||||
# - Set your AVIATIONSTACK_API_KEY
|
||||
```
|
||||
|
||||
2. **Deploy with Production Configuration**:
|
||||
```bash
|
||||
# Load production environment
|
||||
export $(cat .env.prod | xargs)
|
||||
|
||||
# Build and start production containers
|
||||
docker-compose -f docker-compose.prod.yml up -d --build
|
||||
```
|
||||
|
||||
3. **Verify Deployment**:
|
||||
```bash
|
||||
# Check container status
|
||||
docker-compose -f docker-compose.prod.yml ps
|
||||
|
||||
# View logs
|
||||
docker-compose -f docker-compose.prod.yml logs
|
||||
```
|
||||
|
||||
### Production vs Development Differences
|
||||
|
||||
| Feature | Development | Production |
|
||||
|---------|-------------|------------|
|
||||
| Build Target | `development` | `production` |
|
||||
| Source Code | Volume mounted (hot reload) | Built into image |
|
||||
| Database Password | Hardcoded `changeme` | Environment variable |
|
||||
| Frontend Server | Vite dev server (port 5173) | Nginx (port 80) |
|
||||
| API URL | `http://localhost:3000/api` | `https://api.bsa.madeamess.online/api` |
|
||||
| SSL/HTTPS | Not configured | Required |
|
||||
| Restart Policy | Manual | `unless-stopped` |
|
||||
|
||||
### Production Environment Variables
|
||||
|
||||
```bash
|
||||
# Database Configuration
|
||||
DB_PASSWORD=your-secure-database-password-here
|
||||
|
||||
# Domain Configuration
|
||||
DOMAIN=bsa.madeamess.online
|
||||
VITE_API_URL=https://api.bsa.madeamess.online/api
|
||||
|
||||
# Authentication Configuration (Generate new secure keys)
|
||||
JWT_SECRET=your-super-secure-jwt-secret-key-change-in-production-12345
|
||||
SESSION_SECRET=your-super-secure-session-secret-change-in-production-67890
|
||||
|
||||
# Google OAuth Configuration
|
||||
GOOGLE_CLIENT_ID=308004695553-6k34bbq22frc4e76kejnkgq8mncepbbg.apps.googleusercontent.com
|
||||
GOOGLE_CLIENT_SECRET=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
|
||||
GOOGLE_REDIRECT_URI=https://api.bsa.madeamess.online/auth/google/callback
|
||||
|
||||
# Frontend URL
|
||||
FRONTEND_URL=https://bsa.madeamess.online
|
||||
|
||||
# Flight API Configuration
|
||||
AVIATIONSTACK_API_KEY=your-aviationstack-api-key
|
||||
|
||||
# Admin Configuration
|
||||
ADMIN_PASSWORD=your-secure-admin-password
|
||||
|
||||
# Port Configuration
|
||||
PORT=3000
|
||||
```
|
||||
|
||||
### Production-Specific Troubleshooting
|
||||
|
||||
**SSL Certificate errors**: Ensure certificates are properly configured
|
||||
**Domain resolution**: Verify DNS settings for your domains
|
||||
**Environment variables**: Check that all required variables are set in `.env.prod`
|
||||
**Firewall**: Ensure ports 80, 443, 3000 are accessible
|
||||
|
||||
### Production Logs
|
||||
|
||||
```bash
|
||||
# View production container logs
|
||||
docker-compose -f docker-compose.prod.yml logs backend
|
||||
docker-compose -f docker-compose.prod.yml logs frontend
|
||||
docker-compose -f docker-compose.prod.yml logs db
|
||||
|
||||
# Follow logs in real-time
|
||||
docker-compose -f docker-compose.prod.yml logs -f
|
||||
```
|
||||
|
||||
This setup guide reflects the current simple, effective architecture of the VIP Coordinator system with production-ready deployment capabilities.
|
||||
Reference in New Issue
Block a user