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

> Easily set up local development for Plane with Docker and pnpm. Follow our step by step guide to clone the repo, configure, and run Plane locally for seamless development.

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

---

**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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) lines 12-25 |
| `plane-minio` | `minio/minio` | Object storage for file uploads and attachments | [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) lines 26-49 |
| `api` | Built from `apps/api/Dockerfile.dev` | Django REST API backend | [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) lines 66-86 |
| `worker` | Same image as `api` | Celery worker processing async tasks | [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) lines 87-104 |
| `beat-worker` | Same image as `api` | Celery beat scheduler for periodic tasks | [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) lines 106-124 |
| `migrator` | Same image as `api` | One-off container for Django migrations | [`docker-compose-local.yml`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) lines 125-141 |

The pnpm workspace—defined in [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/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:

```bash
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:

```bash
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`](https://github.com/makeplane/plane/blob/main/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:

```bash
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:

```bash
pnpm install

```

pnpm will resolve dependencies across all workspace packages defined in [`pnpm-workspace.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml) and generate a [`pnpm-lock.yaml`](https://github.com/makeplane/plane/blob/main/pnpm-lock.yaml) lockfile.

### 5. Run Database Migrations

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

```bash
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:

```bash
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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/pnpm-workspace.yaml) and relies on pnpm-specific features for dependency hoisting and workspace linking. The root [`package.json`](https://github.com/makeplane/plane/blob/main/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`](https://github.com/makeplane/plane/blob/main/docker-compose-local.yml) maintains the same interface as Redis, ensuring compatibility with Django's cache backend and Celery message transport.