drone-detector/DOMAIN_MIGRATION_GUIDE.md

# Complete Domain Migration Process for Multi-Tenant Setup

## Overview
This guide walks you through migrating from your current domain to `dev.uggla.uamils.com` with full multi-tenant support and SSL certificates.

## Prerequisites
- Server with Docker and Docker Compose
- Domain access for DNS configuration
- Access to your current drone detection system

## Phase 1: DNS Configuration (Do this first!)

### Step 1: Set up DNS Records
```bash
# In your DNS provider (Cloudflare, Route53, etc.), add:

# Main domain A record
dev.uggla.uamils.com    A    [YOUR_SERVER_IP]

# Wildcard CNAME record for all subdomains
*.dev.uggla.uamils.com  CNAME  dev.uggla.uamils.com

# Wait for DNS propagation (can take up to 48 hours)
# Test with: dig dev.uggla.uamils.com
# Test wildcard: dig test.dev.uggla.uamils.com
```

### Step 2: Verify DNS Propagation
```bash
# Test main domain
nslookup dev.uggla.uamils.com

# Test subdomain
nslookup tenant1.dev.uggla.uamils.com

# Both should resolve to your server IP
```

## Phase 2: Update Configuration Files

### Step 3: Copy and Configure Environment
```bash
# On your server, copy the environment template
cp .env.production .env

# Edit the .env file with your specific values:
nano .env

# Update these critical values:
BASE_URL=https://dev.uggla.uamils.com
DOMAIN_NAME=dev.uggla.uamils.com
SSL_EMAIL=your-email@uamils.com
SESSION_SECRET=generate-a-32-character-random-string
JWT_SECRET=generate-another-random-string
```

### Step 4: Database Migration
```bash
# First, stop current containers
docker-compose down

# Run the database migration to add multi-tenant support
docker-compose run --rm backend npm run db:migrate

# This creates the tenants table and updates user schema
```

## Phase 3: SSL Certificate Setup

### Step 5: Generate SSL Certificates
```bash
# Make the SSL setup script executable
chmod +x ./scripts/setup-ssl.sh

# Run the SSL setup (this will be interactive)
./scripts/setup-ssl.sh

# IMPORTANT: During this process, you'll need to:
# 1. Add DNS TXT records when prompted
# 2. Wait for DNS propagation between records
# 3. Complete the manual verification process
```

### Step 6: Manual DNS TXT Record Process
```bash
# When certbot prompts you, you'll see something like:
# Please add the following TXT record to your DNS:
# Name: _acme-challenge.dev.uggla.uamils.com
# Value: abcd1234...

# Add this TXT record in your DNS provider:
_acme-challenge.dev.uggla.uamils.com  TXT  "abcd1234efgh5678..."

# For wildcard, you'll get a second record:
_acme-challenge.dev.uggla.uamils.com  TXT  "ijkl9012mnop3456..."

# IMPORTANT: You need BOTH TXT records for wildcard certificates
# Wait 5-10 minutes for DNS propagation before pressing Enter in certbot
```

## Phase 4: Production Deployment

### Step 7: Start Production Environment
```bash
# Start the production environment with SSL
docker-compose -f docker-compose.production.yml up -d

# Check logs to ensure everything starts correctly
docker-compose -f docker-compose.production.yml logs -f
```

### Step 8: Verify SSL and Multi-Tenant Setup
```bash
# Test main domain
curl -I https://dev.uggla.uamils.com

# Test API endpoint
curl -I https://dev.uggla.uamils.com/api/health

# Test tenant subdomain
curl -I https://tenant1.dev.uggla.uamils.com

# All should return 200 OK with SSL certificates
```

## Phase 5: Configure Tenants

### Step 9: Create Default Tenant
```bash
# Access the backend container
docker-compose -f docker-compose.production.yml exec backend sh

# Create default tenant (run this inside container)
node -e "
const { Tenant } = require('./models');
Tenant.create({
  name: 'Default Tenant',
  subdomain: 'app',
  domain: 'dev.uggla.uamils.com',
  is_active: true,
  auth_config: {
    providers: ['local'],
    local: { enabled: true }
  }
}).then(tenant => {
  console.log('Default tenant created:', tenant.toJSON());
  process.exit(0);
}).catch(err => {
  console.error('Error:', err);
  process.exit(1);
});
"
```

### Step 10: Create Additional Tenants
```bash
# Example: Create a tenant for subdomain 'acme'
# This would be accessible at: https://acme.dev.uggla.uamils.com

node -e "
const { Tenant } = require('./models');
Tenant.create({
  name: 'ACME Corporation',
  subdomain: 'acme',
  domain: 'dev.uggla.uamils.com',
  is_active: true,
  subscription_tier: 'enterprise',
  auth_config: {
    providers: ['local', 'saml'],
    local: { enabled: true },
    saml: {
      enabled: true,
      entryPoint: 'https://acme.com/saml/sso',
      issuer: 'acme-drone-detection',
      cert: '-----BEGIN CERTIFICATE-----...'
    }
  }
}).then(tenant => {
  console.log('ACME tenant created:', tenant.toJSON());
  process.exit(0);
});
"
```

