Development Environment Setup

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

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

Setup Steps

1. Clone the Repository and Start Development

git clone https://github.com/learnhouse/learnhouse && cd learnhouse && npx learnhouse 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 npx learnhouse dev is running, you can access:

Stopping the Environment

Press Ctrl+C in the terminal where npx 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 npx learnhouse dev.
• Dependency issues — The CLI installs all dependencies automatically. If you encounter issues, try deleting node_modules and .venv directories and re-running npx learnhouse dev.