Deployment Guide

Overview

This guide covers deploying the Momentum LMS platform to AWS, including infrastructure, backend services, and frontend application.

Prerequisites

Before deploying, ensure you have:

  1. AWS CLI installed and configured 
    aws --version
aws configure  # Set your AWS credentials
  2. Terraform installed (v1.0+) 
    terraform --version
  3. Node.js and npm installed (v20+) 
    node --version
npm --version
  4. Valid AWS credentials with permissions to create:
    • VPC, Subnets, Security Groups
    • RDS Aurora Serverless
    • ElastiCache Serverless
    • S3 buckets and CloudFront distributions
    • Lambda functions
    • API Gateway
    • Cognito User Pools
    • IAM roles and policies

Deployment Process

Deploy everything at once:

./scripts/deployment/deploy-all.sh

This will:

  1. Deploy infrastructure (Terraform)
  2. Build and deploy backend (Lambda functions)
  3. Build and deploy frontend (S3/CloudFront)

Option 2: Step-by-Step Deployment

Step 1: Deploy Infrastructure 

./scripts/deployment/deploy-infrastructure.sh

This creates:

  • VPC and networking
  • RDS Aurora Serverless (PostgreSQL)
  • ElastiCache Serverless (Redis)
  • S3 buckets and CloudFront distribution
  • API Gateway
  • AWS Cognito User Pool and Identity Pool
  • Lambda function placeholders
  • IAM roles and permissions

Important: After infrastructure deployment, Cognito credentials are saved to .env.infrastructure:

  • COGNITO_USER_POOL_ID
  • COGNITO_WEB_CLIENT_ID
  • COGNITO_IDENTITY_POOL_ID

Step 2: Run Database Migrations 

./scripts/database/db-migrate.sh

This applies database schema migrations to the Aurora cluster.

Step 3: Deploy Backend 

./scripts/deployment/deploy-backend.sh

This builds and deploys:

  • Lambda functions (courses, lessons, enrollments)
  • Cognito Lambda triggers (pre-signup, post-confirmation, etc.)

Step 4: Deploy Frontend 

./scripts/deployment/deploy-frontend.sh

This:

  1. Installs frontend dependencies
  2. Runs linting and type checking
  3. Builds Next.js with Cognito environment variables (from .env.infrastructure)
  4. Uploads build to S3
  5. Invalidates CloudFront cache

Note: The frontend build automatically embeds Cognito credentials at build time using values from .env.infrastructure.

Environment Variables

Frontend Environment Variables

The frontend requires these environment variables at build time:

NEXT_PUBLIC_AWS_REGION=us-east-1
NEXT_PUBLIC_USER_POOL_ID=<cognito-user-pool-id>
NEXT_PUBLIC_USER_POOL_WEB_CLIENT_ID=<cognito-client-id>
NEXT_PUBLIC_API_URL=<api-gateway-url>

Local Development

For local development, copy .env.local.example to .env.local:

cd frontend
cp .env.local.example .env.local

Then get Cognito values from Terraform:

cd infrastructure/terraform
terraform output cognito_user_pool_id
terraform output cognito_web_client_id

Update .env.local with these values.

Production Deployment

The deployment script automatically handles this!

When you run ./scripts/deployment/deploy-frontend.sh, it:

  1. Loads Cognito credentials from .env.infrastructure
  2. Sets them as environment variables during the build
  3. Next.js embeds them in the compiled JavaScript

You don’t need to manually set these for production deployment.

Authentication Setup

Initial Admin User

After deployment, create an admin user:

  1. Via AWS Console:
    • Go to AWS Cognito → User Pools → momentum-dev-user-pool
    • Create a new user
    • Add the user to the “admin” group
  2. Via AWS CLI: 
    # Create user
aws cognito-idp admin-create-user \
  --user-pool-id <user-pool-id> \
  --username admin@yourdomain.com \
  --user-attributes Name=email,Value=admin@yourdomain.com Name=name,Value="Admin User" \
  --temporary-password "TempPassword123!"