## Phase 6: Update Frontend Configuration

### Step 11: Update React App Configuration
```bash
# Update your client environment variables
# Create client/.env.production

REACT_APP_API_URL=https://dev.uggla.uamils.com/api
REACT_APP_SOCKET_URL=https://dev.uggla.uamils.com
REACT_APP_MULTI_TENANT=true
REACT_APP_DEFAULT_TENANT=app

# Rebuild frontend with new configuration
docker-compose -f docker-compose.production.yml build frontend
```

## Phase 7: Set Up Monitoring and Maintenance

### Step 12: Configure Certificate Auto-Renewal
```bash
# Add to crontab for automatic renewal every 12 hours
# Edit crontab: crontab -e

# Add this line:
0 0,12 * * * cd /path/to/your/project && ./scripts/renew-certs.sh >/dev/null 2>&1
```

### Step 13: Set Up Monitoring
```bash
# Test SSL certificate expiry
echo | openssl s_client -servername dev.uggla.uamils.com -connect dev.uggla.uamils.com:443 2>/dev/null | openssl x509 -noout -dates

# Set up monitoring script
cat > ./scripts/monitor.sh << 'EOF'
#!/bin/bash
# Check if services are running
docker-compose -f docker-compose.production.yml ps

# Check SSL certificate validity
echo "Checking SSL certificate..."
echo | openssl s_client -servername dev.uggla.uamils.com -connect dev.uggla.uamils.com:443 2>/dev/null | openssl x509 -noout -dates

# Test API health
curl -f https://dev.uggla.uamils.com/api/health || echo "API health check failed"
EOF

chmod +x ./scripts/monitor.sh
```

## Phase 8: Migration Verification Checklist

### Step 14: Complete Verification
- [ ] DNS resolves correctly for main domain and wildcard
- [ ] SSL certificates are valid and trusted
- [ ] Main application loads at https://dev.uggla.uamils.com
- [ ] Default tenant works at https://app.dev.uggla.uamils.com
- [ ] API endpoints respond correctly
- [ ] WebSocket/Socket.IO connections work
- [ ] Database migration completed successfully
- [ ] Multi-tenant authentication flows work
- [ ] SSL auto-renewal is configured

### Step 15: Update Documentation and Users
- [ ] Update any hardcoded URLs in your application
- [ ] Notify users of the domain change
- [ ] Update any external integrations
- [ ] Update monitoring/alerting systems
- [ ] Update backup scripts if they reference the old domain

## Troubleshooting Common Issues

### SSL Certificate Issues
```bash
# If certificate generation fails:
# 1. Check DNS TXT records are properly set
# 2. Wait for DNS propagation (up to 24 hours)
# 3. Try staging certificates first (STAGING=1 in setup-ssl.sh)

# Debug DNS TXT records:
dig TXT _acme-challenge.dev.uggla.uamils.com

# Check certificate details:
openssl x509 -in ./certbot/conf/live/dev.uggla.uamils.com/fullchain.pem -text -noout
```

### Multi-Tenant Routing Issues
```bash
# Check Nginx configuration syntax:
docker-compose -f docker-compose.production.yml exec nginx nginx -t

# Check Nginx logs:
docker-compose -f docker-compose.production.yml logs nginx

# Test tenant detection:
curl -H "Host: tenant1.dev.uggla.uamils.com" https://dev.uggla.uamils.com/api/health
```

### Database Connection Issues
```bash
# Check database logs:
docker-compose -f docker-compose.production.yml logs postgres

# Test database connection:
docker-compose -f docker-compose.production.yml exec backend npm run db:migrate

# Check if tenants table exists:
docker-compose -f docker-compose.production.yml exec postgres psql -U postgres -d drone_detection -c "\dt"
```

## Security Considerations

1. **Strong Secrets**: Ensure JWT_SECRET and SESSION_SECRET are cryptographically secure
2. **Rate Limiting**: Configure appropriate rate limits in Nginx
3. **CORS**: Restrict CORS origins to your specific domains
4. **Firewall**: Configure server firewall to only allow necessary ports (80, 443, 22)
5. **Database**: Restrict database access to backend containers only
6. **Monitoring**: Set up log monitoring for security events

## Rollback Plan

If you need to rollback:
1. Update DNS to point back to old domain
2. Restart old environment with original configuration
3. Database should remain compatible (migrations are additive)
4. Wait for DNS propagation

This completes the domain migration process!