Setup

Prerequisites

Docker and Docker Compose
A populated .env file (copy from .env.example)

Local Development


# Build and start the container
docker compose up --build
 
# The API is accessible at http://localhost/api/
# Example: http://localhost/api/login.php

The docker-compose.yml mounts the following as bind volumes for hot-reloading during development:

./api -> /var/www/api (endpoint files)
./deploy/deploy.conf -> Nginx server config
./deploy/nginx.conf -> Nginx main config
./deploy/run -> Container entrypoint
./.env -> Environment file
./docker/xdebug.ini -> Xdebug config
./vendor -> Composer dependencies

PHP OPcache timestamp validation is enabled in development (PHP_OPCACHE_VALIDATE_TIMESTAMPS=1), so file changes are picked up without restarting.

Docker Image

The Dockerfile builds on a custom PHP 8.2-FPM base image. It installs:

PHP extensions: mysqli, pdo, pdo_mysql, pdo_pgsql, bcmath, gd, zip, opcache, exif, xdebug
Nginx
SimpleSAMLphp 2.2.2 (for US university SSO)
Composer dependencies

The container runs both Nginx (port 80) and PHP-FPM (port 9000) via the deploy/run entrypoint script.

Environment Variables

Database

Variable	Description	Example
`DB_SERVER`	MySQL host	`housr-database-instance-1.xxx.rds.amazonaws.com`
`DB_USERNAME`	MySQL username	`admin`
`DB_PASSWORD`	MySQL password	(from AWS Secrets Manager in production)
`DB_DATABASE`	Main database name	`housr_database_prod`
`DB_DATABASE_BILLS`	Bills database name (UK only)	`housr_bills_prod`
`DB_PORT`	MySQL port	`3306`
`DB_CONNECTION`	Connection type	`mysql`

Application

Variable	Description	Example
`APP_ENV`	Environment name	`production`, `us_prod`, `development`, `uat`, `demo`
`USA`	Regional flag (truthy = US mode)	`true` or omitted for UK
`URL`	Base API URL	`https://api.uk.housr.com/`
`PORTAL_URL`	Portal URL (for email links)	`https://housrportal.co.uk`

Services

Variable	Description
`SENTRY_DSN`	Sentry error tracking DSN
`SENTRY_ENVIRONMENT`	Sentry environment label
`SENTRY_TRACES_SAMPLE_RATE`	Sentry tracing rate (0.0-1.0)
`FIREBASE_CREDENTIALS`	Firebase service account JSON
`FIREBASE_DATABASE_URL`	Firebase Realtime DB URL
`HUBSPOT_API_KEY`	HubSpot API access token
`FINIX_USERNAME`	Finix API username
`FINIX_PASSWORD`	Finix API password
`FINIX_MERCHANT_ID`	Finix merchant ID
`FINIX_API_URL`	Finix API base URL
`EXTERNAL_API_KEY`	API key for external endpoints
`BRAND_PORTAL_URL`	Brand portal base URL
`BRAND_PORTAL_SECRET_KEY`	Brand portal secret
`HUDDLE_API_URL`	Huddle (bills provider) API URL
`HUDDLE_PUBLIC_API_KEY`	Huddle public key
`HUDDLE_SECRET_API_KEY`	Huddle secret key
`APPLE_API_URL`	Apple StoreKit API URL
`APPLE_API_SECRET`	Apple API secret
`GOOGLE_PLAY_SERVICE_ACCOUNT`	Google Play service account JSON
`VERIFALIA_USERNAME`	Verifalia email verification username
`VERIFALIA_PASSWORD`	Verifalia email verification password
`STARREZ_USERNAME`	StarRez integration username
`STARREZ_PASSWORD`	StarRez integration password
`ENTRATA_CLIENT_ID`	Entrata OAuth client ID (US only)
`ENTRATA_CLIENT_SECRET`	Entrata OAuth client secret (US only)

Xdebug

Xdebug is installed in the Docker image. Configuration is loaded from docker/xdebug.ini via a bind mount. Enable it for step debugging during local development.