Deployment Guide - KidStory: Storybook for Kids

Navigation: README | Architecture & Diagrams | How It Works | Database Schema | Hackathon Requirements | Deployment

Complete guide to deploy this Next.js app to Google Cloud Run.

📋 For Judges/Reviewers

This deployment guide demonstrates complete automation through scripts and infrastructure-as-code.

Template Files in Repository:

• deploy.sh.example - Single-command automated deployment
• fix_permissions.sh.example - Automated IAM setup
• update_url.sh.example - Automated URL configuration
• cloudbuild.yaml - CI/CD pipeline configuration
• .gcloudignore.example - Deployment optimization
• cors.json.example - Storage CORS automation

Security Note: Actual deployment files contain sensitive project data and are excluded from the repository via .gitignore. The .example files show the complete automation structure that judges can review.

Prerequisites

1. Google Cloud Account with billing enabled
2. Google Cloud CLI installed (Install Guide)
3. Firebase Project set up
4. Node.js 18+ installed

Step 1: Set Up Google Cloud Project

# Login to Google Cloud
gcloud auth login

# Create a new project (or use existing)
gcloud projects create YOUR_PROJECT_ID
gcloud config set project YOUR_PROJECT_ID

# Enable required APIs
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable aiplatform.googleapis.com
gcloud services enable storage.googleapis.com
gcloud services enable firestore.googleapis.com

Step 2: Set Up Firebase

1. Go to Firebase Console
2. Create a new project or select existing
3. Enable Authentication → Google Sign-In
4. Enable Firestore Database
5. Get your Firebase config from Project Settings

Step 3: Create Google Cloud Storage Bucket

# Create bucket for media storage
gsutil mb -p YOUR_PROJECT_ID -l us-central1 gs://YOUR_BUCKET_NAME

# Set CORS configuration
gsutil cors set cors.json gs://YOUR_BUCKET_NAME

# Make bucket publicly readable
gsutil iam ch allUsers:objectViewer gs://YOUR_BUCKET_NAME

Step 4: Configure Environment Variables

Create .env.production file:

cp .env.example .env.production

Edit .env.production with your Firebase config:

NEXT_PUBLIC_FIREBASE_API_KEY=your_api_key
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=your_project.firebaseapp.com
NEXT_PUBLIC_FIREBASE_PROJECT_ID=your_project_id
NEXT_PUBLIC_FIREBASE_STORAGE_BUCKET=your_project.firebasestorage.app
NEXT_PUBLIC_FIREBASE_MESSAGING_SENDER_ID=your_sender_id
NEXT_PUBLIC_FIREBASE_APP_ID=your_app_id
NEXT_PUBLIC_FIREBASE_MEASUREMENT_ID=your_measurement_id

Create deployment scripts from templates:

Note for Judges/Reviewers: The actual deployment scripts contain sensitive project information and are not committed to GitHub. The .example files demonstrate the complete automation structure.

# Copy example files and edit with your values
cp deploy.sh.example deploy.sh
cp fix_permissions.sh.example fix_permissions.sh
cp update_url.sh.example update_url.sh
cp .gcloudignore.example .gcloudignore
cp ../cors.json.example ../cors.json

# Make scripts executable
chmod +x deploy.sh fix_permissions.sh update_url.sh

Template Files Available in Repository:

• deploy.sh.example - Complete automated deployment script
• fix_permissions.sh.example - Automated IAM and permissions setup
• update_url.sh.example - Automated service URL configuration
• .gcloudignore.example - Deployment optimization configuration
• cors.json.example - Cloud Storage CORS automation

Edit each script and replace:

• YOUR_PROJECT_ID with your Google Cloud project ID
• YOUR_SERVICE_NAME with your service name (e.g., "storybook-for-kids")
• YOUR_REGION with your region (e.g., "us-central1")
• YOUR_BUCKET_NAME with your storage bucket name
• YOUR_NEXTAUTH_SECRET with a random secret (generate with: openssl rand -base64 32)

Step 5: Set Up Permissions

Run the permissions script to grant necessary IAM roles:

./fix_permissions.sh

This script will:

• Grant Cloud Run permissions
• Enable Vertex AI access
• Configure Firestore access
• Set up storage permissions

Step 6: Add Authorized Domain to Firebase

1. Go to Firebase Console → Authentication → Settings
2. Under "Authorized domains", add your Cloud Run URL (you'll get this after first deployment)
3. Format: your-service-name-xxxxx-uc.a.run.app

Step 7: Deploy

./deploy.sh

This will:

1. Build your Next.js app
2. Deploy to Cloud Run
3. Automatically update NEXTAUTH_URL with the service URL

Step 8: Post-Deployment

After successful deployment:

1. Copy the service URL from the deployment output
2. Add to Firebase Authorized Domains (if not done in Step 6)
3. Test the application:
   • Visit the URL
   • Try Google Sign-In
   • Create a story
   • Generate a quiz
   • Download PDF

Configuration Details

Environment Variables

Build-time variables (in .env.production):

• All NEXT_PUBLIC_* variables for Firebase client config

Runtime variables (in deploy.sh):

• GOOGLE_CLOUD_PROJECT - Your GCP project ID
• GOOGLE_CLOUD_REGION - Deployment region
• GCS_BUCKET_NAME - Storage bucket name
• FIREBASE_CLIENT_EMAIL - Service account email
• GEMINI_IMAGE_MODEL - Image generation model
• GEMINI_TTS_MODEL - Text-to-speech model
• GEMINI_QUIZ_MODEL - Quiz generation model
• NEXTAUTH_SECRET - NextAuth.js secret

Cloud Run Settings

• Min instances: 1 (keeps app always warm)
• Region: us-central1 (or your preferred region)
• Authentication: Allow unauthenticated (public access)
• Memory: 4 GiB
• CPU: 1 vCPU

Troubleshooting

Permission Errors

If you see permission denied errors:

# Re-run permissions script
./fix_permissions.sh

# Wait 1-2 minutes for IAM changes to propagate
# Then redeploy
./deploy.sh

Firebase Auth Error

If you see "unauthorized domain" error:

1. Check Firebase Console → Authentication → Settings → Authorized domains
2. Add your Cloud Run URL
3. Wait a few minutes for changes to propagate

Rate Limiting (429 Errors)

The app includes automatic retry logic with exponential backoff (up to 8 attempts). If you still hit rate limits:

• Wait a few minutes between requests
• Consider upgrading your Vertex AI quota

Image Loading Issues in PDF

The app compresses images before adding to PDF. If images still don't load:

• Check CORS configuration on your storage bucket
• Verify bucket permissions are set correctly

Updating the App

To deploy updates:

# Make your code changes
# Then redeploy
./deploy.sh

The deployment script handles everything automatically.

Security Notes

• Never commit .env.production, deploy.sh, fix_permissions.sh, or .gcloudignore to public repositories
• Use .example files as templates
• Rotate NEXTAUTH_SECRET periodically
• Review IAM permissions regularly

Support

For issues or questions:

1. Check Cloud Run logs: gcloud run services logs read storybook-for-kids --region=us-central1
2. Check Firebase Console for auth issues
3. Review this guide's troubleshooting section

---

Ready to deploy? Start with Step 1 and follow through to Step 7. Good luck! 🚀