Skip to content

Getting Started

Jump to bottom
Rohit Dasgupta edited this page Sep 24, 2025 · 4 revisions

Getting Started

This guide will walk you through setting up the UF r/place project on your local machine and deploying it to AWS.

Prerequisites

Before you begin, make sure you have:

Required Software

AWS Account Setup

Verify Prerequisites

# Check Node.js version (should be 18+)
node --version

# Check npm version
npm --version

# Check Git
git --version

# Check AWS CLI
aws --version

Quick Start

1. Clone the Repository

git clone https://github.com/ufosc/UF_r-place.git
cd UF_r-place

2. Install Dependencies

# Install all dependencies for both workspaces
npm install

This will install dependencies for:

  • Root workspace (build scripts)
  • infra/ workspace (CDK and infrastructure dependencies)
  • web/ workspace (Next.js and frontend dependencies)

3. Configure AWS Credentials

Important: Before proceeding, follow the AWS Configuration Guide to:

  • Set up your AWS account and credentials
  • Ensure you have the required permissions for CDK deployment
  • Configure AWS CLI or environment variables

Once configured, verify your setup:

aws sts get-caller-identity

4. Set CDK Environment Variables

Set the required CDK environment variables (see AWS Configuration Guide for details):

# Set your AWS account ID and region
export CDK_ACCOUNT=$(aws sts get-caller-identity --query Account --output text)
export CDK_REGION=$(aws configure get region)

# Verify they're set correctly
echo "Account: $CDK_ACCOUNT, Region: $CDK_REGION"

5. Bootstrap CDK (First Time Only)

This is a one-time setup per AWS account and region:

npm run cdk:bootstrap

If you see an error about unable to resolve AWS account, make sure you've completed step 4 above.

6. Deploy the Backend Infrastructure

npm run cdk:deploy

This will:

  • Build the TypeScript infrastructure code
  • Create AWS resources (Lambda function, API Gateway)
  • Deploy your stack to AWS
  • Output the API URL when complete

Important: Save the ApiUrl output from this command - you'll need it in the next step.

7. Configure Frontend Environment

Create the environment file for the frontend:

# Replace <ApiUrl> with the URL from the previous step
echo "NEXT_PUBLIC_API_URL=<paste-api-url-here>" > web/.env.local

Example:

echo "NEXT_PUBLIC_API_URL=https://abc123def4.execute-api.us-east-1.amazonaws.com/prod/" > web/.env.local

8. Run the Frontend Locally

npm run dev

This starts the Next.js development server at http://localhost:3000

9. Test the Application

  1. Open your browser to http://localhost:3000
  2. You should see "UF r/place" as the heading
  3. Below it should display "API says: Hello from UF r/place API!"

If you see an error message instead, check:

  • The API URL in web/.env.local is correct and ends with /
  • The backend deployment completed successfully
  • Your AWS credentials are still valid

Development Workflow

Making Changes to the Backend

  1. Modify Lambda functions in infra/lambda/
  2. Update infrastructure in infra/lib/
  3. Deploy changes: 
    npm run cdk:deploy

Making Changes to the Frontend

  1. Modify components in web/app/
  2. Changes are automatically hot-reloaded when running npm run dev
  3. For production builds: 
    npm run build

Available Scripts

From the root directory:

# Development
npm run dev          # Start frontend dev server
npm run build        # Build both frontend and backend
npm run lint         # Run linting

# Deployment
npm run deploy       # Deploy backend infrastructure
npm run cdk:deploy   # Same as above
npm run cdk:bootstrap # Bootstrap CDK (one-time setup)

From individual workspaces:

# Backend (from infra/ directory)
npm run build        # Compile TypeScript
npm run synth        # Generate CloudFormation templates
npm run deploy       # Deploy to AWS
npm run destroy      # Remove all AWS resources

# Frontend (from web/ directory)
npm run dev          # Start development server
npm run build        # Build for production
npm run start        # Start production server
npm run lint         # Run ESLint

Project Structure Overview

UF_r-place/
├── package.json              # Root workspace & scripts
├── infra/                   # AWS Infrastructure
│   ├── bin/app.ts          # CDK app entry point
│   ├── lib/                # Infrastructure definitions
│   ├── lambda/             # Lambda function code
│   └── cdk.out/           # Generated CloudFormation (git-ignored)
└── web/                    # Next.js Frontend
    ├── app/               # App Router pages & components
    ├── .env.local        # Environment variables (git-ignored)
    └── .next/            # Next.js build output (git-ignored)

Troubleshooting

"Unable to resolve AWS account to use"

This means CDK couldn't determine your AWS account/region. See the AWS Configuration Guide for detailed troubleshooting. Quick check:

  1. Verify AWS credentials: aws sts get-caller-identity
  2. Set CDK environment variables: export CDK_ACCOUNT=... CDK_REGION=...

API URL not working

  • Ensure the URL in web/.env.local ends with /
  • Check that the backend deployment completed successfully
  • Verify the API Gateway was created in the AWS console

"Error: NEXT_PUBLIC_API_URL not set"

You need to create web/.env.local with the API URL from step 7.

CDK Bootstrap fails

Check the AWS Configuration Guide for detailed troubleshooting steps. Common issues include:

  • Missing required AWS permissions (see the permissions section)
  • CDK environment variables not set correctly
  • AWS credentials not configured properly

Cleanup and Resource Management

Destroying Project Resources

When you're done experimenting or want to clean up AWS resources to avoid any potential costs:

# Remove all project resources (recommended)
npm run destroy

# Alternative command (same effect)
npm run cdk:destroy

This will delete:

  • Lambda functions
  • API Gateway
  • CloudWatch log groups
  • IAM roles created for the project
  • The entire CloudFormation stack (UfRPlaceBackend)

Complete AWS Cleanup (Optional)

If you want to remove everything including CDK bootstrap resources:

# 1. First destroy project resources
npm run destroy

# 2. Then remove CDK bootstrap stack (only if you won't use CDK again)
aws cloudformation delete-stack --stack-name CDKToolkit

# 3. Verify cleanup
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE

Note: The CDK bootstrap resources (CDKToolkit stack) cost ~$0.02/month and can be reused for other CDK projects.

Verification

To check what resources remain:

# Check CloudFormation stacks
aws cloudformation list-stacks --stack-status-filter CREATE_COMPLETE

# Check Lambda functions
aws lambda list-functions --query 'Functions[?starts_with(FunctionName, `UfRPlace`)].FunctionName'

For detailed cleanup instructions, see the AWS Configuration Guide.

Next Steps

Once you have the basic setup working:

  1. Review AWS configuration - Check the AWS Configuration Guide for security best practices and production setup
  2. Explore the code - Check out the Project Overview for architecture details
  3. Add new features - See the Extensibility Guide
  4. Deploy to production - Consider setting up CI/CD pipelines

Getting Help

  • Check the AWS Configuration Guide for detailed AWS setup
  • Review the Extensibility Guide for adding new features
  • Look at the existing code in infra/ and web/ directories
  • Check AWS CloudWatch logs for Lambda function errors
  • Use npm run synth to see generated CloudFormation templates
Clone this wiki locally