​
Quick Start Guide

Get your FindU development environment set up and make your first contribution.

​
Prerequisites

Before you begin, ensure you have:

Required Tools

  • Git (v2.30+)
  • Node.js (v18+ LTS)
  • Python 3.8+
  • Docker Desktop
  • Supabase CLI
  • Xcode (for iOS development)

Access Needed

  • GitHub organization access
  • Supabase credentials
  • Slack workspace invite
  • Railway access (optional)

​
Installing Prerequisites

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install required tools
brew install git node python3
brew install supabase/tap/supabase

# Install Docker Desktop
# Download from: https://www.docker.com/products/docker-desktop

# For iOS development
# Install Xcode from App Store
Don’t have access yet? See our onboarding checklist for new team members.

​
Automated Setup

We’ve created a script that sets up your entire development environment: 
# Clone the dev-tools repository
git clone https://github.com/findu-app/dev-tools.git

# Run the setup script from the parent directory (important!)
./dev-tools/scripts/setup.sh
Do NOT cd into dev-tools before running the script. Run it from the parent directory.
This script will:
  1. Clone all FindU repositories (~5 minutes)
  2. Prompt to install dependencies for each project (~10-15 minutes if yes)
  3. Create your .env.local configuration template
  4. Prompt to set up pre-commit hooks
  5. Configure the findu CLI tool
First time setup takes approximately 15-20 minutes with dependency installation.

​
Manual Setup (Alternative)

If you prefer manual setup or need to troubleshoot:
1

Clone Repositories

mkdir ~/findu && cd ~/findu
git clone https://github.com/findu-app/ios_app.git
git clone https://github.com/findu-app/web_app.git
git clone https://github.com/findu-app/supabase.git
git clone https://github.com/findu-app/matching-algorithm.git
2

Install Dependencies

# Web app
cd web_app && npm install

# iOS app
cd ../ios_app && pod install

# ML engine
cd ../matching-algorithm
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
3

Configure Environment

The setup script creates .env.local with placeholders. Get real credentials from your team lead:Required for basic development:
  • SUPABASE_PROJECT_ID_DEV
  • SUPABASE_URL_DEV
  • SUPABASE_ANON_KEY_DEV
Optional (can use defaults):
  • Service role keys
  • OAuth credentials
  • API tokens

​
Verify Your Setup

Run these commands to verify everything is working: 
# Check environment and CLI
./findu env status
# Should show: Current environment: dev

# Check if repositories were cloned
ls -la
# Should show: ios_app, web_app, supabase, matching-algorithm, data_scraping, docs

# Verify Docker is running (required for Supabase)
docker ps
# Should show Docker containers or empty list (not an error)

# If you installed dependencies, test web app
cd web_app && npm run dev
# Should start development server on http://localhost:5173

# Test Supabase CLI (requires Docker)
cd ../supabase && supabase start
# First run will download Docker images (~1-2 minutes)

​
Make Your First Change

1

Switch to dev branch

cd ~/findu/web_app
git checkout dev
git pull origin dev
2

Create feature branch

git checkout -b feature/your-name-first-pr
3

Make a small change

Edit any file (try updating a comment or fixing a typo)
4

Commit and push

git add .
git commit -m "My first FindU commit"
git push -u origin feature/your-name-first-pr
5

Open PR

Go to GitHub and create a pull request targeting the dev branch

​
Next Steps

Understand the Architecture

Learn how all the pieces fit together

Development Workflow

Master our git workflow and best practices

Find an Issue

Browse good first issues to work on

Join Slack

Connect with the team for help
Always create branches from dev, not main! Our main branch is protected and only receives updates from dev.