Skip to main content

​
Prerequisites

Before you begin, make sure the following tools are installed on your machine:

Node.js 24.x

Use nvm to manage versions. Verify with node -v.

Python 3.x

Required for database migrations via kmigrator.

Docker & Docker Compose

Used to run PostgreSQL 16 and Redis 6.2 locally.
Condo runs on the current LTS version of Node.js, which is 24.x. Check your version with node -v.

​
Setup Steps

1

Start the databases

Condo uses PostgreSQL 16 for persistent storage and Redis 6.2 for sessions, task queues, and caching. Start both with Docker Compose:
docker compose up -d postgresdb redis
Alternatively, you can install and run PostgreSQL and Redis directly on your machine.Default ports:
  • PostgreSQL: 5432
  • Redis: 6379
2

Install Node.js and Python dependencies

Install all Node.js dependencies from the repo root:
yarn install
If you see turbo: command not found in later steps, install it globally:
npm i -g turbo@^2
Install the Python packages required for database migrations:
pip install Django==5.2 psycopg2-binary==2.9.10
3

Build @open-condo packages

Condo depends on several internal packages located in the ./packages directory. These must be built before running any app:
yarn workspace @app/condo build:deps
Skipping this step will cause import errors when starting the application. Always run build:deps after cloning or pulling changes that affect packages.
4

Prepare the local environment

The prepare script automates first-time setup:
  • Copies .env.example files to .env
  • Creates the app database and runs migrations
  • Assigns a port to the app
  • Creates test users and seed data
node bin/prepare -f condo
This step is only for local development. In production pipelines, set environment variables manually and run yarn workspace @app/condo migrate directly.
5

Start the application

Start the main Condo application in development mode:
yarn workspace @app/condo dev
Open your browser and navigate to http://localhost:4006.
The default port is assigned by the prepare script. You can verify or change it via SERVER_URL and PORT in apps/condo/.env.
6

Log in to the admin panel

Navigate to http://localhost:4006/admin/signin and use the credentials generated by the prepare script:
FieldValue
EmailValue of DEFAULT_TEST_ADMIN_IDENTITY in apps/condo/.env
PasswordValue of DEFAULT_TEST_ADMIN_SECRET in apps/condo/.env
Open apps/condo/.env to find the exact values.
7

Start the worker (optional)

The worker is a separate process that handles asynchronous tasks such as sending notifications, importing data, and exporting reports.First build the app, then start the worker:
yarn workspace @app/condo build
yarn workspace @app/condo worker
The worker is required for features like notifications, imports, and exports. If these features are not needed during development, you can skip this step.

​
Production Mode

To build and run the application in production mode: 
yarn workspace @app/condo build
yarn workspace @app/condo start

​
Debugging Tips

​
Debug database queries

To log all SQL queries and transactions to the console, set the DEBUG environment variable: 
DEBUG=knex:query,knex:tx yarn workspace @app/condo dev

​
Use fake client mode for tests

The TESTS_FAKE_CLIENT_MODE flag runs the entire request/response cycle in a single process, making it easier to set breakpoints in your IDE: 
TESTS_FAKE_CLIENT_MODE=true yarn workspace @app/condo test
See the Testing guide for more details on test modes.

​
Quick Reference

# Full setup from scratch
docker compose up -d postgresdb redis
yarn install
yarn workspace @app/condo build:deps
node bin/prepare -f condo
yarn workspace @app/condo dev

Build docs developers (and LLMs) love

Get started for freeTalk to us