Complete guide for deploying the Machine Learning 101 platform with authentication backend.
- Prerequisites
- Google OAuth Setup
- Cloudflare Worker Setup
- Database Setup
- Environment Configuration
- Frontend Deployment
- Verification
- Troubleshooting
- Cloudflare Account: Sign up
- Google Cloud Account: Sign up
- Domain (optional but recommended): For production deployment
# Node.js 18+ and npm
node --version # Should be 18.0.0 or higher
npm --version
# Wrangler CLI (Cloudflare Workers CLI)
npm install -g wrangler
# Verify installation
wrangler --versionwrangler loginThis will open a browser window for authentication.
- Go to Google Cloud Console
- Click "Select a project" → "New Project"
- Enter project name:
ml-platform-auth - Click "Create"
- In the project dashboard, go to "APIs & Services" → "Library"
- Search for "Google+ API"
- Click "Enable"
- Go to "APIs & Services" → "OAuth consent screen"
- Select "External" user type
- Click "Create"
- Fill in required fields:
- App name: Machine Learning 101
- User support email: Your email
- Developer contact: Your email
- Click "Save and Continue"
- Scopes: Click "Add or Remove Scopes"
- Add:
userinfo.email - Add:
userinfo.profile
- Add:
- Click "Save and Continue"
- Test users (for development):
- Add your email address
- Click "Save and Continue"
- Go to "APIs & Services" → "Credentials"
- Click "Create Credentials" → "OAuth client ID"
- Select "Web application"
- Configure:
- Name: ML Platform Worker
- Authorized JavaScript origins: Leave empty
- Authorized redirect URIs:
- Development:
http://localhost:8787/api/auth/google/callback - Production:
https://api.yourdomain.com/api/auth/google/callback
- Development:
- Click "Create"
- Save the credentials:
- Client ID:
xxxxx.apps.googleusercontent.com - Client Secret:
xxxxx
- Client ID:
⚠️ Important: Keep these credentials secure. Never commit them to version control.
cd workernpm install# Create the database
wrangler d1 create ml-platform-dbOutput example:
✅ Successfully created DB 'ml-platform-db'
[[d1_databases]]
binding = "DB"
database_name = "ml-platform-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
Copy the database_id from the output and update wrangler.toml:
[[d1_databases]]
binding = "DB"
database_name = "ml-platform-db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" # Replace with your IDThe migrate.sh script handles database migrations for both development and production.
./migrate.sh devThis creates tables in your local development database.
./migrate.sh prodThis creates tables in your production D1 database.
# List tables in development
wrangler d1 execute ml-platform-db --local --command "SELECT name FROM sqlite_master WHERE type='table'"
# List tables in production
wrangler d1 execute ml-platform-db --command "SELECT name FROM sqlite_master WHERE type='table'"Expected output:
users
progress
quiz_scores
bookmarks
The database includes four main tables:
- users: User accounts with Google OAuth data
- progress: Module completion tracking
- quiz_scores: Quiz results and scores
- bookmarks: User-saved modules
See worker/schema.sql for the complete schema.
Set the following secrets for your Cloudflare Worker:
# Navigate to worker directory
cd worker
# Set Google OAuth credentials
wrangler secret put GOOGLE_CLIENT_ID
# Paste your Google Client ID when prompted
wrangler secret put GOOGLE_CLIENT_SECRET
# Paste your Google Client Secret when prompted
# Set redirect URI (must match Google OAuth configuration)
wrangler secret put GOOGLE_REDIRECT_URI
# Development: http://localhost:8787/api/auth/google/callback
# Production: https://api.yourdomain.com/api/auth/google/callback
# Generate and set JWT secret (use a strong random string)
wrangler secret put JWT_SECRET
# Generate with: openssl rand -base64 32
# Set frontend URL (for CORS)
wrangler secret put FRONTEND_URL
# Development: http://localhost:3000
# production: https://machinelearning101.com# On macOS/Linux
openssl rand -base64 32
# Or use Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"wrangler secret listExpected output:
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
GOOGLE_REDIRECT_URI
JWT_SECRET
FRONTEND_URL
Create or update .env in the project root:
# API endpoint
NUXT_PUBLIC_API_URL=https://api.yourdomain.com
# For local development
# NUXT_PUBLIC_API_URL=http://localhost:8787cd worker
# Start local development server
npm run devThe worker will be available at http://localhost:8787.
# Run all tests
npm test
# Run with coverage
npm run test:coverageEnsure all tests pass before deploying.
# Deploy the worker
npm run deployOutput example:
✨ Built successfully
✨ Uploaded successfully
✨ Deployed successfully
🌍 https://ml-platform-auth.your-subdomain.workers.dev
To use a custom domain like api.yourdomain.com:
- Go to Cloudflare Dashboard
- Select your worker
- Go to "Triggers" → "Custom Domains"
- Click "Add Custom Domain"
- Enter:
api.yourdomain.com - Click "Add Custom Domain"
Cloudflare will automatically provision SSL certificates.
After deploying with a custom domain:
- Go to Google Cloud Console
- Navigate to "APIs & Services" → "Credentials"
- Edit your OAuth client
- Update "Authorized redirect URIs":
- Add:
https://api.yourdomain.com/api/auth/google/callback
- Add:
- Save changes
Update the redirect URI secret:
wrangler secret put GOOGLE_REDIRECT_URI
# Enter: https://api.yourdomain.com/api/auth/google/callback
wrangler secret put FRONTEND_URL
# Enter: https://yourdomain.comUpdate .env with your production API URL:
NUXT_PUBLIC_API_URL=https://api.yourdomain.com# From project root
npm run buildThis generates a static site in .output/public/.
npm run previewTest the authentication flow:
- Click "Sign in with Google"
- Complete OAuth flow
- Verify user profile appears
- Test progress sync
The platform is a static site and can be deployed to any static hosting provider:
# Install Netlify CLI
npm install -g netlify-cli
# Deploy
netlify deploy --prod --dir=.output/public# Install Vercel CLI
npm install -g vercel
# Deploy
vercel --prod# Deploy to Cloudflare Pages
wrangler pages deploy .output/public# Push .output/public to gh-pages branch
npm run generate
git subtree push --prefix .output/public origin gh-pagesPoint your domain to your hosting provider:
- Netlify: Add custom domain in Netlify dashboard
- Vercel: Add custom domain in Vercel dashboard
- Cloudflare Pages: Add custom domain in Cloudflare dashboard
- GitHub Pages: Configure custom domain in repository settings
# Test health check
curl https://api.yourdomain.com/
# Test OAuth initiation (should redirect)
curl -I https://api.yourdomain.com/api/auth/google- Open your deployed frontend:
https://yourdomain.com - Click "Sign in with Google"
- Complete OAuth consent
- Verify:
- Redirected back to frontend
- User profile appears in header
- JWT token stored in localStorage
- Complete a module
- Open browser DevTools → Network tab
- Verify POST request to
/api/progress/sync - Check response status: 200 OK
- Sign in on Device A
- Complete a module
- Sign in on Device B with same account
- Verify progress appears on Device B
# Tail worker logs
wrangler tail# Query users table
wrangler d1 execute ml-platform-db --command "SELECT COUNT(*) FROM users"
# Query progress table
wrangler d1 execute ml-platform-db --command "SELECT COUNT(*) FROM progress"Cause: Redirect URI doesn't match Google OAuth configuration
Solution:
- Check
GOOGLE_REDIRECT_URIsecret matches exactly - Verify URI is added in Google Cloud Console
- Ensure protocol (http/https) matches
Cause: Invalid client ID or secret
Solution:
- Verify
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRET - Check for extra spaces or newlines
- Regenerate credentials if needed
Cause: JWT validation failing
Solution:
- Check
JWT_SECRETis set correctly - Verify token hasn't expired (7-day expiration)
- Clear localStorage and sign in again
Cause: CORS not configured correctly
Solution:
- Verify
FRONTEND_URLsecret matches your frontend domain exactly - Check protocol (http/https) matches
- Ensure no trailing slash in URL
Cause: Database migrations not run
Solution:
cd worker
./migrate.sh prodCause: Database ID in wrangler.toml is incorrect
Solution:
- Run
wrangler d1 listto find correct ID - Update
database_idinwrangler.toml - Redeploy worker
Cause: D1 database binding not configured
Solution:
- Verify
[[d1_databases]]section inwrangler.toml - Ensure
binding = "DB"matches code - Redeploy worker
Cause: Required secrets not set
Solution:
wrangler secret list
# Set any missing secrets
wrangler secret put SECRET_NAMECause: Worker cold starts
Solution:
- Workers warm up after first request
- Consider Cloudflare Workers Paid plan for reduced cold starts
Cause: Missing indexes or large dataset
Solution:
- Verify indexes exist (see
schema.sql) - Check query performance with
EXPLAIN QUERY PLAN
Before going live, verify:
- Google OAuth configured with production redirect URI
- All Cloudflare Worker secrets set
- Database migrations run on production D1
- Worker deployed and accessible
- Custom domain configured (if applicable)
- Frontend deployed with correct API URL
- Authentication flow tested end-to-end
- Progress sync tested across devices
- Error monitoring configured
- CORS configured correctly
- SSL certificates active
- Test user accounts created and verified
View worker analytics in Cloudflare Dashboard:
- Request volume
- Error rates
- Response times
- Geographic distribution
# Check database size
wrangler d1 execute ml-platform-db --command "SELECT page_count * page_size as size FROM pragma_page_count(), pragma_page_size()"
# Check table row counts
wrangler d1 execute ml-platform-db --command "
SELECT 'users' as table_name, COUNT(*) as count FROM users
UNION ALL
SELECT 'progress', COUNT(*) FROM progress
UNION ALL
SELECT 'quiz_scores', COUNT(*) FROM quiz_scores
UNION ALL
SELECT 'bookmarks', COUNT(*) FROM bookmarks
"# Real-time logs
wrangler tail
# Filter by status code
wrangler tail --status errorD1 databases are automatically backed up by Cloudflare. To export data:
# Export users table
wrangler d1 execute ml-platform-db --command "SELECT * FROM users" --json > users_backup.jsonIf issues occur after deployment:
# List deployments
wrangler deployments list
# Rollback to previous version
wrangler rollback [deployment-id]# Restore from backup
wrangler d1 execute ml-platform-db --file=backup.sqlDepends on hosting provider:
- Netlify: Rollback in dashboard
- Vercel: Rollback in dashboard
- Cloudflare Pages: Rollback in dashboard
- Rotate Secrets Regularly: Update JWT_SECRET and OAuth credentials periodically
- Monitor Access Logs: Watch for suspicious authentication attempts
- Rate Limiting: Consider adding rate limiting for auth endpoints
- HTTPS Only: Never use HTTP in production
- Audit Dependencies: Regularly update npm packages
- Backup Data: Export database regularly
- Test Security: Run security audits before major releases
- Free Tier: 100,000 requests/day
- Paid Plan: $5/month for 10M requests
- Free Tier: 5GB storage, 5M reads/day, 100K writes/day
- Paid Plan: Usage-based pricing
- < 1000 users: Free tier sufficient
- 1000-10000 users: ~$5-10/month
- 10000+ users: ~$20-50/month
After successful deployment:
- Monitor Performance: Watch worker analytics and error rates
- Gather Feedback: Test with real users
- Optimize: Identify and fix bottlenecks
- Scale: Upgrade plans as needed
- Iterate: Add new features based on usage patterns
Deployment complete! 🎉
Your Machine Learning 101 platform is now live with authentication and progress sync.