Getting Started
Getting Started
Everything you need to clone, configure, and run the BizTech app locally, covering both the frontend and backend.
Prerequisites
Before you begin, make sure you have the following installed on your machine:
| Tool | Version | How to Install |
|---|---|---|
| Node.js | v20+ (LTS recommended) | nodejs.org or brew install node |
| npm | v9+ (comes with Node) | Included with Node.js |
| Git | Latest | brew install git or git-scm.com |
| AWS CLI | v2 | brew install awscli or AWS docs |
| Serverless Framework | v3 | npm install -g serverless@3 |
| Java (for local DynamoDB) | JRE 11+ | brew install openjdk@11 |
macOS Users
We recommend using Homebrew to install tools. On Windows, use WSL2 (Windows Subsystem for Linux) for the best experience.
Repository Overview
BizTech has two main repositories:
| Repository | What it is | Tech Stack |
|---|---|---|
bt-web-v2 | Frontend web app | Next.js 14, TypeScript, Tailwind, AWS Amplify |
serverless-biztechapp-1 | Backend API | Serverless Framework, Node.js 20, AWS Lambda, DynamoDB |
Both repos should be cloned into the same parent directory for the easiest setup:
mkdir ~/BizTech && cd ~/BizTech
git clone https://github.com/ubc-biztech/bt-web-v2.git
git clone https://github.com/ubc-biztech/serverless-biztechapp-1.git
Setting Up the Backend
1. Install dependencies
cd serverless-biztechapp-1
npm install
2. Environment configuration
The backend uses three config files for different environments: config.dev.json, config.staging.json, and config.prod.json. When running locally, the dev config is used by default.
The key difference between environments:
| Config Key | Dev / Staging | Production |
|---|---|---|
ENVIRONMENT | "" (empty string) | "PROD" |
REQUIRE_API_KEY | false | true |
Table Name Suffixes
All DynamoDB table names automatically get the ENVIRONMENT value appended. In dev, tables are biztechEvents. In production, they become biztechEventsPROD. This prevents accidentally writing to production data.
3. Set up local DynamoDB
The backend uses a local DynamoDB instance for development. First install the Serverless DynamoDB plugin, then seed the database:
# Install DynamoDB Local (one-time setup)
npx sls dynamodb install
# Seed local DB with a copy of production data (requires AWS credentials)
node scripts/initlocal.js
AWS Credentials Required
You need valid AWS credentials configured (~/.aws/credentials) with access to the BizTech AWS account to run the seed script. Ask the dev lead for access.
4. Set up environment variables
Create a .env file in the backend root (or export these in your shell):
# Required for local development
ENVIRONMENT=""
REACT_APP_STAGE=dev
# Stripe (for payments)
STRIPE_KEY=sk_test_...
STRIPE_MEMBERSHIP_PRICE_ID=price_...
# SendGrid (for registration emails)
SENDGRID_KEY=SG...
# Algolia (for profile search)
ALGOLIA_APP_ID=...
ALGOLIA_ADMIN_API_KEY=...
# OpenAI (for profile recommendations)
OPENAI_API_KEY=sk-...
# Slack/Discord (for bot integrations)
SLACK_BOT_TOKEN=xoxb-...
DISCORD_BOT_TOKEN=...
DISCORD_APP_ID=...
DISCORD_PUBLIC_KEY=...
Never Commit Secrets
Never commit .env files or API keys to Git. These files are in .gitignore. Ask in the slack for the dev environment keys.
5. Start the backend
npm start
This starts all 19 services simultaneously using concurrently. Each service runs on its own port (4001–4019), and a lightweight proxy runs on port 4000 that routes requests to the correct service.
| Port | What's on it |
|---|---|
| 4000 | Main proxy (send all requests here) |
| 4001 | hello (health check) |
| 4002 | events |
| 4003 | registrations |
| 4004 | members |
| 4005 | users |
| 4006 | payments |
| 4007 | teams |
| ... | ...and so on up to 4019 |
Verify it's working:
curl http://localhost:4000/hello
# Should return: "Hello World"
Setting Up the Frontend
1. Install dependencies
cd bt-web-v2
npm install
2. Environment variables
Create a .env.local file in the frontend root:
# Points the frontend to your local backend
NEXT_PUBLIC_STAGE=local
# AWS Amplify config (uses the staging Cognito pool for local dev)
# These are already configured in amplify_outputs.json, no action needed
The NEXT_PUBLIC_STAGE variable controls which backend URL the frontend talks to:
| Value | Backend URL |
|---|---|
local | http://localhost:4000 |
dev / staging | https://api-dev.ubcbiztech.com |
prod | https://api.ubcbiztech.com |
Running Without the Backend
If you set NEXT_PUBLIC_STAGE=dev instead of local, the frontend will talk to the deployed dev backend. This is useful if you're only working on frontend changes and don't want to run the backend locally.
3. Start the development server
npm run dev
The app will be available at http://localhost:3000.
4. Login
- Visit
http://localhost:3000/login - Use your
@ubcbiztech.comemail to log in (this automatically grants admin access) - Alternatively, use Google OAuth if configured
Project Scripts Cheat Sheet
Frontend (bt-web-v2)
| Command | What it does |
|---|---|
npm run dev | Start the dev server on port 3000 |
npm run build | Build for production |
npm run lint | Run ESLint |
npx tsc --noEmit | Type-check without building |
Backend (serverless-biztechapp-1)
| Command | What it does |
|---|---|
npm start | Start all 19 services locally |
npm test | Run all unit tests |
node scripts/initlocal.js | Seed local DynamoDB from production |
npx sls deploy --stage dev | Deploy to dev environment |
npx sls deploy --stage prod | Deploy to production |
Common Issues & Fixes
"Cannot connect to DynamoDB Local"
Make sure Java is installed and DynamoDB Local is running:
java -version # Should show JRE 11+
npx sls dynamodb install # Re-install if needed
"401 Unauthorized" on API calls
Your Cognito session may have expired. Log out and log back in. If running locally, make sure the frontend's NEXT_PUBLIC_STAGE matches how you're running the backend.
"Module not found" errors
Try clearing your node_modules and reinstalling:
rm -rf node_modules package-lock.json
npm install
Port conflicts
If ports 4000–4019 are in use, kill existing processes:
lsof -ti:4000 | xargs kill -9
Amplify/Auth issues locally
The frontend uses the staging Cognito User Pool for local development (configured in amplify_outputs.json). If you're getting auth errors, verify the Amplify config is pointing to the correct pool.
Next Steps
Once you have both the frontend and backend running locally:
- Read the Frontend Architecture guide to understand how the Next.js app is structured
- Read the Backend Architecture guide to understand the serverless services
- Check the Database Guide to understand our DynamoDB tables
- Read the Authentication guide to understand the auth flow