How to Set Up a Local Development Environment for Plane (makeplane/plane)

Plane requires Docker Engine, Node 20+, Python 3.8+, and at least 12 GB RAM to run a Django backend and React frontend locally using docker-compose-local.yml and pnpm dev.

Plane is a modern, open-source project management platform structured as a monorepo that combines a Django REST API with React/Next.js frontend applications. Setting up a local development environment involves orchestrating PostgreSQL, Redis, RabbitMQ, and MinIO services via Docker while running the Node-based UI with hot-reloading for rapid iteration.

Prerequisites and System Requirements

Before cloning the repository, ensure your workstation meets the following specifications defined in CONTRIBUTING.md:

• Docker Engine (for containerized services)
• Node.js 20+ (for frontend tooling)
• Python 3.8+ (for backend scripts)
• 12 GB RAM minimum (to support concurrent containers)

You will also need pnpm as the package manager, which the setup script automatically enables via Corepack.

Repository Structure Overview

The makeplane/plane repository organizes code as a monorepo with distinct application layers:

• apps/api/ – Django backend with REST APIs and background workers
• apps/web/ – Main Next.js application (port 3000)
• apps/space/ – Additional UI service
• packages/ – Shared internal packages (e.g., @plane/ui)

This separation allows the backend and frontend to run independently while sharing environment configuration through .env files.

Environment Configuration

Plane ships with .env.example templates for every service. Instead of manually copying these files, run the automated setup script:

chmod +x setup.sh
./setup.sh

According to the source code in setup.sh, this script performs three critical tasks:

1. Copies all .env.example files to .env across the monorepo
2. Generates a cryptographically secure Django SECRET_KEY for apps/api/.env
3. Installs Node dependencies using pnpm install

Manual alternative: If you prefer manual configuration, copy apps/api/.env.example to apps/api/.env and generate a SECRET_KEY using Django's get_random_secret_key() function.

Starting the Development Stack

The local development workflow splits infrastructure (data stores) from application code (API and UI).

Backend Services (Docker)

The docker-compose-local.yml file defines the complete data layer and backend containers:

• Postgres – Primary database
• Redis – Caching and session storage
• RabbitMQ – Message broker for Celery workers
• MinIO – S3-compatible object storage
• API – Django application server
• Workers – Celery worker processes
• Beat-worker – Celery scheduler
• Migrator – One-shot migration container

Start these services with:

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

The -d flag runs containers in detached mode. All services attach to the dev_env network and mount source code for hot-reloading.

Frontend Services (Node.js)

With backend containers running, launch the development UI servers:

pnpm dev

This command starts:

• Web app on http://localhost:3000 – The main Plane interface
• Admin app on http://localhost:3001 – The God-mode administrative panel

The monorepo configuration automatically handles port allocation and concurrent builds across workspaces.

Initial Access and Setup

Once both Docker and Node services are running, complete the initial configuration:

1. Navigate to http://localhost:3001/god-mode/ to access the admin panel
2. Create an instance administrator account
3. Log in at http://localhost:3000 using the same credentials

The docker-compose-local.yml ensures that API requests from the frontend (port 3000) reach the Django backend through the internal Docker network.

Manual Database Migrations

If you need to run migrations manually rather than relying on the migrator container, execute:

docker compose -f docker-compose-local.yml run --rm migrator \
    ./bin/docker-entrypoint-migrator.sh --settings=plane.settings.local

This command spins up a temporary container using the migrator service definition, applies pending migrations, and removes the container upon completion.

Summary

• Plane is a monorepo requiring Docker Engine, Node 20+, Python 3.8+, and 12 GB RAM for local development
• Environment setup is automated via setup.sh, which copies .env files and generates Django SECRET_KEY
• Backend services (Postgres, Redis, RabbitMQ, MinIO) run via docker-compose-local.yml with hot-reloading enabled
• Frontend services start with pnpm dev, exposing the main app on port 3000 and admin panel on port 3001
• Initial access requires visiting localhost:3001/god-mode/ to create an admin before logging into the main interface

Frequently Asked Questions

What are the minimum hardware requirements for Plane local development?

Plane requires at least 12 GB RAM to run the full stack locally, including PostgreSQL, Redis, RabbitMQ, MinIO, and the Django/Python backend alongside Node.js frontend builds. This specification is documented in CONTRIBUTING.md and ensures sufficient memory for the Celery worker processes and Next.js hot-reloading.

How does the setup.sh script configure the environment?

The setup.sh script automates three critical setup tasks: it recursively copies all .env.example files to .env across the monorepo, generates a cryptographically secure Django SECRET_KEY for the backend, and initializes the Node.js dependencies using pnpm. This ensures all services have valid configuration before the first Docker build.

Which ports does Plane use in local development?

Plane exposes port 3000 for the main web application and port 3001 for the God-mode administrative panel. The backend API runs internally within the Docker network and is not exposed on a host port by default, as the Next.js frontend communicates with it through the dev_env Docker network bridge.

How do I run database migrations manually in Plane?

To run migrations manually, use the migrator service defined in docker-compose-local.yml with the command: docker compose -f docker-compose-local.yml run --rm migrator ./bin/docker-entrypoint-migrator.sh --settings=plane.settings.local. This executes Django's migrate command inside a container that shares the database volume with your development stack.

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