Architecture Overview
Agility consists of two main components:- Next.js Frontend Application - The web interface and client-side logic
- Supabase Backend - Database, authentication, and edge functions
Deployment Options
Recommended: Vercel + Supabase
The recommended deployment stack combines:- Vercel for hosting the Next.js application
- Supabase for backend services (database, auth, edge functions)
- Zero-config deployment for Next.js
- Automatic HTTPS and CDN
- Serverless edge functions
- Built-in authentication
- PostgreSQL database
Alternative Platforms
While Vercel is recommended, you can deploy the Next.js application to:- Netlify
- AWS Amplify
- Self-hosted Node.js server
- Docker containers
Deployment Checklist
Before deploying to production:Set up Supabase project
Create a Supabase project and configure the database schema.See Supabase Setup for detailed instructions.
Configure environment variables
Set up all required environment variables for your deployment platform.See Environment Variables for the complete list.
Configure OAuth callbacks
Update OAuth redirect URIs in your Google Cloud Console to match your production domain.
Deploying to Vercel
Vercel provides the simplest deployment experience for Next.js applications.Using Vercel CLI
Using Vercel Dashboard
Connect repository
- Go to vercel.com
- Click “Add New Project”
- Import your Git repository
Configure build settings
Vercel automatically detects Next.js projects. Verify:
- Framework Preset: Next.js
- Build Command:
next build - Output Directory:
.next
Security Considerations
Environment Variables
- Use platform-specific secret management (Vercel Environment Variables, AWS Secrets Manager, etc.)
- Rotate API keys and tokens regularly
- Use different credentials for development and production
Encryption Key
Agility uses an encryption key to protect sensitive data like API keys and OAuth tokens:- Set a strong, random encryption key in production
- Never use the default encryption key (
default-encryption-key) - Use the same encryption key across frontend and backend
- Store the encryption key securely (never in version control)
Database Security
- Enable Row Level Security (RLS) in Supabase
- Use Supabase’s built-in authentication
- Regularly backup your database
- Monitor database access logs
Performance Optimization
Frontend Optimization
- Enable Next.js production optimizations (automatic in build)
- Use Vercel’s Edge Network for global distribution
- Implement proper caching strategies
- Optimize images using Next.js Image component
Backend Optimization
- Use Supabase connection pooling
- Implement proper database indexes
- Monitor edge function performance
- Use Supabase’s built-in caching
Monitoring and Logging
Application Monitoring
- Use Vercel Analytics for frontend performance
- Monitor Supabase edge function logs
- Set up error tracking (Sentry, LogRocket, etc.)
- Monitor API rate limits and usage
Database Monitoring
- Use Supabase Dashboard for database metrics
- Monitor query performance
- Track connection pool usage
- Set up alerts for critical issues
Troubleshooting
Common Deployment Issues
Build Failures- Verify all dependencies are in
package.json - Check Node.js version compatibility (18+)
- Review build logs for specific errors
- Ensure all required variables are set
- Verify variable names match exactly (case-sensitive)
- Check for typos in variable values
- Review Supabase function logs
- Verify function deployment was successful
- Check CORS configuration
- Ensure encryption keys match
- Verify Supabase URL and anon key are correct
- Check OAuth redirect URIs match production domain
- Ensure middleware is configured correctly
Next Steps
- Environment Variables - Complete list of required variables
- Supabase Setup - Detailed backend configuration guide