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

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 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 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, pnpm-workspace.yaml, and docker-compose-local.yml).

1. Clone the Repository

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

2. Configure Environment Variables

Copy the example environment file and customize if needed:

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:

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:

pnpm install

This creates a shared node_modules/.pnpm store and links workspace packages according to pnpm-workspace.yaml.

5. Launch Development Servers

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

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)
• Admin UI at http://localhost:3001 (administration console configured in apps/admin/vite.config.ts)
• Live Collaboration at http://localhost:3002 (real-time service configured in 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:

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

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

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 – Defines the multi-container local stack including database, cache, and API services
• pnpm-workspace.yaml – Declares workspace packages in apps/* and packages/* directories
• setup.sh – Helper script for dependency verification and stack management
• apps/web/vite.config.ts – Vite configuration for the main UI (port 3000)
• apps/admin/vite.config.ts – Configuration for the admin console (port 3001)
• 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 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 file and 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}