Skip to main content
This guide walks you through starting Condo locally for the first time. By the end you will have a running instance with an admin UI accessible in your browser.

​
Prerequisites

Before you begin, make sure you have the following installed:

Node.js 24.x

The current LTS version. Use nvm to manage versions. Check with node -v.

Python 3.x

Required for database migrations via the Django-based kmigrator tool.

Docker & Docker Compose

Used to run PostgreSQL 16 and Redis 6.2 locally. Optional if you run databases directly on the host.
Condo uses Yarn 3.2.2+ (Berry) as its package manager. If you don’t have it, follow the Yarn installation guide.

​
Setup steps

1

Start the databases

Condo requires PostgreSQL (port 5432) and Redis (port 6379). Start both with Docker Compose:
docker compose up -d postgresdb redis
Alternatively, bring up PostgreSQL and Redis directly on your host machine if you prefer not to use Docker.
2

Install Python packages

The database migration tool (kmigrator) is Django-based and requires two Python packages:
pip install Django==5.2 psycopg2-binary==2.9.10
3

Install Node.js dependencies

Install all Node.js dependencies across the monorepo:
yarn install
If you see a turbo: command not found error in later steps, install Turbo globally:
npm i -g turbo@^2
4

Build @open-condo packages

Condo depends on several internal packages in the packages/ directory. Build them before launching the app:
yarn workspace @app/condo build:deps
This command uses Turbo to build all upstream package dependencies of @app/condo in the correct order.
5

Prepare the local environment

The prepare script handles first-time setup automatically:
  • Copies .env.example files to .env
  • Creates the application database and runs migrations
  • Assigns a port to the app
  • Creates test users and other seed data needed for first launch
node bin/prepare -f condo
This step is for local development only. For production deployments, set environment variables manually and run yarn workspace @app/condo migrate directly.
After the script completes, check apps/condo/.env for the assigned PORT, SERVER_URL, DEFAULT_TEST_ADMIN_IDENTITY, and DEFAULT_TEST_ADMIN_SECRET values.
6

Start the app in development mode

Launch the main Condo application with hot-reload enabled:
yarn workspace @app/condo dev
The app will be available at http://localhost:4006. The exact port depends on what was assigned during the prepare step — verify with SERVER_URL in apps/condo/.env.
7

Start the worker

The worker is a separate process that handles asynchronous tasks such as sending notifications, imports, and exports. It requires the app to be built first:
yarn workspace @app/condo build
The worker must be running for notifications, data imports, and exports to function. You can run both the dev server and the worker simultaneously in separate terminal sessions.

​
Accessing the admin UI

Once the app is running, open your browser and navigate to: 
http://localhost:4006/admin/signin
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

​
Quick reference

The full setup sequence in one block: 
# 1. Start databases
docker compose up -d postgresdb redis

# 2. Install Python migration dependencies
pip install Django psycopg2-binary

# 3. Install Node.js dependencies
yarn install

# 4. Build internal packages
yarn workspace @app/condo build:deps

# 5. Prepare local environment
node bin/prepare -f condo

# 6. Start the app
yarn workspace @app/condo dev

# 7. Start the worker (separate terminal)
yarn workspace @app/condo build && yarn workspace @app/condo worker

​
Production mode

To run the app in production mode instead of dev: 
yarn workspace @app/condo build
yarn workspace @app/condo start

​
Next steps

Architecture

Understand the monorepo structure, tech stack, and how apps and packages relate.

Project structure

Learn about domain-driven design inside apps/condo/domains/.

Testing

Run schema tests and unit tests with Jest.

Deploy with Docker

Run Condo in production using the included Docker Compose configuration.

Build docs developers (and LLMs) love

Get started for freeTalk to us