Skip to main content
1

Install prerequisites

Before cloning the repo, make sure you have the following installed:
ToolRequired versionNotes
Node.js22Check with node -v. Use nvm to switch versions.
Yarnanybrew install yarn on macOS
PostgreSQL15brew install postgresql@15, then brew services start postgresql@15
If you see env: node: No such file or directory after installing Node, check the installer output for instructions on adding Node to your shell’s PATH.
2

Clone and install dependencies

Clone the repository, then install dependencies from two locations — the workspace root and the api directory:
git clone https://github.com/bloom-housing/bloom.git
cd bloom

yarn install

cd api && yarn install
The root yarn install installs dependencies for sites/public, sites/partners, and shared-helpers via Yarn workspaces. The api directory manages its own separate dependency tree.
3

Set up environment variables

Each of the three packages needs its own .env file copied from the provided template:
cp api/.env.template api/.env
Key variables to review in each file:api/.env
DATABASE_URL="postgres://<username>@localhost:5432/bloom_prisma"
PORT=3100
APP_SECRET="some-long-secret-key"
API_PASS_KEY="some-key-here"
CORS_ORIGINS=["http://localhost:3000", "http://localhost:3001"]
TIME_ZONE=America/Los_Angeles
NODE_ENV=development
DB_NO_SSL="TRUE"
sites/public/.env
BACKEND_API_BASE=http://127.0.0.1:3100
BACKEND_API_BASE_NEW=http://127.0.0.1:3100
NEXTJS_PORT=3000
JURISDICTION_NAME=Bloomington
LANGUAGES=en,es,zh,vi,tl,bn,ar,ko,hy,fa
API_PASS_KEY="some-key-here"
LISTINGS_QUERY=/listings
sites/partners/.env
BACKEND_API_BASE=http://localhost:3100
NEXTJS_PORT=3001
API_PASS_KEY="some-key-here"
LISTINGS_QUERY=/listings
Some variables — such as APP_SECRET, EMAIL_API_KEY, CLOUDINARY_SECRET, and TWILIO_AUTH_TOKEN — are secret keys that are not committed to the repository. These are available internally via the team’s password manager. Request access from the Bloom team if you need them for a non-default local workflow.
4

Set up the database

From within the api directory, run:
cd api
yarn setup
This single command:
  1. Generates the Prisma client from schema.prisma
  2. Runs all pending database migrations against bloom_prisma
  3. Seeds the database with jurisdiction and listing data that mirrors the core Bloom environments
If this is your first time and you see psql: error: FATAL: database "<username>" does not exist, run createdb <username> first, then update the DATABASE_URL in api/.env to include your system username.
If you prefer randomly generated seed data rather than production-mirrored data, use yarn setup:dev instead.
5

Start all services

From the repository root, run:
yarn dev:all
This uses concurrently to start all three processes in a single terminal:
ProcessCommand internallyPort
Backend APIcd api && yarn dev3100
Public portalcd sites/public && yarn dev3000
Partners portalcd sites/partners && yarn dev3001
The public and partners apps use wait-on to wait for the API (http://127.0.0.1:3100) to be ready before starting.
You can also run each service individually from separate terminals using yarn dev inside each package directory (api/, sites/public/, sites/partners/). This is useful when you only need to work on one part of the stack, or when you want separate log streams.
6

Access the running services

Once all three processes are up:

Public portal

http://localhost:3000Browse listings and submit applications.

Partners portal

http://localhost:3001Manage listings, applications, and lotteries.

API + Swagger docs

http://localhost:3100/apiInteractive OpenAPI documentation auto-generated by the server.
7

Log in with default credentials

The seed data includes a default admin user for local development:
FieldValue
Emailadmin@example.com
Passwordabcdef
This account works on both the Public and Partners portals. Additional seeded users with different permission levels can be found in the seed-staging.ts file.

​
Running with Docker

The repository also ships a docker-compose.yml that wires together all services — PostgreSQL, the API, both frontend apps, and an nginx load balancer — on the same ports (3000, 3001, 3100). See docker.md in the repository root for full Docker setup instructions.
Do not use DB_NO_SSL="TRUE" outside of local development or CI environments. The production API connects to PostgreSQL over SSL.

Build docs developers (and LLMs) love

Get started for freeTalk to us