Skip to content

Getting Started

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

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 need AWS credentials to deploy the infrastructure.

If you need to create an AWS account, set up IAM users, or understand AWS permissions, follow the comprehensive AWS Configuration Guide which covers:

  • Creating an AWS account
  • Setting up IAM users and permissions
  • Creating access keys
  • Security best practices
  • Troubleshooting common issues

4. Set CDK Environment Variables

The CDK deployment requires some environment variables. Put these in a copy of infra/.env.example, calling it infra/.env.

# Replace with your 12-digit AWS account ID
CDK_ACCOUNT=123456789012
CDK_REGION=us-east-1

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 by copying the example file and updating it:

# Copy the example environment file
cp web/.env.example web/.env.local

Then edit web/.env.local and replace the placeholder with your actual API URL from step 6:

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

Important: Make sure the URL ends with a trailing slash /

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. Start contributing - Read the Contributing Guide for development workflow
  2. Explore the code - Check out the Project Overview for architecture details
  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 Contributing Guide for development workflow and collaboration
  • Review the AWS Configuration Guide for detailed AWS setup
  • 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