Deployment Guide

Deployment Guide

This guide covers deploying the 8531 TeamSite to various environments, managing configurations, and understanding the deployment architecture.

🌐 Environment Architecture

Environments

• Production: https://team.8531.ca - Main production site
• Development: https://dev.team.8531.ca - Staging and preview deployments
• Local: http://localhost:4321 - Local development environment

Environment Detection

The application automatically detects its environment and configures:

• Site URLs: Production, development, or local URLs
• Auth Callbacks: Environment-specific OAuth redirect URLs
• CORS Policies: Proper cross-origin request handling
• Security Headers: Production-appropriate security measures

🚀 Vercel Deployment

The project is configured for Vercel deployment with zero-downtime deployment strategy.

Vercel Configuration

The vercel.json file includes:

• Serverless function configuration for API endpoints
• Security headers for all routes
• CORS configuration for API routes
• Environment variable settings

{
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "installCommand": "npm install",
  "devCommand": "npm run dev",
  "functions": {
    "src/pages/api/**/*.ts": {
      "runtime": "nodejs18.x"
    }
  },
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        {
          "key": "X-Frame-Options",
          "value": "DENY"
        },
        {
          "key": "X-Content-Type-Options",
          "value": "nosniff"
        }
      ]
    },
    {
      "source": "/api/(.*)",
      "headers": [
        {
          "key": "Access-Control-Allow-Origin",
          "value": "https://team.8531.ca"
        },
        {
          "key": "Access-Control-Allow-Methods",
          "value": "GET, POST, PUT, DELETE, OPTIONS"
        }
      ]
    }
  ]
}

Setting Up Vercel

1. Install Vercel CLI

   npm i -g vercel

2. Login to Vercel

   vercel login

3. Link Project

   vercel link

4. Configure Environment Variables

   vercel env add

5. Deploy

   vercel --prod

Automatic Deployment

The project supports automatic deployment:

• Main Branch: Deploys to production
• Pull Requests: Creates preview deployments
• Push to Main: Triggers production deployment

🔧 Environment Configuration

Production Environment Variables

Configure these in Vercel dashboard or CLI:

Required Variables

NODE_ENV=production
SITE_URL=https://team.8531.ca
AUTH_GATEWAY_URL=https://auth.8531.ca
JWT_SECRET=your-production-jwt-secret
JWT_ISSUER=https://auth.8531.ca
JWT_AUDIENCE=8531-apps

Optional Variables

# Google Drive Integration
GOOGLE_SERVICE_ACCOUNT_EMAIL=[email protected]
GOOGLE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour-private-key\n-----END PRIVATE KEY-----"

# Logging
LOG_LEVEL=warn

# Analytics (if used)
ANALYTICS_ID=your-analytics-id

Development Environment

For dev.team.8531.ca:

NODE_ENV=development
SITE_URL=https://dev.team.8531.ca
AUTH_GATEWAY_URL=https://auth.8531.ca
JWT_SECRET=your-development-jwt-secret

Local Development

For local development (.env.local):

NODE_ENV=development
SITE_URL=http://localhost:4321
AUTH_GATEWAY_URL=https://auth.8531.ca
JWT_SECRET=your-local-jwt-secret

📦 Build Process

Build Commands

# Development build (with source maps)
npm run build

# Production build (optimized)
NODE_ENV=production npm run build

# Build specific output
npm run build -- --mode production

Build Optimization

The build process includes:

• Static Site Generation: Pre-builds all pages at build time
• API Routes: Converted to serverless functions
• Asset Optimization: Minification and compression
• Code Splitting: Automatic JavaScript bundling
• Image Optimization: Responsive image generation

Build Outputs

dist/
├── _astro/          # Generated Astro assets
├── assets/          # Static assets (images, fonts)
├── favicon.svg      # Site favicon
├── manifest.json    # PWA manifest
└── index.html       # Entry point

🔄 CI/CD Pipeline

GitHub Actions (Optional)

Create .github/workflows/deploy.yml:

name: Deploy

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 20
          cache: npm

      - run: npm ci
      - run: npm run build

      - name: Deploy to Vercel
        uses: amondnet/vercel-action@v25
        with:
          vercel-token: ${{ secrets.VERCEL_TOKEN }}
          vercel-org-id: ${{ secrets.ORG_ID }}
          vercel-project-id: ${{ secrets.PROJECT_ID }}
          vercel-args: '--prod'

Pre-deployment Checklist

Before deploying to production:

• All tests passing
• Environment variables configured
• Build succeeds without errors
• Preview deployment tested
• Security headers verified
• Performance metrics acceptable
• Backup current version (if needed)

🔒 Security Configuration

Production Security Headers

