Skip to content

DEPLOYMENT_GUIDE.md

Latest commit

 

History

History
284 lines (232 loc) · 7.28 KB

DEPLOYMENT_GUIDE.md

File metadata and controls

284 lines (232 loc) · 7.28 KB

Urbindex - Complete Deployment Guide with Continuous Integration

Overview

This guide documents the authentication fixes applied to Urbindex and provides comprehensive deployment instructions including automatic deployment via GitHub Actions.

File Consolidation ✅

  • Old structure: Multiple HTML files (index.html, final.html, etc.)
  • New structure: Single index.html as the main entry point
  • Changes made:
    • Backed up old index.html to index-old-backup.html
    • Copied fixed final.html to index.html
    • All fixes are now in the main index.html file

Continuous Deployment Setup

1. Generate Firebase CI Token

# Install Firebase CLI globally if not already installed
npm install -g firebase-tools

# Generate a CI token
firebase login:ci

Copy the token that is displayed - you'll need it for GitHub Secrets.

2. Add GitHub Secrets

Go to your GitHub repository → Settings → Secrets and variables → Actions

Add the following secret:

  • Name: FIREBASE_TOKEN
  • Value: The token you generated in step 1

3. GitHub Actions Workflow

The workflow is already configured in .github/workflows/firebase-deploy.yml and will:

  • On push to main/master: Deploy to production Firebase Hosting
  • On pull request: Deploy to a preview channel for testing
  • Automatically deploy Firestore rules
  • Comment on PRs with preview URLs

4. Verify GitHub Actions

  1. Make a commit and push to your repository
  2. Go to the "Actions" tab in GitHub
  3. Watch the deployment workflow run
  4. Check for any errors in the logs

Authentication Fixes Applied

1. Core Issues Fixed ✅

  • Authentication Flow: Standardized across the application
  • UI State Management: FAB button and auth indicators update correctly
  • Firestore Permissions: Proper handling of anonymous auth
  • Error Handling: Toast notifications instead of alerts
  • User Experience: Clear prompts and feedback

2. Technical Changes

// Key improvements in index.html:
- Deferred Firestore queries until after authentication
- Added proper error handling for permission errors
- Implemented toast notification system
- Fixed FAB button visibility logic
- Added authentication checks before operations

Manual Deployment (if needed)

Prerequisites

  • Node.js 14+ installed
  • Firebase CLI installed (npm install -g firebase-tools)
  • Access to the Firebase project

Steps

  1. Login to Firebase:

    firebase login

  2. Deploy Everything:

    firebase deploy

  3. Deploy Specific Services:

    # Hosting only
firebase deploy --only hosting

# Firestore rules only
firebase deploy --only firestore:rules

# Functions only (if any)
firebase deploy --only functions

Testing Checklist

Before Deployment

  • Run test-auth.html locally and verify all tests pass
  • Test authentication flow in index.html
  • Verify FAB button shows/hides correctly
  • Test adding a location
  • Check console for errors

After Deployment

  • Visit production URL
  • Test sign in/out functionality
  • Add a test location
  • Verify map loads correctly
  • Test on mobile devices
  • Check browser console for errors

Project Structure

urbindex/
├── index.html              # Main application (with all fixes)
├── index-old-backup.html   # Backup of original buggy version
├── test-auth.html          # Authentication test suite
├── firebase.json           # Firebase configuration
├── firestore.rules         # Security rules
├── service-worker.js       # PWA offline support
├── manifest.json           # PWA manifest
├── .github/
│   └── workflows/
│       └── firebase-deploy.yml  # CI/CD workflow
└── docs/
    ├── AUTHENTICATION_PLAN.md   # Future auth improvements
    └── DEPLOYMENT_GUIDE.md      # This file

Firebase Configuration

firebase.json

{
  "hosting": {
    "public": ".",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**",
      "test-auth.html",
      "index-old-backup.html"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    "headers": [
      {
        "source": "**/*.@(jpg|jpeg|gif|png|webp|svg)",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=604800"
          }
        ]
      },
      {
        "source": "**/*.@(js|css)",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=3600"
          }
        ]
      }
    ]
  },
  "firestore": {
    "rules": "firestore.rules",
    "indexes": "firestore.indexes.json"
  }
}

Monitoring & Maintenance

1. Monitor Deployments

  • Check GitHub Actions tab for deployment status
  • Review deployment logs for any warnings
  • Monitor Firebase Console for usage and errors

2. Error Tracking

  • Firebase Console → Functions → Logs (if using functions)
  • Firebase Console → Hosting → Usage
  • Browser DevTools console for client-side errors

3. Performance Monitoring

  • Use Firebase Performance Monitoring
  • Check Lighthouse scores regularly
  • Monitor load times and user feedback

Troubleshooting

GitHub Actions Failures

  1. Authentication Error:

    • Regenerate Firebase CI token
    • Update FIREBASE_TOKEN in GitHub Secrets

  2. Build Failures:

    • Check syntax errors in files
    • Verify all dependencies are committed

  3. Deployment Failures:

    • Check Firebase project permissions
    • Verify project ID matches in workflow

Common Issues

  1. "Permission Denied" in app:

    • User not authenticated
    • Firestore rules not deployed
    • Check browser console

  2. FAB button not showing:

    • Clear browser cache
    • Check authentication state
    • Verify JavaScript loads

  3. Map not loading:

    • Check network requests
    • Verify Leaflet CDN is accessible
    • Check for JavaScript errors

Rollback Procedures

Automatic Rollback

# List recent releases
firebase hosting:releases:list

# Rollback to previous version
firebase hosting:rollback

Manual Rollback

  1. Revert the GitHub commit
  2. Push to trigger new deployment
  3. Or manually deploy previous version

Security Notes

Keep These Secret

  • Firebase CI token
  • Firebase API keys (though they're public-facing)
  • Any service account keys

Best Practices

  • Regular security audits
  • Monitor for unusual activity
  • Keep dependencies updated
  • Review Firestore rules regularly

Next Steps

  1. Immediate:

    • Push code to GitHub to trigger deployment
    • Monitor first automatic deployment
    • Test production site thoroughly

  2. Short-term:

    • Implement email authentication (see AUTHENTICATION_PLAN.md)
    • Add error tracking (Sentry/Bugsnag)
    • Set up monitoring alerts

  3. Long-term:

    • Social authentication
    • User profiles enhancement
    • Performance optimization

Support & Resources

Version: 2.0
Last Updated: December 2024
Status: Production Ready with CI/CD