cim_summary/DEPLOYMENT_GUIDE.md

Deployment Guide - Cloud-Only Architecture

This guide covers the standardized deployment process for the CIM Document Processor, which has been optimized for cloud-only deployment using Google Cloud Platform services.

Architecture Overview

• Frontend: React/TypeScript application deployed on Firebase Hosting
• Backend: Node.js/TypeScript API deployed on Google Cloud Run (recommended) or Firebase Functions
• Storage: Google Cloud Storage (GCS) for all file operations
• Database: Supabase (PostgreSQL) for data persistence
• Authentication: Firebase Authentication

Prerequisites

Required Tools

• Google Cloud CLI (gcloud)
• Firebase CLI
• Docker (for Cloud Run deployment)
• Node.js (v18 or higher)

Required Permissions

• Google Cloud Project with billing enabled
• Firebase project configured
• Service account with GCS permissions
• Supabase project configured

Quick Deployment

Option 1: Deploy Everything (Recommended)

# Deploy backend to Cloud Run + frontend to Firebase Hosting
./deploy.sh -a

Option 2: Deploy Components Separately

# Deploy backend to Cloud Run
./deploy.sh -b cloud-run

# Deploy backend to Firebase Functions
./deploy.sh -b firebase

# Deploy frontend only
./deploy.sh -f

# Deploy with tests
./deploy.sh -t -a

Manual Deployment Steps

Backend Deployment

Cloud Run (Recommended)

1. Build and Deploy:

   cd backend
   npm run deploy:cloud-run
   

2. Or use Docker directly:

   cd backend
   npm run docker:build
   npm run docker:push
   gcloud run deploy cim-processor-backend \
     --image gcr.io/cim-summarizer/cim-processor-backend:latest \
     --region us-central1 \
     --platform managed \
     --allow-unauthenticated
   

Firebase Functions

1. Deploy to Firebase:

   cd backend
   npm run deploy:firebase
   

Frontend Deployment

1. Deploy to Firebase Hosting:

   cd frontend
   npm run deploy:firebase
   

2. Deploy Preview Channel:

   cd frontend
   npm run deploy:preview
   

Environment Configuration

Required Environment Variables

Backend (Cloud Run/Firebase Functions)

NODE_ENV=production
PORT=8080
PROCESSING_STRATEGY=agentic_rag
GCLOUD_PROJECT_ID=cim-summarizer
DOCUMENT_AI_LOCATION=us
DOCUMENT_AI_PROCESSOR_ID=your-processor-id
GCS_BUCKET_NAME=cim-summarizer-uploads
DOCUMENT_AI_OUTPUT_BUCKET_NAME=cim-summarizer-document-ai-output
LLM_PROVIDER=anthropic
VECTOR_PROVIDER=supabase
AGENTIC_RAG_ENABLED=true
ENABLE_RAG_PROCESSING=true
SUPABASE_URL=your-supabase-url
SUPABASE_ANON_KEY=your-supabase-anon-key
SUPABASE_SERVICE_KEY=your-supabase-service-key
ANTHROPIC_API_KEY=your-anthropic-key
OPENAI_API_KEY=your-openai-key
JWT_SECRET=your-jwt-secret
JWT_REFRESH_SECRET=your-refresh-secret

Frontend

VITE_API_BASE_URL=your-backend-url
VITE_FIREBASE_API_KEY=your-firebase-api-key
VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
VITE_FIREBASE_PROJECT_ID=your-project-id

Configuration Files

Firebase Configuration

Backend (backend/firebase.json)

{
  "functions": {
    "source": ".",
    "runtime": "nodejs20",
    "ignore": [
      "node_modules",
      "src",
      "logs",
      "uploads",
      "*.test.ts",
      "*.test.js",
      "jest.config.js",
      "tsconfig.json",
      ".eslintrc.js",
      "Dockerfile",
      "cloud-run.yaml"
    ],
    "predeploy": ["npm run build"],
    "codebase": "backend"
  }
}

Frontend (frontend/firebase.json)

{
  "hosting": {
    "public": "dist",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**",
      "src/**",
      "*.test.ts",
      "*.test.js"
    ],
    "headers": [
      {
        "source": "**/*.js",
        "headers": [
          {
            "key": "Cache-Control",
            "value": "public, max-age=31536000, immutable"
          }
        ]
      }
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ],
    "cleanUrls": true,
    "trailingSlash": false
  }
}

Cloud Run Configuration

Dockerfile (backend/Dockerfile)

• Multi-stage build for optimized image size
• Security best practices (non-root user)
• Proper signal handling with dumb-init
• Optimized for Node.js 20

Cloud Run YAML (backend/cloud-run.yaml)

• Resource limits and requests
• Health checks and probes
• Autoscaling configuration
• Environment variables

Development Workflow

Local Development

# Backend
cd backend
npm run dev

# Frontend
cd frontend
npm run dev

Testing

# Backend tests
cd backend
npm test

# Frontend tests
cd frontend
npm test

# GCS integration tests
cd backend
npm run test:gcs

Emulators

# Firebase emulators
cd backend
npm run emulator:ui

cd frontend
npm run emulator:ui

Monitoring and Logging

Cloud Run Monitoring

• Built-in monitoring in Google Cloud Console
• Logs available in Cloud Logging
• Metrics for CPU, memory, and request latency

Firebase Monitoring

• Firebase Console for Functions monitoring
• Real-time database monitoring
• Hosting analytics

Application Logging

• Structured logging with Winston
• Correlation IDs for request tracking
• Error categorization and reporting

Troubleshooting

Common Issues

1. Build Failures

   • Check Node.js version compatibility
   • Verify all dependencies are installed
   • Check TypeScript compilation errors

2. Deployment Failures

   • Verify Google Cloud authentication
   • Check project permissions
   • Ensure billing is enabled

3. Runtime Errors

   • Check environment variables
   • Verify service account permissions
   • Review application logs

Debug Commands

# Check deployment status
gcloud run services describe cim-processor-backend --region=us-central1

# View logs
gcloud logs read "resource.type=cloud_run_revision"

# Test GCS connection
cd backend
npm run test:gcs

# Check Firebase deployment
firebase hosting:sites:list

Security Considerations

Cloud Run Security

• Non-root user in container
• Minimal attack surface with Alpine Linux
• Proper signal handling
• Resource limits

Firebase Security

• Authentication required for sensitive operations
• CORS configuration
• Rate limiting
• Input validation

GCS Security

• Service account with minimal permissions
• Signed URLs for secure file access
• Bucket-level security policies

Cost Optimization

Cloud Run

• Scale to zero when not in use
• CPU and memory limits
• Request timeout configuration

Firebase

• Pay-per-use pricing
• Automatic scaling
• CDN for static assets

GCS

• Lifecycle policies for old files
• Storage class optimization
• Request optimization

Migration from Local Development

This deployment configuration is designed for cloud-only operation:

1. No Local Dependencies: All file operations use GCS
2. No Local Database: Supabase handles all data persistence
3. No Local Storage: Temporary files only in /tmp
4. Stateless Design: No persistent local state

Support

For deployment issues:

1. Check the troubleshooting section
2. Review application logs
3. Verify environment configuration
4. Test with emulators first

For architecture questions:

• Review the design documentation
• Check the implementation summaries
• Consult the GCS integration guide