# Add to admin group
aws cognito-idp admin-add-user-to-group \
  --user-pool-id <user-pool-id> \
  --username admin@yourdomain.com \
  --group-name admin
  3. First Login:
    • Navigate to your website
    • Click “Sign In”
    • Use the temporary password
    • You’ll be prompted to change it

User Groups

Three user groups are configured:

  • admin: Full access to admin panel, can create/edit/delete courses
  • premium: Access to all courses (paid tier)
  • free: Access to free courses only

Users are automatically added to the “free” group on signup. Admins can promote users via Cognito.

Verifying Deployment

Check Infrastructure 

cd infrastructure/terraform
terraform output

Verify all outputs are present:

  • website_url
  • api_gateway_url
  • cognito_user_pool_id
  • cognito_web_client_id

Test Website 

# Get website URL
WEBSITE_URL=$(cd infrastructure/terraform && terraform output -raw website_url)

# Test accessibility
curl -I $WEBSITE_URL

Expected: HTTP 200 OK

Test Authentication

  1. Navigate to https://your-domain.com
  2. Click “Sign In” or “Start Free Trial”
  3. Verify you’re redirected to /auth/signin or /auth/signup
  4. Create a test account and sign in
  5. Verify redirect to dashboard

Test API 

# Get API URL
API_URL=$(cd infrastructure/terraform && terraform output -raw api_gateway_url)

# Test courses endpoint
curl $API_URL/courses

Redeployment

Update Frontend Only 

./scripts/deployment/deploy-frontend.sh

Update Backend Only 

./scripts/deployment/deploy-backend.sh

Update Infrastructure 

./scripts/deployment/deploy-infrastructure.sh

Note: Infrastructure changes may require manual approval in Terraform.

Troubleshooting

“Cognito is not configured” Error

Symptom: Frontend shows error about missing Cognito configuration.

Solution:

  1. Check .env.infrastructure has Cognito values: 
    grep COGNITO .env.infrastructure
  2. If missing, redeploy infrastructure: 
    ./scripts/deployment/deploy-infrastructure.sh
  3. Redeploy frontend to pick up new values: 
    ./scripts/deployment/deploy-frontend.sh

Frontend Not Updating

Symptom: Changes not visible on website.

Solution:

  1. CloudFront caching - wait 5-10 minutes
  2. Force cache invalidation: 
    DIST_ID=$(cd infrastructure/terraform && terraform output -raw cloudfront_distribution_id)
aws cloudfront create-invalidation --distribution-id $DIST_ID --paths "/*"

Authentication Not Working

Symptom: Users can’t sign in/sign up.

Solution:

  1. Check Cognito User Pool exists: 
    aws cognito-idp list-user-pools --max-results 10
  2. Verify frontend has correct Cognito configuration:
    • Open browser developer console
    • Look for errors related to Cognito
    • Verify network requests to cognito-idp.us-east-1.amazonaws.com
  3. Check Lambda triggers are deployed: 
    aws lambda list-functions | grep cognito

Destroying Infrastructure

⚠️ Warning: This will delete all resources and data!

./scripts/deployment/destroy-infrastructure.sh

You’ll be prompted to confirm before destruction.

Cost Optimization

  • Development: Infrastructure costs ~$50-100/month with minimal usage
  • Production: Scales with usage, budget ~$200-500/month for moderate traffic

Cost-Saving Tips

  1. Delete development environments when not in use
  2. Use Aurora Serverless auto-pause (pauses after 5 min inactivity)
  3. Enable S3 Intelligent-Tiering for automatic cost optimization
  4. Set up AWS Budgets to alert on unexpected costs

Next Steps

After successful deployment:

  1. ✅ Create admin user (see Authentication Setup above)
  2. ✅ Test authentication flow
  3. ✅ Access admin panel at /admin
  4. ✅ Create your first course
  5. ✅ Set up monitoring and alerts
  6. ✅ Configure custom domain (if not using default)

Support

For issues or questions:

  • Check logs in CloudWatch
  • Review Terraform state
  • Contact DevOps team

Last Updated: November 15, 2025 Version: 1.0 Maintainer: CloudNNJ Development Team

Back to top

Momentum LMS © 2025. Distributed under the MIT license.