# How to Set Up Plane for Local Development Using Docker-Compose and the PNPM Monorepo

> Learn to set up Plane for local development with Docker Compose and PNPM monorepo. Easily launch the backend and frontend servers in minutes for a smooth workflow.

- Repository: [Plane/plane](https://github.com/makeplane/plane)
- Tags: how-to-guide
- Published: 2026-06-22

---

**Clone the makeplane/plane repository, run `docker compose -f docker-compose-local.yml up -d` to start the backend stack, then execute `pnpm install` and `pnpm dev` to launch the Turbo-powered development servers on ports 3000, 3001, and 3002.**

Plane is an open-source project management platform structured as a **PNPM monorepo** using Turbo for task orchestration. The repository contains a [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) file that containerizes PostgreSQL, Redis, Celery workers, and the Django API, while the Node.js frontend packages run locally via PNPM workspaces. This configuration enables full-stack local development with hot reloading and real-time collaboration features.

## Prerequisites

Before starting, ensure your system meets these requirements:

- **Docker Engine** 24.0+ and **Docker Compose** v2 (the `docker compose` CLI plugin)
- **Node.js** 18.x LTS (required by PNPM and the JavaScript packages)
- **PNPM** 8.x (handles the monorepo workspace and Turbo tasks)
- **Git** for cloning the repository

The repository includes a [`setup.sh`](https://github.com/makeplane/plane/blob/main/setup.sh) script that verifies these dependencies and suggests installations when tools are missing.

## Step-by-Step Setup

Follow these commands from the repository root (the directory containing [`package.json`](https://github.com/makeplane/plane/blob/main/package.json), [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml), and [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml)).

### 1. Clone the Repository

```bash
git clone https://github.com/makeplane/plane.git
cd plane

```

### 2. Configure Environment Variables

Copy the example environment file and customize if needed:

```bash
cp .env.example .env

```

The default values in `.env` work out-of-the-box for local development, but you can modify ports or database passwords before starting the containers.

### 3. Start the Docker Services

Launch the backend infrastructure using the local development compose file:

```bash
docker compose -f docker-compose-local.yml up -d

```

This command spins up **PostgreSQL**, **Redis**, **RabbitMQ**, the Django API, Celery workers, and the "Plane AIO" container. Services are prefixed with `plane_` (e.g., `plane_db`, `plane_api`).

### 4. Install PNPM Dependencies

Resolve all inter-package dependencies across the monorepo:

```bash
pnpm install

```

This creates a shared `node_modules/.pnpm` store and links workspace packages according to [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml).

### 5. Launch Development Servers

Start all frontend applications in watch mode with a single command:

```bash
pnpm dev

```

Under the hood, this executes `pnpm turbo run dev --parallel`, which concurrently starts:

- **Web UI** at `http://localhost:3000` (the main Plane interface configured in [`apps/web/vite.config.ts`](https://github.com/makeplane/plane/blob/main/apps/web/vite.config.ts))
- **Admin UI** at `http://localhost:3001` (administration console configured in [`apps/admin/vite.config.ts`](https://github.com/makeplane/plane/blob/main/apps/admin/vite.config.ts))
- **Live Collaboration** at `http://localhost:3002` (real-time service configured in [`apps/live/vite.config.ts`](https://github.com/makeplane/plane/blob/main/apps/live/vite.config.ts))

All frontends proxy API requests to the Django service running in Docker at `http://localhost:8000`. The first run will automatically trigger database migrations.

## Working with Individual Packages

Because the repository uses a monorepo structure, you can target specific applications using Turbo filters.

To run only the web frontend:

```bash
pnpm turbo run dev --filter=@plane/web

```

To rebuild a specific Docker container without restarting the entire stack:

```bash
docker compose -f docker-compose-local.yml up -d --build plane_api

```

## Key Configuration Files

Understanding these files helps when customizing your local environment:

- **[`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml)** – Defines the multi-container local stack including database, cache, and API services
- **[`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml)** – Declares workspace packages in `apps/*` and `packages/*` directories
- **[`setup.sh`](https://github.com/makeplane/plane/blob/main/setup.sh)** – Helper script for dependency verification and stack management
- **[`apps/web/vite.config.ts`](https://github.com/makeplane/plane/blob/main/apps/web/vite.config.ts)** – Vite configuration for the main UI (port 3000)
- **[`apps/admin/vite.config.ts`](https://github.com/makeplane/plane/blob/main/apps/admin/vite.config.ts)** – Configuration for the admin console (port 3001)
- **[`apps/live/vite.config.ts`](https://github.com/makeplane/plane/blob/main/apps/live/vite.config.ts)** – Configuration for the Live Collaboration service (port 3002)
- **`apps/api/Dockerfile`** – Build instructions for the Django API container

## Troubleshooting Common Issues

**Port conflicts** occur when services like 3000, 3001, 3002, or 8000 are already bound. Modify `PLANE_WEB_PORT`, `PLANE_ADMIN_PORT`, `PLANE_LIVE_PORT`, and `PLANE_API_PORT` in your `.env` file, then restart Docker Compose.

**Node version errors** happen when `pnpm install` reports engine mismatches. Ensure Node.js 18.x LTS is active using `nvm` or your version manager before installing dependencies.

**Missing database tables** on first access require manual migration. Execute `docker compose -f docker-compose-local.yml exec plane_api python manage.py migrate` to apply Django schema changes to the PostgreSQL container.

**Stale cached builds** after code changes require a dev server restart. Stop the process with `Ctrl-C` and rerun `pnpm dev` to trigger Turbo's incremental rebuild of affected packages.

## Summary

- **Clone** the repository and `cd` into the `plane` directory
- **Copy** `.env.example` to `.env` and adjust variables if needed
- **Start** backend services with `docker compose -f docker-compose-local.yml up -d`
- **Install** dependencies via `pnpm install`
- **Launch** the development stack using `pnpm dev` for parallel frontend execution

You now have a functional local Plane instance with hot-reloading frontends and containerized backend services, ready for development and debugging.

## Frequently Asked Questions

### What is the difference between docker-compose-local.yml and other compose files in the repository?

The [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) file in the repository root is specifically optimized for development environments, mounting source directories and enabling debug mode for the Django API. Other compose files in the repository typically target production deployments or specific cloud configurations without volume mounts or development dependencies.

### How do I run only the web application without starting all frontend services?

Use Turbo's filter flag to target specific workspace packages. Run `pnpm turbo run dev --filter=@plane/web` to start only the main web interface on port 3000, or substitute `@plane/admin` or `@plane/live` for the other applications. This conserves system resources when you don't need the full stack.

### Why do I see database errors when first accessing localhost:3000?

The Django API container may require manual migration execution on first setup. Run `docker compose -f docker-compose-local.yml exec plane_api python manage.py migrate` to apply database schema changes. Subsequent restarts persist data through the Docker volume, so you only need to run migrations after cloning or pulling significant schema changes.

### Can I use npm or yarn instead of PNPM for local development?

No, the Plane monorepo is configured specifically for **PNPM** with a [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml) file and [`pnpm-lock.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-lock.yaml) lockfile. Using npm or yarn will result in dependency resolution errors and missing workspace links. Ensure you have PNPM 8.x installed globally before running `pnpm install`.