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

Set up the Plane development environment by running the automated setup.sh script to configure environment variables, then launch the Docker containers and Node.js frontend services to access the admin panel at localhost:3001 and the main application at localhost:3000.

Plane is an open-source project management platform structured as a monorepo combining a Django backend (apps/api) with React/Next.js frontend applications (apps/web, apps/space). The local development workflow relies on Docker containers for infrastructure services while the Node-based UI runs via pnpm for hot-reloading.

Prerequisites

Before cloning the repository, ensure your system meets the following requirements outlined in CONTRIBUTING.md:

• Docker Engine installed and running
• Node.js 20+ (the setup script enables Corepack to manage the correct pnpm version)
• Python 3.8+ for the Django backend
• At least 12 GB RAM allocated to Docker

Repository Structure

The makeplane/plane repository follows a monorepo architecture:

• apps/api/ – Django backend service handling business logic and database operations
• apps/web/ and apps/space/ – Next.js frontend applications
• packages/ – Shared libraries such as @plane/ui used across frontend services

This structure requires coordinating both Python and Node.js environments during development.

Environment Configuration

Plane uses environment variables to configure service connections. The repository provides .env.example files at the root and within apps/api/ that serve as templates for local development.

Instead of manually copying these files, run the automated configuration script:

chmod +x setup.sh
./setup.sh

This script performs three critical tasks:

1. Copies .env.example to .env for all services
2. Automatically generates a secure Django SECRET_KEY for the backend
3. Installs Node dependencies using pnpm and generates a status report

Docker Services

The docker-compose-local.yml file defines the complete development infrastructure stack. When you run the compose command, it provisions:

• PostgreSQL – Primary database for the Django backend
• Redis – Caching and session store
• RabbitMQ – Message broker for background tasks
• MinIO – S3-compatible object storage for file uploads
• API – The Django backend container
• Workers – Celery workers for asynchronous task processing
• Beat-worker – Celery beat scheduler
• Migrator – One-off container for database migrations

All services share the dev_env Docker network and mount source code volumes for hot-reloading, allowing changes to reflect immediately without rebuilding containers.

Starting the Development Stack

Backend Containers

After running setup.sh, bring up the infrastructure and backend services:

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

The -d flag runs containers in detached mode. This command starts the database, cache, message queue, and Django API server.

Frontend Services

Once the backend containers are healthy, launch the Next.js applications using the monorepo's package manager:

pnpm dev

This command starts both the main web application and the administrative interface with hot-reloading enabled. The process monitors files in apps/web/ and apps/space/ for changes.

Accessing the Application

With both backend and frontend running, access the development instance at:

• Admin Panel: http://localhost:3001/god-mode/ – Create an instance administrator here first
• Main Application: http://localhost:3000 – Log in using the credentials created in the admin panel

You must create an admin user through the god-mode interface before accessing the primary project management interface.

Running Migrations Manually

If database schema changes occur or you need to reset the state, run migrations explicitly using the migrator service:

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

This executes the Django migration command within the container environment with the correct local settings module.

Summary

• System requirements: Docker, Node 20+, Python 3.8+, and 12 GB RAM minimum
• Configuration: Run ./setup.sh to generate .env files and Django SECRET_KEY
• Backend: Use docker-compose-local.yml to start PostgreSQL, Redis, RabbitMQ, MinIO, and Django services
• Frontend: Execute pnpm dev to start Next.js apps on ports 3000 and 3001
• Access: Admin panel at localhost:3001/god-mode/, main app at localhost:3000

Frequently Asked Questions

What are the minimum system requirements for Plane development?

According to the CONTRIBUTING.md file in the repository, you need Docker Engine, Node.js version 20 or higher, Python 3.8 or higher, and at least 12 GB of RAM allocated to your Docker environment. The memory requirement is essential because the stack runs multiple containers including PostgreSQL, Redis, RabbitMQ, and MinIO simultaneously.

How do I regenerate the Django SECRET_KEY?

The setup.sh script automatically generates a new SECRET_KEY when you first run it. If you need to regenerate it manually, you can delete the existing SECRET_KEY value in apps/api/.env and run the setup script again, or generate a new secure key using Django's get_random_secret_key() function and paste it into the environment file.

Can I run Plane without Docker?

While the frontend (pnpm dev) can run directly on your host machine, the backend infrastructure requires Docker. The docker-compose-local.yml defines services like PostgreSQL, Redis, and MinIO that the Django backend depends on. Running these services natively would require manual installation and configuration of each dependency, which is not documented in the official setup workflow.

Which ports are used by the Plane development environment?

The standard development configuration exposes four main ports: 3000 for the main web application (apps/web), 3001 for the admin panel (apps/space), 5432 for PostgreSQL, and 9000 for MinIO. Ensure these ports are available on your host machine before starting the Docker compose stack.

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