Skip to main content

Deployment Guide

Complete guide for deploying the Toto ecosystem with Next.js API Routes and App Hosting.

🏗 Ecosystem Architecture​

Complete Toto Ecosystem Deployment​

  • toto (Main App): Next.js API Routes + App Hosting
  • toto-bo (Backoffice): Next.js API Routes + App Hosting
  • Unified Technology Stack: Both projects use the same deployment patterns

Deployment Architecture​

┌─────────────────────────────────────────────────────────────────┐
│                    Toto Ecosystem                              │
├─────────────────────────────────────────────────────────────────┤
│                                                               │
│  ┌─────────────────┐    ┌─────────────────┐                  │
│  │   toto-f9d2f    │    │     toto-bo     │                  │
│  │   (Main App)    │    │   (Backoffice)  │                  │
│  │                 │    │                 │                  │
│  │  🚀 App Hosting │    │  🚀 App Hosting │                  │
│  │  🔧 API Routes  │    │  🔧 API Routes  │                  │
│  │  🗄️ Firestore   │    │  🗄️ Firestore   │                  │
│  │  (Main DB)      │    │  (Local DB)     │                  │
│  └─────────────────┘    └─────────────────┘                  │
│                                                               │
│  🔗 External API Integration: toto-bo → toto-f9d2f           │
│  🔐 Unified Security: JWT + Session-based Auth               │
│  📊 Unified Monitoring: Performance + Health Metrics          │
│  🔒 Cloud Secret Manager: Secure environment management       │
│                                                               │
└─────────────────────────────────────────────────────────────────┘

🚀 Quick Deployment​

