Development Environment Setup

The ZəkaHouse CLI provides a streamlined way to set up and run the entire development environment with a single command.

This repository is private. You’ll need to be granted access to rashadjafarov/zeka-learnhouse on GitHub before you can clone it.

Prerequisites

Make sure you have the following installed before proceeding:

Docker (with Docker Compose v2)
Node.js 18+
Bun — used to install and run the web and collab workspaces
uv — used to manage and run the Python API

Make sure Docker has at least 4GB of RAM allocated. You can check and adjust this in Docker Desktop under Settings > Resources.

zeka-learnhouse dev runs bun install and uv sync to install project dependencies, but it does not install bun or uv themselves — install them on your host first.

Setup Steps

1. Clone the Repository and Build the CLI

git clone https://github.com/rashadjafarov/zeka-learnhouse.git
cd zeka-learnhouse/apps/cli
bun install && bun run build
cd ../..

The CLI isn’t published to npm — this builds it from the repository. Optionally run npm link from apps/cli once to put zeka-learnhouse on your PATH; the rest of this page assumes you have.

2. Start Development

From the repository root:

zeka-learnhouse dev
# or, without linking:
bun apps/cli/dist/bin/learnhouse.js dev

That single command handles everything:

Starts backing services — PostgreSQL and Redis are launched via Docker Compose.
Installs dependencies — Python dependencies are installed via uv and JavaScript dependencies via bun, all automatically.
Starts the API — The FastAPI backend starts on port 1338 with hot reload.
Starts the frontend — The Next.js development server starts with --turbopack and hot reload.
Starts the collaboration server — The Hocuspocus collaboration server starts via tsx watch.

All services are coordinated automatically so you do not need to manage them individually.

Accessing the Application

Once zeka-learnhouse dev is running, you can access:

Service	URL
Frontend	http://localhost:3000
API	http://localhost:1338
API Documentation (Swagger)	http://localhost:1338/docs

The Swagger UI at /docs is only available in development mode. Production instances do not expose the interactive API documentation.

Stopping the Environment

Press Ctrl+C in the terminal where zeka-learnhouse dev is running to stop all services.

Troubleshooting

Port conflicts — Make sure ports 3000 (web), 1338 (API), 4000 (collab), 5432 (Postgres), and 6379 (Redis) are not in use by other applications.
Docker not running — Ensure the Docker daemon is started before running zeka-learnhouse dev.
Dependency issues — The CLI installs all dependencies automatically. If you encounter issues, try deleting node_modules and .venv directories and re-running zeka-learnhouse dev.

PreviousContributing to ZəkaHouse NextContribution Guidelines