homelab-optimized/docs/services/individual/plane.md

Plane.so

Open-source project management and issue tracking for modern software teams

Overview

Property	Value
Category	Productivity / Project Management
Host	guava (TrueNAS Scale)
Stack Name	plane-stack
Portainer ID	26
Status	✅ Active
Domain	guava.crista.home

Access

Type	URL
HTTP	http://guava.crista.home:3080 ← Primary
HTTPS	https://guava.crista.home:3443
Admin	First registered user becomes admin

Features

• 📋 Issue Tracking - Create, organize, and track issues with custom workflows
• 📊 Multiple Views - Kanban boards, lists, calendars, and Gantt charts
• 🔄 Cycles - Sprint/iteration planning and management
• 📁 Modules - Group related issues into feature modules
• 📄 Pages - Documentation and wiki functionality
• 🤖 AI Integration - Optional AI-powered features (requires OpenAI API key)
• 🔗 Integrations - GitHub, GitLab, Slack support
• 📱 Responsive - Works on desktop and mobile

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        plane-proxy (Caddy)                      │
│                     Port 3080 (HTTP) / 3443 (HTTPS)            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌─────────┐            │
│  │plane-web│  │ space   │  │  admin  │  │  live   │            │
│  │Frontend │  │ Public  │  │  Panel  │  │Realtime │            │
│  └────┬────┘  └────┬────┘  └────┬────┘  └────┬────┘            │
│       │            │            │            │                  │
│       └────────────┴────────────┴────────────┘                  │
│                           │                                     │
│                    ┌──────┴──────┐                              │
│                    │  plane-api  │                              │
│                    │  (Django)   │                              │
│                    └──────┬──────┘                              │
│                           │                                     │
│       ┌───────────────────┼───────────────────┐                │
│       │                   │                   │                 │
│  ┌────┴────┐        ┌─────┴─────┐       ┌────┴────┐            │
│  │plane-db │        │plane-redis│       │plane-mq │            │
│  │Postgres │        │  Valkey   │       │RabbitMQ │            │
│  └─────────┘        └───────────┘       └─────────┘            │
│                           │                                     │
│                    ┌──────┴──────┐                              │
│                    │plane-minio  │                              │
│                    │ File Store  │                              │
│                    └─────────────┘                              │
└─────────────────────────────────────────────────────────────────┘

Services

Container	Image	Purpose	Health
plane-proxy	plane-proxy:stable	Caddy reverse proxy	Up
plane-web	plane-frontend:stable	React frontend	Healthy
plane-admin	plane-admin:stable	Admin dashboard	Healthy
plane-space	plane-space:stable	Public issue pages	Healthy
plane-live	plane-live:stable	WebSocket server	Up
plane-api	plane-backend:stable	Django REST API	Up
plane-worker	plane-backend:stable	Celery worker	Up
plane-beat	plane-backend:stable	Celery beat scheduler	Up
plane-migrator	plane-backend:stable	DB migrations	Completed
plane-db	postgres:15.7-alpine	PostgreSQL database	Healthy
plane-redis	valkey:7.2.11-alpine	Cache & sessions	Up
plane-mq	rabbitmq:3.13.6-management	Message queue	Up
plane-minio	minio:latest	S3-compatible storage	Up

Data Persistence

All data is stored on the ZFS pool at /mnt/data/plane-data/:

Directory	Purpose	Backup Priority
postgres/	PostgreSQL database	🔴 Critical
minio/	File uploads & attachments	🔴 Critical
redis/	Session cache	🟡 Medium
rabbitmq/	Message queue state	🟢 Low

Backup Recommendations

# Database backup
sudo docker exec plane-db pg_dump -U plane plane > plane_backup_$(date +%Y%m%d).sql

# Full data backup
sudo tar -czf plane_data_$(date +%Y%m%d).tar.gz /mnt/data/plane-data/

Configuration

Environment Variables

Variable	Default	Description
WEB_URL	http://localhost:3080	Public URL for the application
APP_DOMAIN	localhost	Domain for cookies/CORS
SECRET_KEY	(generated)	Django secret key
POSTGRES_PASSWORD	planeSecure2024!	Database password
RABBITMQ_PASSWORD	planeRabbit2024!	Message queue password
AWS_ACCESS_KEY_ID	planeaccess	MinIO access key
AWS_SECRET_ACCESS_KEY	planesecret123	MinIO secret key
FILE_SIZE_LIMIT	52428800	Max upload size (50MB)

Custom Domain Setup

To use a custom domain:

1. Update environment variables in Portainer:

   WEB_URL=https://plane.yourdomain.com
   APP_DOMAIN=plane.yourdomain.com
   

2. Configure DNS to point to guava (192.168.0.100)

3. Set up SSL certificate (Caddy auto-provisions Let's Encrypt)

Operations

Start/Stop via Portainer API

# Stop stack
curl -sk -X POST \
  -H 'X-API-Key: "REDACTED_API_KEY" \
  'https://192.168.0.100:31015/api/stacks/26/stop?endpointId=3'

# Start stack
curl -sk -X POST \
  -H 'X-API-Key: "REDACTED_API_KEY" \
  'https://192.168.0.100:31015/api/stacks/26/start?endpointId=3'

View Logs

# Via SSH to guava
ssh guava "sudo docker logs plane-api --tail 100"
ssh guava "sudo docker logs plane-worker --tail 100"

# All containers
ssh guava "sudo docker compose -f /data/compose/26/docker-compose.yml logs -f"

Update to Latest Version

1. Stop the stack in Portainer
2. Pull new images:

   ssh guava "sudo docker compose -f /data/compose/26/docker-compose.yml pull"
   

3. Start the stack in Portainer

Health Check

# API health
curl -s http://guava.crista.home:3080/api/v1/health/

# Database connection
ssh guava "sudo docker exec plane-db pg_isready -U plane"

# Redis connection  
ssh guava "sudo docker exec plane-redis redis-cli ping"

Troubleshooting

API Not Starting

Check if migrations completed:

ssh guava "sudo docker logs plane-migrator"

The API waits for migrations. If stuck, check database connectivity.

Space Service Unhealthy

This is normal during initial startup. The space service takes longer to initialize. Wait 2-3 minutes after deployment.

File Uploads Failing

Check MinIO status:

ssh guava "sudo docker logs plane-minio"
ssh guava "curl -s http://localhost:9000/minio/health/live"

Performance Issues

Plane is resource-intensive. Recommended minimums:

• 4 CPU cores
• 8GB RAM
• SSD storage

Security Considerations

• 🔐 Default passwords should be changed for production use
• 🔒 HTTPS is available on port 3443 (self-signed cert by default)
• 🛡️ Consider putting behind Cloudflare Tunnel or reverse proxy
• 📝 First user to register becomes admin

Related Files

• Stack Definition: hosts/physical/guava/plane.yaml
• Host Documentation: hosts/physical/guava/README.md

External Links

• Plane.so Website
• Plane GitHub
• Self-Hosting Docs
• Docker Compose Guide

---

Deployed: February 2026 | Managed via Portainer on guava