How to Set Up Local Development for Plane Using Docker and pnpm

To set up local development for Plane using Docker and pnpm, clone the makeplane/plane repository, copy .env.example to .env and configure the required variables, start the backend services with docker compose -f docker-compose-local.yml up -d, install JavaScript dependencies with pnpm install, execute initial database migrations via the migrator container, and launch the frontend development servers with pnpm dev.

Plane is an open-source, full-stack project management application that combines a Django REST API with a React/Next.js-style frontend. When you set up local development for Plane using Docker and pnpm, you orchestrate the backend infrastructure—PostgreSQL, Redis, RabbitMQ, and MinIO—inside Docker containers while using pnpm workspaces to manage the monorepo's JavaScript packages.

Architecture Overview

Plane's local development environment consists of eight containerized services defined in docker-compose-local.yml and a pnpm-managed JavaScript workspace. All services attach to a single Docker network named dev_env and share persistent volumes for data durability.

Service	Image	Role	Source Location
plane-db	postgres:15.7-alpine	Primary relational database for issues, cycles, and user data	docker-compose-local.yml lines 51-65
plane-redis	valkey/valkey:7.2.11-alpine	Cache layer and real-time pub/sub for live updates	docker-compose-local.yml lines 1-10
plane-mq	rabbitmq:3.13.6-management-alpine	Message broker for Celery background jobs	docker-compose-local.yml lines 12-25
plane-minio	minio/minio	Object storage for file uploads and attachments	docker-compose-local.yml lines 26-49
api	Built from apps/api/Dockerfile.dev	Django REST API backend	docker-compose-local.yml lines 66-86
worker	Same image as api	Celery worker processing async tasks	docker-compose-local.yml lines 87-104
beat-worker	Same image as api	Celery beat scheduler for periodic tasks	docker-compose-local.yml lines 106-124
migrator	Same image as api	One-off container for Django migrations	docker-compose-local.yml lines 125-141

The pnpm workspace—defined in pnpm-workspace.yaml—includes apps/web (the main UI), apps/live (real-time updates), and shared packages in packages/*. Running pnpm dev starts Vite development servers that proxy API requests to the Dockerized Django backend at http://localhost:8000.

Prerequisites

Before starting, ensure your workstation meets the following requirements:

• Docker Desktop or Docker Engine with Docker Compose ≥ 2.0
• Node.js ≥ 20
• pnpm (enable via corepack enable && corepack prepare pnpm@latest --activate or install globally with npm i -g pnpm)

Step-by-Step Setup Guide

1. Clone the Repository

Clone the Plane repository and switch to the preview branch, which contains the latest development configuration:

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

2. Configure Environment Variables

Plane requires environment variables for both Docker services and the Django application. Create your local configuration from the provided template:

cp .env.example .env

Edit .env to set the following required values (other variables have sensible defaults):

• RABBITMQ_USER, RABBITMQ_PASSWORD, RABBITMQ_VHOST
• AWS_S3_BUCKET_NAME, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY

The docker-compose-local.yml references this file via env_file: .env, injecting these values into the appropriate containers.

3. Start the Docker Services

Launch the backend infrastructure in detached mode:

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

This command creates the dev_env network and mounts persistent volumes (redisdata, pgdata, uploads, rabbitmq_data). Verify all containers are healthy with docker compose ps.

4. Install pnpm Dependencies

Install the JavaScript workspace dependencies:

pnpm install

pnpm will resolve dependencies across all workspace packages defined in pnpm-workspace.yaml and generate a pnpm-lock.yaml lockfile.

5. Run Database Migrations

For first-time setup, execute Django migrations using the dedicated migrator container:

docker compose -f docker-compose-local.yml run --rm migrator

This container runs manage.py migrate against the plane.settings.local configuration, initializing the PostgreSQL schema.

6. Launch the Development Servers

Start the frontend development environment:

pnpm dev

This command launches:

• Plane Web UI at http://localhost:3000
• Admin UI at http://localhost:3001
• Live reload server (apps/live) proxying API requests

Accessing Your Local Instance

Once running, access the following endpoints in your browser:

URL	Service
http://localhost:3000	Main Plane application UI
http://localhost:3001	Instance administration panel
http://localhost:8000/api/docs/	Django REST API Swagger documentation
http://localhost:9000	MinIO object storage console
http://localhost:5672	RabbitMQ management interface (if port exposed)

Key Configuration Files

Understanding these files helps troubleshoot and customize your setup:

• docker-compose-local.yml — Defines the complete backend service stack, network configuration (dev_env), and volume mounts for local development.
• .env.example — Template for environment variables required by Docker services and Django settings.
• pnpm-workspace.yaml — Declares the monorepo structure, including apps/web, apps/live, and shared packages.
• apps/api/Dockerfile.dev — Multi-stage build definition used for the api, worker, beat-worker, and migrator containers.
• apps/web/vite.config.ts — Vite development server configuration that pnpm dev executes.

Summary

• Plane uses Docker Compose to orchestrate PostgreSQL, Redis, RabbitMQ, MinIO, and Django services via docker-compose-local.yml.
• The pnpm workspace manages frontend dependencies; use pnpm install to prepare the monorepo and pnpm dev to start development servers.
• Environment configuration requires copying .env.example to .env and setting RabbitMQ and MinIO credentials before starting containers.
• Database migrations run via a one-off migrator container: docker compose run --rm migrator.
• The complete stack exposes the UI on port 3000, admin panel on 3001, and API on 8000.

Frequently Asked Questions

What is the purpose of the migrator container in Plane's Docker setup?

The migrator container is a one-off service defined in docker-compose-local.yml that executes Django's manage.py migrate command against the PostgreSQL database. Unlike the persistent api container, the migrator runs to completion and exits, ensuring schema updates apply before the application starts serving requests.

Can I use npm or yarn instead of pnpm for Plane local development?

No. Plane is configured as a pnpm monorepo with workspace definitions in pnpm-workspace.yaml and relies on pnpm-specific features for dependency hoisting and workspace linking. The root package.json scripts specifically expect the pnpm CLI to resolve workspace packages correctly.

How do I reset the database during local development?

Stop the Docker services with docker compose -f docker-compose-local.yml down, then remove the pgdata volume using docker volume rm plane_pgdata (or docker volume prune to remove all unused volumes). Restart the stack with docker compose up -d and rerun the migrator container to recreate the schema.

Why does Plane use Valkey instead of Redis in the Docker compose file?

Plane uses valkey/valkey:7.2.11-alpine as a drop-in replacement for Redis, providing compatible caching and pub/sub functionality for real-time updates. The plane-redis service defined in docker-compose-local.yml maintains the same interface as Redis, ensuring compatibility with Django's cache backend and Celery message transport.

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