UI Screenshot Capture (for docs/marketing)​

  • Main app (toto-app):

    • Local: cd toto-app; npm run dev then npm run capture:ui:local
    • Prod: cd toto-app; npm run capture:ui
    • Output: toto-app/public/ui/*.png

  • Backoffice (toto-bo):

    • Local: cd toto-bo; node scripts/capture-ui.mjs http://localhost:5000 /dashboard
    • Prod: cd toto-bo; node scripts/capture-ui.mjs https://bo.betoto.pet /dashboard
    • Output: toto-bo/public/ui/*.png

  • Landing (toto-landing):

    • Desktop screenshot used in Solution section: public/bo-dashboard.png
    • Mobile overlay: public/home-mobile.png

toto (Main App) Deployment​

Initialize App Hosting:

# Navigate to main app
cd ../toto

# Initialize App Hosting configuration
firebase init apphosting

# Create backend (if not exists)
firebase apphosting:backends:create --project toto-f9d2f

Next.js API Routes Deployment:

# Build and deploy (API routes are part of App Hosting)
npm run build
firebase deploy --only hosting

# Verify deployment
firebase hosting:list

App Hosting Deployment (Automatic):

# Push to main branch triggers automatic deployment
git push origin main

# Check App Hosting status
firebase apphosting:backends:list

toto-bo (Backoffice) Deployment​

Initialize App Hosting:

# Navigate to backoffice
cd toto-bo

# Initialize App Hosting configuration
firebase init apphosting

# Create backend (if not exists)
firebase apphosting:backends:create --project toto-bo

Next.js API Routes Deployment:

# Build and deploy (API routes are part of App Hosting)
npm run build
firebase deploy --only hosting

# Verify deployment
firebase hosting:list

App Hosting Deployment (Automatic):

# Push to main branch triggers automatic deployment
git push origin main

# Check App Hosting status
firebase apphosting:backends:list

🔧 Configuration​

Environment Variables​

Main App (toto):

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=toto-f9d2f
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# App Hosting Configuration
NEXT_PUBLIC_APP_HOSTING_BACKEND_ID=your_backend_id

Backoffice (toto-bo):

# Firebase Configuration
NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_auth_domain
NEXT_PUBLIC_FIREBASE_PROJECT_ID=toto-bo
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_storage_bucket
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id

# NextAuth Configuration
NEXTAUTH_URL=https://your-backoffice-domain.com
NEXTAUTH_SECRET=your_nextauth_secret

# App Hosting Configuration
NEXT_PUBLIC_APP_HOSTING_BACKEND_ID=your_backend_id

Firebase Configuration​

firebase.json (Main App):

{
  "hosting": {
    "public": "out",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  },
  "apphosting": {
    "backend": "your-backend-id"
  }
}

firebase.json (Backoffice):

{
  "hosting": {
    "public": "out",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  },
  "apphosting": {
    "backend": "your-backend-id"
  }
}

📊 Monitoring & Health Checks​

App Hosting Monitoring​

Check Backend Status:

# List all backends
firebase apphosting:backends:list

# Get backend details
firebase apphosting:backends:get your-backend-id

# View logs
firebase apphosting:backends:logs your-backend-id

Health Check Endpoints:

# Main app health check
curl https://app.betoto.pet/api/health

# Backoffice health check
curl https://your-backoffice-domain.com/api/health

Performance Monitoring​

App Hosting Metrics:

  • Response Time: Monitor API response times
  • Throughput: Requests per second
  • Error Rate: Failed requests percentage
  • Resource Usage: CPU and memory utilization

Custom Metrics:

// Example custom metric
import { performance } from 'firebase/apphosting';

// Track custom metrics
performance.trace('api_request').start();
// ... API logic
performance.trace('api_request').stop();

🔒 Security Configuration​

Authentication Setup​

Main App (JWT-based):

// Firebase Auth configuration
const auth = getAuth();
auth.useDeviceLanguage();

// JWT token validation
const validateToken = async (token: string) => {
  try {
    const decodedToken = await auth.verifyIdToken(token);
    return decodedToken;
  } catch (error) {
    throw new Error('Invalid token');
  }
};

Backoffice (Session-based):

// NextAuth.js configuration
export const authOptions: NextAuthOptions = {
  providers: [
    GoogleProvider({
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    }),
  ],
  session: {
    strategy: 'jwt',
  },
  callbacks: {
    async session({ session, token }) {
      return session;
    },
    async jwt({ token, user }) {
      return token;
    },
  },
};

CORS Configuration​

API Routes CORS:

// Next.js API route with CORS
import { NextApiRequest, NextApiResponse } from 'next';
import Cors from 'cors';

const cors = Cors({
  methods: ['GET', 'POST', 'PUT', 'DELETE'],
  credentials: true,
  origin: ['https://app.betoto.pet', 'https://bo.betoto.pet'],
});

export default async function handler(req: NextApiRequest, res: NextApiResponse) {
  await new Promise((resolve) => cors(req, res, resolve));
  
  // Your API logic here
  res.json({ message: 'API response' });
}

🚀 Deployment Best Practices​

Pre-deployment Checklist​

  1. Environment Variables: Verify all required environment variables are set
  2. Database Migration: Ensure Firestore rules are updated
  3. API Testing: Test all API endpoints locally
  4. Build Verification: Confirm successful build process
  5. Security Review: Validate authentication and authorization

Deployment Process​

  1. Development Testing:

    npm run dev
    npm run test
    npm run build

  2. Staging Deployment:

    # Deploy to staging environment
    firebase use staging
    firebase deploy

  3. Production Deployment:

    # Deploy to production
    firebase use production
    firebase deploy

Rollback Strategy​

Quick Rollback:

# Revert to previous deployment
firebase hosting:clone --from toto-f9d2f:live --to toto-f9d2f:live --version-id previous-version-id

Database Rollback:

# Export current data
firebase firestore:export ./backup

# Import previous data
firebase firestore:import ./backup

📞 Troubleshooting​

Common Issues​

App Hosting Issues:

  • Backend not found: Verify backend ID in firebase.json
  • Deployment failed: Check build logs and environment variables
  • API routes not working: Verify Next.js configuration

Authentication Issues:

  • JWT validation failed: Check Firebase Auth configuration
  • Session expired: Verify NextAuth.js settings
  • CORS errors: Update CORS configuration

Performance Issues:

  • Slow response times: Monitor App Hosting metrics
  • High error rates: Check application logs
  • Memory leaks: Review application code

Debug Commands​

# Check App Hosting status
firebase apphosting:backends:list

# View deployment logs
firebase hosting:list

# Check Firebase project
firebase projects:list

# Verify environment
firebase use --add

🔗 Related Resources​