Deployment Guide

Complete guide for building and deploying the AquaGen Web Application to Firebase Hosting and other platforms.

Overview

AquaGen uses Firebase Hosting for deployment, with support for multiple hosting targets for different environments (UAT, demo, test, production, etc.).

Available Hosting Targets:

uat - User Acceptance Testing
test1 through test9 - Test environments
demo - Demo environment
pre-prod - Pre-production
dev - Development
aquagen - Production

Prerequisites

Required Tools

Firebase CLI
```
npm install -g firebase-tools
```
Firebase Account
- Access to the Firebase project
- Appropriate permissions for deployment
Built Application
- Application must be built before deployment
- Build artifacts in dist/apps/[app-name]/

Verify Firebase Setup

# Check Firebase CLI version
firebase --version
# Should output: 13.x.x or higher

# Login to Firebase
firebase login

# List your projects
firebase projects:list

# Check current project
firebase use

Deployment Process

Step 1: Build the Application

Build the application for production:

# Build production app
npm run build

# Or build specific app
APP_NAME=production npm run build:app

Build Output:

dist/apps/production/
├── index.html
├── main.[hash].js
├── vendor.[hash].js
├── styles.[hash].css
├── assets/
│   └── ... (images, fonts, etc.)
└── web.config

Build Time: ~30-60 seconds

Step 2: Test Build Locally (Recommended)

Before deploying, test the build locally:

npm run serve:build production

What this does:

Serves built files from dist/apps/production/
Usually runs on http://localhost:5000
Simulates production environment locally

Test Checklist:

Step 3: Deploy to Firebase

Deploy using the custom deploy script:

npm run deploy:app <app-name> <hosting-target>

Examples:

# Deploy to UAT environment
npm run deploy:app production uat

# Deploy to Test environment
npm run deploy:app production test1

# Deploy to Demo environment
npm run deploy:app production demo

# Deploy to Production
npm run deploy:app production aquagen

Deployment Process:

Script validates that build exists
Backs up firebase.json
Updates firebase.json with correct build path
Runs firebase deploy --only hosting:[target]
Restores original firebase.json

Expected Output:

Deploying app: production
Build path: dist/apps/production
Hosting target: uat

Updated firebase.json with build path: dist/apps/production
Deploying to hosting: uat

=== Deploying to 'your-project'...

i  deploying hosting
i  hosting[uat]: beginning deploy...
i  hosting[uat]: found 15 files in dist/apps/production
✔  hosting[uat]: file upload complete
i  hosting[uat]: finalizing version...
✔  hosting[uat]: version finalized
i  hosting[uat]: releasing new version...
✔  hosting[uat]: release complete

✔  Deploy complete!

Project Console: https://console.firebase.google.com/project/your-project/overview
Hosting URL: https://your-site.web.app

Deployment successful!

Manual Deployment (Alternative)

If you prefer manual deployment without the script:

Method 1: Firebase CLI Direct

# Update firebase.json manually to point to your build
# Then deploy:
firebase deploy --only hosting:uat

Method 2: Firebase Console

Build your application locally
Go to Firebase Console
Select your project
Navigate to Hosting
Click "Add another site" or select existing site
Use Firebase CLI to deploy or drag & drop build folder

Environment-Specific Deployments

Development Environment (`dev`)

# Build
npm run build

# Deploy
npm run deploy:app production dev

Purpose: For development team testing URL: https://dev.your-project.web.app

Test Environments (`test1-test9`)

# Deploy to test1
npm run deploy:app production test1

# Deploy to test5
npm run deploy:app production test5

Purpose: For QA testing, client demos, feature previews URLs: https://test1.your-project.web.app through https://test9.your-project.web.app

UAT Environment (`uat`)

npm run deploy:app production uat

Purpose: User Acceptance Testing with stakeholders URL: https://uat.your-project.web.app

Pre-Production (`pre-prod`)

npm run deploy:app production pre-prod

Purpose: Final testing before production release URL: https://pre-prod.your-project.web.app

Production (`aquagen`)

npm run deploy:app production aquagen

Purpose: Live production environment URL: https://aquagen.your-project.web.app or custom domain

⚠️ Production Deployment Checklist:

Firebase Hosting Configuration

firebase.json Structure

The firebase.json file defines hosting targets and configurations:

{
  "hosting": [
    {
      "public": "dist/apps/production",
      "ignore": ["firebase.json", "**/.*", "**/node_modules/**"],
      "target": "uat",
      "headers": [ /* Security headers */ ],
      "rewrites": [
        {
          "source": "**",
          "destination": "/index.html"
        }
      ]
    },
    // ... more targets
  ]
}

Key Fields:

public: Path to build directory
target: Hosting target name
headers: HTTP security headers
rewrites: SPA routing configuration (all routes → index.html)

Security Headers

All deployments include comprehensive security headers:

