Getting Started

This guide walks you through setting up the Housr development environment from scratch.

Prerequisites

1. Install Homebrew

Homebrew is the package manager used to install almost everything below. If you don’t have it:


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

Follow the printed instructions to add Homebrew to your PATH (required on Apple Silicon Macs).

2. Install core tools


# Node version manager — lets you switch Node versions per project
brew install nvm
 
# Add nvm to your shell (add these lines to ~/.zshrc or ~/.bash_profile)
export NVM_DIR="$HOME/.nvm"
[ -s "$(brew --prefix)/opt/nvm/nvm.sh" ] && \. "$(brew --prefix)/opt/nvm/nvm.sh"
 
# Then install Node 18 (LTS)
nvm install 18
nvm use 18
nvm alias default 18


# PHP 8.2
brew install php@8.2
echo 'export PATH="$(brew --prefix php@8.2)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
 
# Composer (PHP dependency manager)
brew install composer


# MySQL 8.0
brew install mysql@8.0
brew services start mysql@8.0
echo 'export PATH="$(brew --prefix mysql@8.0)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc


# Docker Desktop (includes Docker Compose)
brew install --cask docker
# Then open Docker.app from Applications to complete setup

Verify everything is installed:


node -v       # should be v18.x
php -v        # should be 8.2.x
composer -V
mysql --version
docker --version

3. Additional tools for mobile development


# Xcode — install from the Mac App Store, then install CLI tools:
xcode-select --install
 
# Android Studio — download from https://developer.android.com/studio
# After installing, open Android Studio → SDK Manager and install:
#   - Android SDK Platform (API 34+)
#   - Android Emulator
#   - Android SDK Build-Tools
 
# EAS CLI for Expo cloud builds
npm install -g eas-cli

Tool summary

Tool	Version	Install method
Node.js	18+	`nvm install 18`
PHP	8.2+	`brew install php@8.2`
Composer	Latest	`brew install composer`
MySQL	8.0+	`brew install mysql@8.0`
Redis	Latest	`brew install redis`
Docker	Latest	`brew install --cask docker`
Xcode	Latest	Mac App Store
Android Studio	Latest	developer.android.com

Clone the Repos

All Housr repos live under a single parent directory. Clone the core repos:


mkdir -p ~/Housr/Repos && cd ~/Housr/Repos
 
git clone git@github.com:Housr/Housr-Webapp.git
git clone git@github.com:Housr/Housr-App.git
git clone git@github.com:Housr/Housr-API.git
git clone git@github.com:Housr/Housr-API2.git
git clone git@github.com:Housr/Housr-Portal.git

Quick Start per Repo

Each repo has its own setup instructions in docs/setup.md. Here is the short version:

Housr-Webapp (Next.js)


cd Housr-Webapp
cp .env.example .env.local    # Fill in API URLs, Mapbox token, etc.
npm install
npm run dev                    # http://localhost:3000

Housr-App (Expo)


cd Housr-App
cp .env.example .env           # Set EXPO_PUBLIC_USA_MODE, API URLs, Firebase config
npm install
npm start                      # Expo dev server
npm run ios                    # Or: npm run android

Housr-API (Laravel v1)


cd Housr-API
cp .env.example .env
composer install
php artisan key:generate
php artisan migrate
php artisan serve              # http://localhost:8000

Housr-API2 (Laravel Modules v2)


cd Housr-API2
cp .env.example .env
composer install
php artisan key:generate
php artisan module:migrate     # Runs migrations for all modules
php artisan serve --port=8001  # http://localhost:8001

Housr Portal (Laravel + Filament)


cd "Housr Portal"
cp .env.example .env
composer install
php artisan key:generate
php artisan migrate
php artisan serve --port=8002  # http://localhost:8002

Environment Variables

Each repo has its own .env file. There is no shared env. Key things to configure:

Database: All PHP backends (API v1, API v2, Portal) point at the same MySQL database
API URLs: Webapp and App need the URLs of running API v1 and v2 instances
Firebase: App and API both need Firebase credentials
Third-party keys: Mapbox, Finix, HubSpot, etc. — see each repo’s .env.example

Common Development Workflows

Working on a mobile feature

Run these simultaneously:

API v2 (php artisan serve --port=8001)
API v1 (php artisan serve --port=8000) — if the feature uses legacy endpoints
Expo dev server (npm start in Housr-App)
iOS simulator or Android emulator

Working on the webapp

API v2 (php artisan serve --port=8001)
Next.js dev server (npm run dev in Housr-Webapp)

Working on the admin portal

Portal dev server (php artisan serve --port=8002 in Housr Portal)
The portal shares the same database as the APIs — no API server needed for most tasks

Working on API endpoints

Run the relevant API server
Use a tool like Postman or curl to test endpoints
If the endpoint is consumed by the App or Webapp, run those too for integration testing