# Plane Project Management

> Open source project tracking tool like Jira/Linear.

- Category: Productivity & Collaboration
- Difficulty: intermediate
- Components: plane-web, plane-api, plane-worker, postgresql, redis, minio
- Tags: plane, project-management, jira-alternative, linear, issues
- Source: https://docker.recipes/productivity/plane-project

## Overview

Plane is a modern, open-source project management platform that serves as a powerful alternative to Jira and Linear. Born from the need for developer-friendly issue tracking without vendor lock-in, Plane provides agile project management with cycles, modules, views, and real-time collaboration features. The platform emphasizes speed and user experience while maintaining the depth required for complex project workflows.

This stack combines Plane's three-tier architecture with robust data infrastructure. The plane-web frontend delivers a responsive React-based interface, while plane-api handles business logic and REST endpoints. The plane-worker processes background tasks through Celery queues. PostgreSQL stores structured project data with full ACID compliance for data integrity, Redis provides sub-millisecond caching and task queue management, and MinIO offers S3-compatible object storage for file attachments and assets.

Development teams, startups, and organizations seeking project management control without SaaS limitations will find this configuration valuable. Unlike hosted solutions, this self-hosted approach eliminates per-user costs, provides complete data ownership, and allows custom integrations. The combination is particularly suited for teams already comfortable with containerized infrastructure who need enterprise-grade project tracking with the flexibility of open-source tooling.

## Features

- Agile project management with sprints (cycles), feature groupings (modules), and custom issue views
- Real-time collaborative editing and commenting powered by Redis pub/sub messaging
- Advanced PostgreSQL-backed analytics with custom fields, filters, and project insights
- S3-compatible file attachment system using MinIO for images, documents, and project assets
- Celery-based background processing for notifications, imports, and scheduled tasks
- Multi-workspace support with team permissions and project-level access controls
- API-first architecture enabling custom integrations and automation workflows
- GitHub, GitLab, and other VCS integrations for linking commits to issues

## Use cases

- Software development teams transitioning from Jira to avoid licensing costs and vendor lock-in
- Startups requiring enterprise project management features without per-seat pricing constraints
- Organizations with data sovereignty requirements needing on-premises issue tracking
- Development agencies managing multiple client projects with workspace isolation
- Open source projects needing professional project management tools with community hosting
- Companies requiring custom project workflows and integrations not available in SaaS solutions
- Teams in regulated industries needing complete audit trails and data control for compliance

## Prerequisites

- Docker Engine 20.10+ and Docker Compose V2 for container orchestration support
- Minimum 4GB RAM (2GB for PostgreSQL/MinIO, 1GB for Plane services, 512MB for Redis)
- Available ports 3000 (web interface), 8000 (API), and 9001 (MinIO console)
- Basic understanding of environment variable configuration for secrets management
- Familiarity with PostgreSQL concepts for database maintenance and backups
- Knowledge of object storage concepts for file upload and MinIO bucket management

## docker-compose.yml

```yaml
services:
  plane-web:
    image: makeplane/plane-frontend:latest
    ports:
      - "3000:3000"
    environment:
      NEXT_PUBLIC_API_BASE_URL: http://localhost:8000
    depends_on:
      - plane-api
    networks:
      - plane-net
    restart: unless-stopped

  plane-api:
    image: makeplane/plane-backend:latest
    ports:
      - "8000:8000"
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379
      SECRET_KEY: ${SECRET_KEY}
      AWS_ACCESS_KEY_ID: ${MINIO_ACCESS_KEY}
      AWS_SECRET_ACCESS_KEY: ${MINIO_SECRET_KEY}
      AWS_S3_BUCKET_NAME: uploads
      AWS_S3_ENDPOINT_URL: http://minio:9000
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_started
    networks:
      - plane-net
    restart: unless-stopped

  plane-worker:
    image: makeplane/plane-backend:latest
    command: celery -A plane worker -l info
    environment:
      DATABASE_URL: postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}
      REDIS_URL: redis://redis:6379
      SECRET_KEY: ${SECRET_KEY}
    depends_on:
      - plane-api
    networks:
      - plane-net
    restart: unless-stopped

  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - plane-net
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data
    networks:
      - plane-net
    restart: unless-stopped

  minio:
    image: minio/minio:latest
    ports:
      - "9001:9001"
    environment:
      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY}
      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY}
    volumes:
      - minio_data:/data
    command: server /data --console-address ":9001"
    networks:
      - plane-net
    restart: unless-stopped

volumes:
  postgres_data:
  redis_data:
  minio_data:

networks:
  plane-net:
    driver: bridge
```

## .env

```bash
# PostgreSQL
POSTGRES_USER=plane
POSTGRES_PASSWORD=secure_postgres_password
POSTGRES_DB=plane

# Plane
SECRET_KEY=$(openssl rand -hex 32)

# MinIO
MINIO_ACCESS_KEY=plane
MINIO_SECRET_KEY=secure_minio_password
```

## Usage notes

- Plane at http://localhost:3000
- API at http://localhost:8000
- Modern issue tracking UI
- Cycles, modules, and views

## Troubleshooting

- plane-api fails to connect to PostgreSQL: Ensure PostgreSQL health check passes before API startup and verify DATABASE_URL environment variable format
- File uploads return 403 errors: Check MinIO bucket creation and verify AWS_S3_BUCKET_NAME exists with proper access policies configured
- Background tasks not processing: Verify plane-worker container is running and Redis connection is established for Celery task queue
- Frontend shows API connection errors: Confirm NEXT_PUBLIC_API_BASE_URL matches your domain and plane-api is accessible on port 8000
- PostgreSQL connection pool exhausted: Increase max_connections in PostgreSQL config or implement connection pooling like PgBouncer for high-traffic instances
- MinIO console inaccessible: Verify MINIO_ROOT_USER and MINIO_ROOT_PASSWORD are set correctly and console is bound to port 9001