{
  "X-Frame-Options": "DENY",
  "X-Content-Type-Options": "nosniff",
  "X-XSS-Protection": "1; mode=block",
  "Referrer-Policy": "strict-origin-when-cross-origin",
  "Permissions-Policy": "camera=(), microphone=(), geolocation=()"
}

CORS Configuration

Production CORS settings:

{
  "origin": ["https://team.8531.ca"],
  "methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
  "allowedHeaders": ["Content-Type", "Authorization"],
  "credentials": true
}

SSL/HTTPS

• Production enforces HTTPS
• Automatic SSL certificate via Vercel
• HSTS headers enabled
• Secure cookie flags

📊 Monitoring & Analytics

Vercel Analytics

Built-in Vercel Analytics provides:

• Page view tracking
• Web Vitals monitoring
• Real-time visitor data
• Performance metrics

Custom Monitoring

Add custom monitoring:

src/lib/analytics.ts

export function trackEvent(name: string, data?: any) {
  if (typeof window !== 'undefined' && window.gtag) {
    window.gtag('event', name, data);
  }
}

Error Tracking

Consider adding error tracking:

src/lib/error-tracking.ts

export function reportError(error: Error) {
  console.error(error);
  // Send to error tracking service
}

🚨 Rollback Procedures

Quick Rollback

1. Vercel Rollback

   vercel rollback

2. Git Rollback

   git revert <commit-hash>
   git push origin main

3. Emergency Patch

   # Create hotfix branch
   git checkout -b hotfix/emergency-fix
   # Make fixes
   git commit -m "Emergency fix"
   git push origin hotfix/emergency-fix

Rollback Checklist

Before rolling back:

• Identify problematic commit
• Communicate with team
• Prepare rollback communication
• Test rollback in staging
• Monitor after rollback
• Document root cause

🔄 Domain Configuration

Custom Domain Setup

1. DNS Configuration

   A    @     76.76.19.61
   CNAME www  vercel.app

2. Vercel Domain Settings

   • Add domain in Vercel dashboard
   • Configure automatic HTTPS
   • Set up redirects

3. Environment-specific Domains

   • Production: team.8531.ca
   • Development: dev.team.8531.ca
   • Staging: staging.team.8531.ca (optional)

Domain Redirects

Configure redirects in vercel.json:

{
  "rewrites": [
    {
      "source": "/old-path",
      "destination": "/new-path"
    },
    {
      "source": "/blog/:slug",
      "destination": "/posts/:slug"
    }
  ]
}

📈 Performance Optimization

Build Optimizations

• Tree Shaking: Remove unused code
• Minification: Compress JavaScript and CSS
• Image Optimization: Responsive images
• Font Optimization: Font subsetting and preloading

Runtime Optimizations

• Edge Caching: Cache static assets at edge
• API Caching: Cache API responses
• CDN: Global content delivery
• Lazy Loading: Load resources as needed

Performance Budget

Set performance budgets in astro.config.mjs:

export default defineConfig({
  vite: {
    build: {
      rollupOptions: {
        output: {
          manualChunks: {
            vendor: ['astro'],
            framework: ['@astrojs/starlight']
          }
        }
      }
    }
  }
});

🔍 Testing in Production

A/B Testing

Implement feature flags for A/B testing:

src/lib/feature-flags.ts

export const flags = {
  newFeature: process.env.ENABLE_NEW_FEATURE === 'true'
};

Canary Deployments

Deploy to subset of users:

1. Create canary branch
2. Deploy to canary.team.8531.ca
3. Route percentage of traffic
4. Monitor performance
5. Full rollout if successful

Blue-Green Deployment

• Maintain two production environments
• Switch traffic with DNS
• Instant rollback capability
• Zero-downtime deployments

📋 Maintenance Tasks

Regular Maintenance

• Weekly: Review error logs, update dependencies
• Monthly: Security audits, performance reviews
• Quarterly: Architecture review, capacity planning

Dependency Updates

# Check for outdated packages
npm outdated

# Update packages
npm update

# Audit for security vulnerabilities
npm audit fix

Database Maintenance (if applicable)

• Back up data regularly
• Optimize queries
• Archive old data
• Monitor storage usage

📞 Deployment Support

Getting Help

• Vercel Support: Support via Vercel dashboard
• Community: Astro and Starlight Discord
• Documentation: Available on site
• Issues: Create GitHub issues for bugs

Troubleshooting

Common deployment issues:

1. Build Failures

   • Check Node.js version
   • Verify environment variables
   • Review build logs

2. Runtime Errors

   • Check function logs in Vercel
   • Verify API routes configuration
   • Test environment variables

3. Performance Issues

   • Check Vercel Analytics
   • Review Core Web Vitals
   • Optimize images and assets