# Plane Issue Tracker

> Open-source project tracking tool, JIRA alternative.

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

## Overview

Plane is an open-source project management and issue tracking platform designed as a modern alternative to JIRA. Built with a focus on simplicity and speed, Plane offers comprehensive project tracking capabilities including issue management, sprint planning, roadmap visualization, and team collaboration features. The platform emphasizes user experience with a clean, intuitive interface while providing powerful features like custom workflows, multiple project views, and advanced filtering options.

This Docker deployment creates a complete Plane installation using a multi-service architecture. The stack includes a Next.js frontend (web), Django REST API backend (api), Celery worker processes for background tasks (worker), Celery beat scheduler for periodic tasks (beat), PostgreSQL for primary data storage (db), Redis for caching and task queues (redis), and MinIO for S3-compatible file storage (minio). The backend services share the same Docker image but run different processes to handle web requests, background processing, and scheduled tasks separately.

This configuration is ideal for teams seeking a self-hosted project management solution with enterprise-grade features but without vendor lock-in. Organizations transitioning from JIRA, development teams requiring integrated issue tracking with Git workflows, and companies needing customizable project management tools will benefit from this deployment. The separation of concerns across multiple services provides scalability while maintaining data sovereignty and customization flexibility.

## Features

- Comprehensive issue tracking with custom fields, labels, and workflow states
- Sprint planning and cycle management with burndown charts and velocity tracking
- Multiple project views including Kanban boards, lists, and calendar views
- Advanced filtering and search capabilities across issues and projects
- File attachment support with S3-compatible storage via MinIO integration
- Real-time collaboration features powered by Redis pub/sub messaging
- Background task processing for notifications, imports, and data synchronization
- GitHub and GitLab integration for automatic issue creation and status updates

## Use cases

- Software development teams migrating from JIRA to an open-source alternative
- Startups and scale-ups needing project management without per-user licensing costs
- Organizations requiring self-hosted solutions for data privacy and compliance
- Development teams integrating issue tracking with existing Git workflows
- Companies needing customizable project management workflows and reporting
- Remote teams requiring real-time collaboration on project planning and execution
- Agencies managing multiple client projects with separate workspaces and permissions

## Prerequisites

- Docker and Docker Compose installed with minimum 4GB total RAM available
- Port 3000 available for web interface and port 9000 for MinIO console access
- Environment variables configured including SECRET_KEY, database password, and MinIO credentials
- SMTP server details for email notifications (optional but recommended)
- Basic understanding of Django/Python applications for configuration and troubleshooting
- Familiarity with PostgreSQL for database maintenance and backup procedures

## docker-compose.yml

```yaml
services:
  web:
    image: makeplane/plane-frontend:latest
    container_name: plane-web
    environment:
      - NEXT_PUBLIC_API_BASE_URL=${API_URL}
    ports:
      - "3000:3000"
    depends_on:
      - api
    networks:
      - plane-network
    restart: unless-stopped

  api:
    image: makeplane/plane-backend:latest
    container_name: plane-api
    environment:
      - DEBUG=0
      - DJANGO_SETTINGS_MODULE=plane.settings.production
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgres://plane:${DB_PASSWORD}@db:5432/plane
      - REDIS_URL=redis://redis:6379/
      - EMAIL_HOST=${EMAIL_HOST}
      - EMAIL_HOST_USER=${EMAIL_HOST_USER}
      - EMAIL_HOST_PASSWORD=${EMAIL_HOST_PASSWORD}
      - AWS_ACCESS_KEY_ID=${MINIO_ACCESS_KEY}
      - AWS_SECRET_ACCESS_KEY=${MINIO_SECRET_KEY}
      - AWS_S3_ENDPOINT_URL=${MINIO_URL}
      - AWS_S3_BUCKET_NAME=plane
      - FILE_SIZE_LIMIT=5242880
      - WEB_URL=${WEB_URL}
    depends_on:
      - db
      - redis
    networks:
      - plane-network
    restart: unless-stopped

  worker:
    image: makeplane/plane-backend:latest
    container_name: plane-worker
    command: ./bin/worker
    environment:
      - DEBUG=0
      - DJANGO_SETTINGS_MODULE=plane.settings.production
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgres://plane:${DB_PASSWORD}@db:5432/plane
      - REDIS_URL=redis://redis:6379/
    depends_on:
      - api
      - redis
    networks:
      - plane-network
    restart: unless-stopped

  beat:
    image: makeplane/plane-backend:latest
    container_name: plane-beat
    command: ./bin/beat
    environment:
      - DEBUG=0
      - DJANGO_SETTINGS_MODULE=plane.settings.production
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_URL=postgres://plane:${DB_PASSWORD}@db:5432/plane
      - REDIS_URL=redis://redis:6379/
    depends_on:
      - api
      - redis
    networks:
      - plane-network
    restart: unless-stopped

  db:
    image: postgres:15-alpine
    container_name: plane-db
    environment:
      - POSTGRES_USER=plane
      - POSTGRES_PASSWORD=${DB_PASSWORD}
      - POSTGRES_DB=plane
    volumes:
      - postgres-data:/var/lib/postgresql/data
    networks:
      - plane-network
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: plane-redis
    volumes:
      - redis-data:/data
    networks:
      - plane-network
    restart: unless-stopped

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

volumes:
  postgres-data:
  redis-data:
  minio-data:

networks:
  plane-network:
    driver: bridge
```

## .env

```bash
# Plane
WEB_URL=http://localhost:3000
API_URL=http://localhost:8000

# Generate with: openssl rand -hex 32
SECRET_KEY=your_secret_key_here
DB_PASSWORD=secure_plane_password

# MinIO
MINIO_ACCESS_KEY=plane_minio
MINIO_SECRET_KEY=secure_minio_password
MINIO_URL=http://minio:9000

# Email (optional)
EMAIL_HOST=smtp.example.com
EMAIL_HOST_USER=plane@example.com
EMAIL_HOST_PASSWORD=email_password
```

## Usage notes

- Web UI at http://localhost:3000
- Create plane bucket in MinIO first
- JIRA-like issue tracking
- Supports cycles, modules, views
- GitHub and GitLab integrations

## Troubleshooting

- plane-api container fails to start: Verify DATABASE_URL format and ensure plane-db is fully initialized before API startup
- File uploads not working: Check MinIO credentials match between plane-api AWS_* variables and plane-minio MINIO_ROOT_* settings
- Background tasks not processing: Ensure plane-worker container is running and Redis connection is established via REDIS_URL
- Email notifications not sending: Verify EMAIL_HOST, EMAIL_HOST_USER, and EMAIL_HOST_PASSWORD variables are correctly set in plane-api
- plane-web shows API connection errors: Confirm NEXT_PUBLIC_API_BASE_URL points to accessible plane-api service and matches your domain setup
- Scheduled tasks not executing: Check plane-beat container logs and ensure Celery beat scheduler is connecting to Redis successfully

