Skip to content

Getting Started

Jump to bottom
Rohit Dasgupta edited this page Sep 23, 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

You have several options for setting up AWS credentials. Choose the one that works best for you:

Option A: Using AWS CLI (Recommended)

aws configure

Option B: Using Environment Variables

export AWS_ACCESS_KEY_ID=your-access-key-id
export AWS_SECRET_ACCESS_KEY=your-secret-access-key
export AWS_DEFAULT_REGION=us-east-1

Option C: Using AWS Profiles

# Configure a named profile
aws configure --profile myprofile

# Use the profile
export AWS_PROFILE=myprofile

4. Set CDK Environment Variables

# Replace with your 12-digit AWS account ID
export CDK_ACCOUNT=123456789012

# Choose your preferred region
export CDK_REGION=us-east-1

To find your AWS account ID:

aws sts get-caller-identity --query Account --output text

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. Make sure you've:

  1. Set up AWS credentials (step 3)
  2. Exported CDK_ACCOUNT and CDK_REGION (step 4)
  3. Run aws sts get-caller-identity to verify your credentials work

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

Make sure you have the necessary permissions in your AWS account. You need permissions to create IAM roles, S3 buckets, and other resources.

Next Steps

Once you have the basic setup working:

  1. Explore the code - Check out the Project Overview for architecture details
  2. Add new features - See the Extensibility Guide
  3. Set up additional AWS resources - Follow the AWS Configuration 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