Skip to Content
API v2Setup

Setup

Prerequisites

  • PHP 8.2+
  • Composer
  • Node.js 18+
  • MySQL (or MariaDB)
  • Redis (optional, for caching/queues)

Installation

# Clone the repo
git clone <repo-url>
cd Housr-API2
 
# Install PHP dependencies
composer install
 
# Install Node dependencies (for Vite module assets)
npm install
 
# Copy environment file
cp .env.example .env
 
# Generate app key
php artisan key:generate

Environment Variables

Core Laravel

VariableDescriptionDefault
APP_NAMEApplication nameHousr-API2
APP_ENVEnvironment (local/staging/production)local
APP_DEBUGEnable debug modetrue
APP_URLBase URLhttp://localhost:8080
APP_KEYEncryption key (generate with artisan key:generate)—

Database

VariableDescriptionDefault
DB_CONNECTIONDatabase drivermysql
DB_HOSTDatabase host127.0.0.1
DB_PORTDatabase port3306
DB_DATABASEMain database namehousr_database_dev
DB_USERNAMEDatabase user—
DB_PASSWORDDatabase password—
DB_DATABASE_BILLSBills database namehousr_bills_dev
DB_BILLS_DRIVERBills DB drivermysql

Authentication

VariableDescriptionDefault
JWT_KEYShared JWT secret (must match API v1)example_key
EXTERNAL_JWT_KEYExternal JWT secretexample_key

Region

VariableDescriptionDefault
USARun in US mode (true/false)false

Third-Party Services

VariableDescription
SENTRY_LARAVEL_DSNSentry error tracking DSN
MAILGUN_DOMAIN / MAILGUN_SECRETMailgun email delivery
TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN / TWILIO_FROMTwilio SMS
HUBSPOT_API_KEYHubSpot CRM API key
MAPBOX_ACCESS_TOKENMapbox maps
HUDDLE_API_URL / HUDDLE_PUBLIC_API_KEY / HUDDLE_SECRET_API_KEYHuddle address lookup
VERIFALIA_USERNAME / VERIFALIA_PASSWORDEmail validation
MAILCHIMP_API_KEY / MAILCHIMP_SERVER / MAILCHIMP_MARKETING_LIST_IDMailchimp newsletters
FIREBASE_CREDENTIALSFirebase service account JSON (as string)
FIREBASE_DATABASE_URLFirebase Realtime Database URL
AUTHORIZATION_KEYShared webhook authorization key
QUOTE_PREFILL_EXTERNAL_API_KEYExternal quote prefill API key
PROPERTIES_API_BASE_URL / REAPIT_CLIENT_ID / REAPIT_CLIENT_SECRETReapit property API

Storage

VariableDescription
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEYAWS credentials
AWS_PUBLIC_IMAGES_ACCESS_KEY_ID / AWS_PUBLIC_IMAGES_SECRET_ACCESS_KEYPublic images S3 credentials

Database Setup

The application uses two MySQL databases:

  1. Main database (DB_DATABASE): Shared with API v1 and Portal. Contains users, houses, cities, feature flags, etc.
  2. Bills database (DB_DATABASE_BILLS): Bills-specific tables (contracts, tenants, pricing, regions).
# Create databases
mysql -u root -e "CREATE DATABASE housr_database_dev;"
mysql -u root -e "CREATE DATABASE housr_bills_dev;"
 
# Run migrations
php artisan migrate

See database.md for details on the multi-database setup.

Running the Dev Server

The recommended way to run all dev services:

composer dev

This starts:

  • API server on http://localhost:8001
  • Queue worker for async jobs
  • Log viewer (Laravel Pail) for real-time log output
  • Vite for module asset compilation

Alternatively, run just the server:

php artisan serve --port=8001

Docker

A Docker Compose setup is available for local development:

docker-compose up

This runs the app on port 8000 with the DB host set to host.docker.internal for connecting to a local MySQL instance.

Last updated on
OverviewArchitecture