Header	Value	Purpose
`X-Frame-Options`	`DENY`	Prevent clickjacking
`Content-Security-Policy`	(detailed CSP)	XSS protection
`X-Content-Type-Options`	`nosniff`	MIME type sniffing protection
`X-XSS-Protection`	`1; mode=block`	XSS filter
`Referrer-Policy`	`strict-origin-when-cross-origin`	Control referrer info
`Strict-Transport-Security`	`max-age=31536000`	Force HTTPS
`Permissions-Policy`	(restricted)	Limit browser features
`Cross-Origin-Opener-Policy`	`same-origin-allow-popups`	Isolate browsing context
`Cross-Origin-Resource-Policy`	`same-origin`	Control resource loading
`Cache-Control`	`no-store, no-cache`	Prevent caching sensitive data

Content Security Policy (CSP)

The CSP allows:

Scripts from:

'self'
Google APIs (https://apis.google.com, https://accounts.google.com)
Firebase (https://*.firebaseio.com, https://*.googleapis.com)
'unsafe-inline', 'unsafe-eval' (for React and third-party libs)

Styles from:

'self'
Google Fonts (https://fonts.googleapis.com)
'unsafe-inline', blob:

Images from:

'self', data:, https:, blob:

Fonts from:

'self', data:
Google Fonts (https://fonts.gstatic.com)

Connections to:

'self', blob:
Azure WebSockets (wss://*.webpubsub.azure.com)
Azure Services (https://*.azurewebsites.net)
Firebase services
Iconify API (https://api.iconify.design)
Microsoft Login (https://login.microsoftonline.com)

Frames from:

'self', blob:
Azure services

Rollback Strategy

Quick Rollback

Firebase keeps deployment history. To rollback:

Via Firebase Console:
- Go to Hosting section
- Select the hosting target
- Click "Release history"
- Find previous working version
- Click "Rollback"

Via Firebase CLI:

firebase hosting:clone uat:uat --only hosting:uat

Emergency Rollback Procedure

If production is broken:

# 1. Identify last working commit
git log --oneline

# 2. Checkout last working commit
git checkout <commit-hash>

# 3. Build
npm run build

# 4. Deploy immediately
npm run deploy:app production aquagen

# 5. Return to current branch
git checkout main

Continuous Deployment (CI/CD)

GitHub Actions Example

Create .github/workflows/deploy.yml:

name: Deploy to Firebase

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

      - name: Deploy to Firebase
        uses: FirebaseExtended/action-hosting-deploy@v0
        with:
          repoToken: '${{ secrets.GITHUB_TOKEN }}'
          firebaseServiceAccount: '${{ secrets.FIREBASE_SERVICE_ACCOUNT }}'
          channelId: live
          projectId: your-project-id

Required Secrets

Add to GitHub repository secrets:

FIREBASE_SERVICE_ACCOUNT: Firebase service account JSON

Custom Domain Setup

Adding Custom Domain

In Firebase Console:
- Go to Hosting
- Click "Add custom domain"
- Enter your domain (e.g., app.aquagen.com)
- Follow DNS configuration steps
DNS Configuration:
- Add A records pointing to Firebase IPs
- Or add CNAME record pointing to Firebase subdomain
SSL Certificate:
- Firebase automatically provisions SSL certificates
- Usually takes 24-48 hours

Update Target:

firebase target:apply hosting aquagen your-custom-domain

Performance Optimization

Pre-Deployment Checks

# Analyze bundle size
npx nx build production --analyze

# Check for unused dependencies
npx depcheck

# Lighthouse CI (if configured)
npm run lighthouse

Post-Deployment Verification

Check Load Time:
- Use browser DevTools Network tab
- Target: < 3 seconds initial load
Check Bundle Sizes:
- Main bundle: < 500KB (gzipped)
- Total assets: < 2MB (initial load)
Check Lighthouse Score:
- Performance: > 90
- Accessibility: > 90
- Best Practices: > 90
- SEO: > 90

Troubleshooting Deployment Issues

Issue: "Build directory not found"

Error:

Error: Build directory 'dist/apps/production' does not exist
Please build the app first using: npm run build:app

Solution:

# Build the app
npm run build

# Verify build exists
ls -la dist/apps/production

# Then deploy
npm run deploy:app production uat

Error:

Error: No user signed in

Solution:

firebase login
# Follow browser authentication flow

Issue: "Insufficient permissions"

Error:

HTTP Error: 403, The caller does not have permission

Solution:

Contact Firebase project admin
Ensure you have "Firebase Hosting Admin" role
Check project permissions in Firebase Console

Issue: "Deployment fails midway"

Error:

i  hosting[uat]: file upload complete
!  hosting[uat]: Deploy timed out

Solution:

# Try again with increased timeout
firebase deploy --only hosting:uat --debug

# Or redeploy specific files
firebase deploy --only hosting:uat --force

Issue: "Old version still showing after deployment"

Cause: Browser cache or CDN cache

Solution:

Hard refresh browser: Ctrl+Shift+R (Windows) / Cmd+Shift+R (Mac)
Clear browser cache
Check deployment history in Firebase Console
Wait 5-10 minutes for CDN propagation

Issue: "404 on refresh"

Cause: SPA routing not configured properly

Solution: Ensure firebase.json has rewrite rules:

"rewrites": [
  {
    "source": "**",
    "destination": "/index.html"
  }
]

Monitoring & Analytics

Post-Deployment Monitoring

Firebase Analytics:
- Monitor real-time users
- Track page views
- Analyze user behavior
Error Tracking (Sentry):
- Check for new errors after deployment
- Monitor error rates
- Set up alerts for critical errors
Performance Monitoring:
- Use Firebase Performance Monitoring
- Track page load times
- Monitor API response times
Uptime Monitoring:
- Use third-party service (UptimeRobot, Pingdom)
- Get alerted if site goes down

Deployment Checklist Template

Pre-Deployment

All code merged to deployment branch
All tests passing (npm test)
Lint checks pass (npx nx lint production)
Build succeeds (npm run build)
Local build testing complete
Environment variables configured
API endpoints verified
Database migrations applied (if needed)

Deployment

Post-Deployment

Rollback Plan (if needed)

Best Practices

1. Use Staging Before Production

Always deploy to UAT or pre-prod before production:

# Test in UAT first
npm run deploy:app production uat
# Test thoroughly
# Then deploy to production
npm run deploy:app production aquagen

2. Tag Releases

# Tag production releases
git tag -a v1.2.3 -m "Release version 1.2.3"
git push origin v1.2.3

3. Keep Deploy Logs

Save deployment logs for troubleshooting:

npm run deploy:app production aquagen 2>&1 | tee deploy-$(date +%Y%m%d-%H%M%S).log

4. Schedule Deployments

Avoid deploying during peak hours
Prefer off-hours (evening/weekend) for production
Notify users of scheduled maintenance

5. Automate Testing

Run automated tests before deployment
Use CI/CD pipelines
Implement smoke tests post-deployment

Next Steps

Review Build Process for optimization tips
Check Environment Configuration for settings
See Production Optimization for performance tuning
Read Troubleshooting for common issues

Questions? See FAQ or contact the DevOps team.

Overview​

Prerequisites​

Required Tools​

Verify Firebase Setup​

Deployment Process​

Step 1: Build the Application​

Step 2: Test Build Locally (Recommended)​

Step 3: Deploy to Firebase​

Manual Deployment (Alternative)​

Method 1: Firebase CLI Direct​

Method 2: Firebase Console​

Environment-Specific Deployments​

Development Environment (dev)​

Test Environments (test1-test9)​

UAT Environment (uat)​

Pre-Production (pre-prod)​

Production (aquagen)​

Firebase Hosting Configuration​

firebase.json Structure​

Security Headers​

Content Security Policy (CSP)​

Rollback Strategy​

Quick Rollback​

Emergency Rollback Procedure​

Continuous Deployment (CI/CD)​

GitHub Actions Example​

Required Secrets​

Custom Domain Setup​

Adding Custom Domain​

Performance Optimization​

Pre-Deployment Checks​

Post-Deployment Verification​

Troubleshooting Deployment Issues​

Issue: "Build directory not found"​

Issue: "Firebase login required"​

Issue: "Insufficient permissions"​

Issue: "Deployment fails midway"​

Issue: "Old version still showing after deployment"​

Issue: "404 on refresh"​

Monitoring & Analytics​

Post-Deployment Monitoring​

Deployment Checklist Template​

Pre-Deployment​

Deployment​

Post-Deployment​

Rollback Plan (if needed)​

Best Practices​

1. Use Staging Before Production​

2. Tag Releases​

3. Keep Deploy Logs​

4. Schedule Deployments​

5. Automate Testing​

Next Steps​

Overview

Prerequisites

Required Tools

Verify Firebase Setup

Deployment Process

Step 1: Build the Application

Step 2: Test Build Locally (Recommended)

Step 3: Deploy to Firebase

Manual Deployment (Alternative)

Method 1: Firebase CLI Direct

Method 2: Firebase Console

Environment-Specific Deployments

Development Environment (`dev`)

Test Environments (`test1-test9`)

UAT Environment (`uat`)

Pre-Production (`pre-prod`)

Production (`aquagen`)

Firebase Hosting Configuration

firebase.json Structure

Security Headers

Content Security Policy (CSP)

Rollback Strategy

Quick Rollback

Emergency Rollback Procedure

Continuous Deployment (CI/CD)

GitHub Actions Example

Required Secrets

Custom Domain Setup

Adding Custom Domain

Performance Optimization

Pre-Deployment Checks

Post-Deployment Verification

Troubleshooting Deployment Issues

Issue: "Build directory not found"

Issue: "Firebase login required"

Issue: "Insufficient permissions"

Issue: "Deployment fails midway"

Issue: "Old version still showing after deployment"

Issue: "404 on refresh"

Monitoring & Analytics

Post-Deployment Monitoring

Deployment Checklist Template

Pre-Deployment

Deployment

Post-Deployment

Rollback Plan (if needed)

Best Practices

1. Use Staging Before Production

2. Tag Releases

3. Keep Deploy Logs

4. Schedule Deployments

5. Automate Testing

Next Steps