Plane Admin Guide

This guide is the operational and architectural reference for Plane Community Edition — the open-source project management platform in the makeplane/plane repository. It is written for the people who deploy, operate, secure, integrate with, and extend a self-hosted Plane instance: administrators, DevOps/SRE, platform engineers, and developers.

It covers the system architecture, every deployment method, the complete environment-variable reference, the REST API, authentication and SSO, security model, day-2 operations (backup/restore/upgrade), the management-command toolbox, and the internal structure of the codebase.

Note

This repository is the Community Edition (CE). Plane also has paid/enterprise tiers built as an overlay (ee/ directories and a separate enterprise distribution). Configuration and features described here are CE unless explicitly marked. Where you see a ce/ path in the source, an ee/ sibling typically exists in non-CE builds.

1. Executive Summary

Plane is a multi-service web application, not a single process. A self-hosted instance is a small fleet of containers coordinated by Docker Compose (or Swarm/Kubernetes), fronted by a Caddy reverse proxy that terminates TLS.

Two truths to internalize before operating Plane:

1. It is a distributed app. The API, three frontends, the live server, the worker, the beat scheduler, and the migrator are separate containers that all read the same environment. A misconfigured WEB_URL or CORS_ALLOWED_ORIGINS breaks the whole thing even if every container is "up".
2. There are two distinct APIs. A session-authenticated web API (/api/) used by the frontends, and an API-key-authenticated external API (/api/v1/) for integrations. They live in different Django apps (plane.app vs plane.api) with different middleware and auth.

2. Architecture

2.1 Service topology

                          Internet
                             │
                    ┌────────▼─────────┐
                    │   proxy (Caddy)  │  :80 / :443  — auto TLS (Let's Encrypt)
                    │  Caddyfile.ce    │  routes by path
                    └───┬───┬───┬───┬──┘
        /  ───────────► web │   │   │ space ◄─────── /spaces
        /god-mode ───► admin    │   │
        /live (ws) ─────────► live  │
        /api, /api/v1 ──────────► api (Django :8000, gunicorn/uvicorn)
                                     │
            ┌────────────────────────┼───────────────────────────┐
            ▼            ▼            ▼            ▼               ▼
        plane-db     plane-redis  plane-mq     plane-minio   (worker / beat)
        Postgres15   Valkey7.2    RabbitMQ    MinIO (S3)      Celery

2.2 The container roster

From docker-compose.yml, a full instance runs these services:

Important

The migrator is a run-once container (restart: no). It applies database migrations and exits. After an upgrade, confirm it ran to completion before declaring the deployment healthy — an API that starts against an un-migrated database will throw schema errors.

2.3 Request routing

The Caddy Caddyfile.ce routes by path prefix:

Warning

Changing a base path (e.g. APP_BASE_PATH) without aligning the proxy config and the matching VITE_*_BASE_PATH build-time variable produces broken static asset paths (community issue #5200 — "APP_BASE_URL does not change static paths"). The frontends bake VITE_* values at build time; runtime env alone is not enough if you change paths.

2.4 The two APIs

Note

DRF endpoints in Plane are class-based (APIView/Endpoint subclasses), so they do not appear in naive route scrapes. The authoritative endpoint list is the urlpatterns in apps/api/plane/api/urls/ (external) and apps/api/plane/app/urls/ (web). See Section 6.

2.5 Background processing

Asynchronous work (email delivery, webhook dispatch, exports, notifications, importers, cleanup) runs through Celery with RabbitMQ as the broker and Redis for results/locks:

• bgworker consumes tasks (plane/bgtasks/).
• beatworker schedules periodic tasks via django-celery-beat (e.g. hard-delete of soft-deleted records after HARD_DELETE_AFTER_DAYS).

2.6 Real-time collaboration

apps/live is a standalone Node/TypeScript service that powers collaborative page editing and live presence. It authenticates clients against the API using a shared secret (LIVE_SERVER_SECRET_KEY) and uses Redis for coordination. If live is down, pages still load but lose real-time co-editing.

3. Requirements

3.1 Minimum host

3.2 Software versions (pinned)

Backend (apps/api/requirements/base.txt):

Frontend/monorepo:

Note

Several dependency pins are security-driven and called out in the requirements file (e.g. urllib3>=2.7.0 for CVE fixes, requests==2.33.0 for the TLS-context adapter hook used in SSRF IP pinning). Do not downgrade them.

4. Deployment

Plane ships four deployment topologies under deployments/, all Community Edition:

4.1 Docker Compose (recommended)

The official release installer drives Compose deployments:

mkdir plane-selfhost && cd plane-selfhost
curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh
chmod +x setup.sh
./setup.sh

The interactive menu:

1) Install (x86_64)   2) Start   3) Stop   4) Restart
5) Upgrade   6) View Logs   7) Backup Data   8) Exit

Choosing Install creates a plane-app/ directory with docker-compose.yaml and plane.env. Edit plane.env (see Section 5), then re-run and choose Start.

Tip

The installer's Backup Data action and the bundled restore.sh / restore-airgapped.sh scripts (in deployments/cli/community) are your supported backup/restore path. There's also migration-0.13-0.14.sh for that specific version jump.

4.2 Docker Swarm

Use swarm.sh (downloaded the same way as setup.sh but from the swarm release asset). It supports per-service replicas — set WEB_REPLICAS, API_REPLICAS, WORKER_REPLICAS, LIVE_REPLICAS, etc. in the env to scale horizontally.

4.3 Kubernetes (Helm)

The community Helm chart is published as plane-ce on Artifact Hub (makeplane repository). It maps the same services to Deployments/StatefulSets.

Warning

A known Helm gotcha: setting api_key_rate_limit via env may not override the default if the chart's values aren't wired correctly (community issue #9034). Verify rate-limit overrides actually take effect after a Helm upgrade by checking the running API container's environment.

4.4 All-in-one (AIO)

deployments/aio/community (with build.sh / start.sh and Caddyfile.aio.ce) bundles every service into a single container for the simplest possible footprint. Convenient for demos and small instances; less flexible for scaling than Compose/Swarm/K8s.

4.5 Local development

For contributors, setup.sh (repo root) copies every per-service .env.example to .env (root, web, api, space, admin, live), generates a Django SECRET_KEY, runs pnpm install, and then you start with:

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

The monorepo build is orchestrated by Turborepo:

pnpm dev      # turbo run dev (all apps in watch mode)
pnpm build    # turbo run build
pnpm check    # lint + types + format across the workspace

5. Configuration Reference

Configuration is entirely environment-variable driven. In production the release installer writes a single flat plane.env (template: deployments/cli/community/variables.env). In local dev, configuration is split across per-app .env files. Django reads variables in apps/api/plane/settings/ (common.py, production.py, local.py, storage.py).

Caution

Frontend variables (VITE_*) are build-time in the SPAs. Changing them requires rebuilding the corresponding image, not just restarting it. Backend variables (everything else) are read at container start.

5.1 Core / web addressing

5.2 Database (PostgreSQL)

5.3 Redis, RabbitMQ, Celery

5.4 Object storage (MinIO / S3)

5.5 Security & sessions

5.6 TLS / proxy (Caddy)

5.7 Email (SMTP)

Configured via env or, preferably, in God mode (stored in the instance config; see license/utils/instance_value.py):

Important

Without SMTP, magic-link login emails and member invitations will not send. Configure email before onboarding a team. Test with the test_email management command (see Section 9).

5.8 Authentication providers

5.9 AI, analytics & integrations

Tip

For a privacy-hardened instance, leave POSTHOG_*, SCOUT_*, and ANALYTICS_* unset to disable outbound telemetry. None are required for core functionality.

6. REST API Reference

Plane exposes a stable, documented external API under /api/v1/, authenticated with the X-API-Key header (tokens created in Workspace Settings → API Tokens).

6.1 Conventions

• Base path: /api/v1/
• Auth: X-API-Key: <token> (middleware: plane/api/middleware/api_authentication.py; invalid tokens return Given API token is not valid).
• Scoping: Most resources are nested under workspaces/<slug>/projects/<project_id>/....
• Rate limit: API_KEY_RATE_LIMIT (default 60/min) → HTTP 429 when exceeded.
• Pagination: Cursor-based (cursor, per_page query params).
• IDs: UUIDs for resources; workspaces are addressed by slug.

6.2 Endpoint catalogue

Derived from apps/api/plane/api/urls/. {slug} = workspace slug, {project_id} and other IDs are UUIDs.

Projects (project.py)

Work Items / Issues (work_item.py) — list/create/detail plus sub-resources (comments, links, attachments, activity).

Cycles (cycle.py)

Modules (module.py)

States (state.py), Labels (label.py)

Estimates (estimate.py)

Intake (intake.py)

Members (member.py)

Invitations (invite.py): DRF router under workspaces/{slug}/invitations/.

Assets (asset.py) — file uploads via presigned URLs:

Stickies (sticky.py), User (user.py): personal sticky notes and the authenticated user's profile.

6.3 Interactive docs (OpenAPI)

Plane generates an OpenAPI 3 schema via drf-spectacular. Enable it with ENABLE_DRF_SPECTACULAR=1, then browse:

Note

The schema is curated for the public API. Filtering and tagging hooks live in apps/api/plane/utils/openapi/ (preprocess_filter_api_v1_paths, postprocess_assign_tags).

6.4 Example: end-to-end work-item creation

export PLANE=https://plane.example.com
export KEY="your-api-key"
export WS="my-team"

# 1. Find a project
PROJECT=$(curl -s "$PLANE/api/v1/workspaces/$WS/projects/" -H "X-API-Key: $KEY" \
  | jq -r '.results[0].id')

# 2. Create a work item
curl -s -X POST "$PLANE/api/v1/workspaces/$WS/projects/$PROJECT/issues/" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"name":"Investigate slow dashboard","priority":"high"}'

{"id":"…","name":"Investigate slow dashboard","sequence_id":42,"priority":"high", …}

7. Authentication, SSO, and the data model

7.1 Authentication methods

Plane's auth lives in apps/api/plane/authentication/:

• Credentials (provider/credentials/): email + password, and passwordless magic code (email).
• OAuth (provider/oauth/): Google, GitHub, GitLab, Gitea.

Configure providers in God mode (or via the configure_instance command / env vars in Section 5.8). Toggle open sign-up with ENABLE_SIGNUP and magic links with ENABLE_MAGIC_LINK_LOGIN.

Caution

OAuth redirect URIs must match your real public domain and port. A mismatch produces invalid oauth2 redirect_uri (community issue #5853). Set WEB_URL correctly before registering OAuth apps.

7.2 Permission model

Authorization is enforced by DRF permission classes in apps/api/plane/app/permissions/. Roles are hierarchical:

• Workspace roles: Admin, Member, Guest.
• Project roles: Admin, Member, Guest (the ROLE enum), applied per project membership.

Each endpoint checks the caller's workspace/project role before allowing reads or writes.

7.3 Core data model (the nouns)

The Django models in apps/api/plane/db/models/ define the domain. Key entities:

User ──< WorkspaceMember >── Workspace ──< Project ──< Issue (Work Item)
                                   │            ├──< Cycle ──< CycleIssue
                                   │            ├──< Module ──< ModuleIssue
                                   │            ├──< State (StateGroup)
                                   │            ├──< Label
                                   │            ├──< IssueView (Views)
                                   │            ├──< Page ──< PageVersion
                                   │            ├──< Estimate ──< EstimatePoint
                                   │            └──< Intake ──< IntakeIssue
                                   └──< Webhook, DeployBoard, APIToken

Most models inherit soft-delete and audit fields from base classes (BaseModel, ProjectBaseModel, WorkspaceBaseModel).

8. Security

Plane CE includes several deliberate security controls. Operators should understand and not weaken them.

8.1 SSRF protection on webhooks and link unfurling

Webhook targets and outbound URL fetches are validated against private/internal networks. The code (plane/utils/ip_address.py, plane/utils/url_security.py) rejects:

• Non-HTTP(S) schemes — Invalid URL scheme. Only HTTP and HTTPS are allowed.
• Private/internal network addresses — Access to private/internal networks is not allowed.
• Unresolvable hosts and excessive redirects.

To allow specific internal targets (e.g. a trusted internal service), use the allowlists: WEBHOOK_ALLOWED_IPS (CIDR/IPs) and WEBHOOK_ALLOWED_HOSTS (hostnames). WEBHOOK_DISALLOWED_DOMAINS blocks specific domains.

Warning

Widening these allowlists weakens SSRF protection. Only add IPs/hosts you fully trust, and never allow 0.0.0.0/0.

8.2 Input and content safety

• HTML content is sanitized with nh3 before storage/render.
• Workspace slugs are validated (Slug is not valid) to prevent routing abuse.
• Upload size is capped by FILE_SIZE_LIMIT.

8.3 Rate limiting

• External API: API_KEY_RATE_LIMIT (default 60/min) per token.
• Anonymous auth endpoints (magic link, sign-in, sign-up): AUTHENTICATION_RATE_LIMIT (default 10/min) per IP — a brute-force/abuse guard.

8.4 Secrets and transport

• Set strong, unique values for SECRET_KEY, LIVE_SERVER_SECRET_KEY, DB/RabbitMQ/MinIO credentials. The defaults (plane/plane, access-key/secret-key) are for local dev only.
• Run with DEBUG=0 in production.
• Terminate TLS at Caddy (CERT_EMAIL for Let's Encrypt) or at your own load balancer with TRUSTED_PROXIES set appropriately.

8.5 Hardening checklist

• [ ] DEBUG=0
• [ ] Strong SECRET_KEY and LIVE_SERVER_SECRET_KEY
• [ ] Non-default Postgres / RabbitMQ / MinIO credentials
• [ ] WEB_URL and CORS_ALLOWED_ORIGINS pinned to your domain (not * origins)
• [ ] TLS enabled (CERT_EMAIL set, or external TLS + TRUSTED_PROXIES)
• [ ] Telemetry disabled if undesired (POSTHOG_*, SCOUT_*, ANALYTICS_* unset)
• [ ] Webhook allowlists minimal; SSRF protection intact
• [ ] ENABLE_SIGNUP=0 for closed instances

9. Management Commands

Run Django management commands inside the api container: docker exec -it api python manage.py <command>.

9.1 Instance setup & admin

9.2 User & workspace operations

9.3 Data integrity & maintenance

9.4 Startup guards

Tip

First-run admin bootstrap, in order: bring the stack up → configure_instance (loads provider/email config) → create_instance_admin [email removed] → sign in and open /god-mode.

10. Operations

10.1 Health and logs

# Service status
docker compose ps

# Tail logs (or use ./setup.sh → View Logs)
docker compose logs -f api worker beat-worker live

Note

A known healthcheck issue: the space container's healthcheck has failed when curl is missing from the image (community issue #9196). If space reports unhealthy but serves traffic, verify the healthcheck command rather than assuming the service is down.

10.2 Backup

Back up three stores together:

1. PostgreSQL — all relational data.
2. Object storage (MinIO/S3) — file attachments.
3. plane.env — your configuration and secrets.

# Database dump
docker exec plane-db pg_dump -U plane plane > plane_db_$(date +%F).sql

The installer's Backup Data action and restore.sh / restore-airgapped.sh in deployments/cli/community are the supported, tested path — prefer them over ad-hoc scripts.

Caution

A database backup alone is not a full backup. Attachments live in object storage. Restoring the DB without the bucket leaves work items pointing at missing files.

10.3 Restore

Use restore.sh (or restore-airgapped.sh for offline environments) from deployments/cli/community. Restore the database and the object store from the same point in time to avoid dangling asset references.

10.4 Upgrades

./setup.sh        # choose: 7) Backup Data  (always first)
./setup.sh        # choose: 5) Upgrade

The upgrade pulls new images and runs the migrator container. Verify:

• [ ] plane-migrator completed (check its logs; it should exit 0).
• [ ] api starts cleanly (no schema errors).
• [ ] Frontends load and the version updates.

Version-specific migration helpers (e.g. migration-0.13-0.14.sh) exist for breaking jumps — read release notes before major upgrades.

10.5 Scaling

• Increase GUNICORN_WORKERS for API throughput.
• In Swarm/K8s, raise *_REPLICAS (web/api/worker/live).
• Add a Postgres read replica (ENABLE_READ_REPLICA=1 + replica vars) to offload reads; routing is handled by plane/middleware DB routing.
• Postgres is launched with max_connections=1000; tune to your worker/replica count.

10.6 Periodic jobs

beat-worker runs scheduled Celery tasks (via django-celery-beat), including hard-deletion of soft-deleted records after HARD_DELETE_AFTER_DAYS. Keep the beat worker running; without it, soft-deleted data is never purged and scheduled notifications won't fire.

11. Codebase Internals (for developers)

11.1 Monorepo layout

plane/
├── apps/
│   ├── api/      Django + DRF backend (the system of record)
│   │   └── plane/
│   │       ├── app/             Web API (session auth)  — views, urls, serializers
│   │       ├── api/             External API (X-API-Key) — views, urls, serializers
│   │       ├── db/models/       Domain models + migrations + management commands
│   │       ├── authentication/  Credentials + OAuth providers, adapters, middleware
│   │       ├── bgtasks/         Celery tasks
│   │       ├── license/         Instance registration / God-mode config
│   │       ├── settings/        common/local/production/storage settings
│   │       └── utils/           Pagination, exporters, OpenAPI, SSRF guards, analytics
│   ├── web/      Main app SPA (React Router + Vite + MobX)
│   ├── admin/    God-mode instance admin SPA
│   ├── space/    Public published-views SPA
│   ├── live/     Node/TS real-time collaboration server
│   └── proxy/    Caddy build + Caddyfiles
├── packages/     Shared TS libraries (see below)
└── deployments/  cli / swarm / kubernetes / aio  (community)

11.2 Shared packages

The frontends compose from shared workspace packages (packages/*), built with Turborepo:

11.3 Frontend architecture notes

• The web SPAs use React Router + Vite (the project migrated off Next.js — note VITE_* env vars and react-router.config.ts, not NEXT_PUBLIC_*).
• State is managed with MobX stores (apps/web/core/store/), organized by domain (issue, cycle, module, workspace, member, …), with ce/ee overrides for edition-specific behavior.
• API access goes through @plane/services and apps/web/core/services/.

11.4 The CE/EE split

Throughout the code, ce/ directories hold Community Edition implementations and ee/ directories (present in non-CE builds) hold enterprise overrides. The build selects one based on edition. When reading or extending CE, stay within ce/ paths; an ee/ import in CE will be a stub or absent.

11.5 Backend conventions

• Two URL trees, two middlewares: plane.app (session) and plane.api (API key) are deliberately separate. Add public-API endpoints under plane/api/, not plane/app/.
• Serializers mirror the URL split (app/serializers/, api/serializers/).
• Soft deletes via base models; hard deletion is a scheduled task.
• Pagination is cursor-based (plane/utils/paginator.py, global_paginator.py).
• Exports use the schema-based exporter framework (plane/utils/exporters/) supporting CSV/JSON/XLSX.

11.6 Testing

The backend test suite (apps/api/plane/tests/) is organized into:

# In apps/api
python -m pytest                       # all
./run_tests.py -u                      # unit only
./run_tests.py -c -o                   # contract + coverage
./run_tests.py -p                      # parallel

External services are mocked (mock_redis, mock_elasticsearch, mock_celery) for fast tests.

12. Troubleshooting (operator)

Error: ImproperlyConfigured: APP_BASE_URL or WEB_URL is not set

• Cause: API started without WEB_URL.
• Solution: Set WEB_URL (and CORS_ALLOWED_ORIGINS) in plane.env; restart.
• Prevention: Treat WEB_URL as mandatory in every environment.

Static assets 404 after changing a base path

• Cause: VITE_*_BASE_PATH is build-time; changing APP_BASE_PATH at runtime doesn't update the bundled asset paths (issue #5200).
• Solution: Rebuild the SPA images with the matching VITE_*_BASE_PATH, and update the Caddy route.
• Prevention: Decide base paths before building images.

OAuth login fails: invalid oauth2 redirect_uri

• Cause: Redirect URI / WEB_URL mismatch (issue #5853).
• Solution: Align the provider's callback URL with your public domain/port and WEB_URL.
• Prevention: Configure WEB_URL before registering OAuth apps.

Helm: api_key_rate_limit override ignored

• Cause: Chart values not propagating the env var (issue #9034).
• Solution: Verify the rendered Deployment actually sets API_KEY_RATE_LIMIT; patch values accordingly.
• Prevention: Confirm env after each Helm upgrade.

space container marked unhealthy

• Cause: Healthcheck uses curl, which may be absent from the image (issue #9196).
• Solution: Adjust the healthcheck or add curl; confirm the service actually serves before alarming.
• Prevention: Track upstream fixes; pin known-good image tags.

Webhook never fires / Access to private/internal networks is not allowed

• Cause: SSRF guard blocked a target resolving to a private network.
• Solution: Add the trusted target to WEBHOOK_ALLOWED_IPS / WEBHOOK_ALLOWED_HOSTS.
• Prevention: Use public, resolvable webhook endpoints, or allowlist deliberately and minimally.

Migrations didn't apply after upgrade

• Cause: The migrator container failed or was skipped.
• Solution: Re-run migrations (docker exec api python manage.py migrate) and check plane-migrator logs.
• Prevention: Verify the migrator exits 0 as part of every upgrade.

Emails not sending

• Cause: SMTP unset or using the console backend.
• Solution: Configure email in God mode or via EMAIL_* env; verify with test_email.
• Prevention: Set SMTP before onboarding users.

13. Improvements & Technical Debt (observed)

These are observations from the source and community tracker, useful for operators planning around rough edges and for contributors picking work.

• Base-path handling is build-time-coupled. Because the SPAs bake VITE_*_BASE_PATH, runtime base-path changes silently break assets (#5200). A runtime-resolved base path would remove a common self-host footgun.
• Healthcheck portability. The space healthcheck assumed curl (#9196). Healthchecks should use tooling guaranteed present in the image.
• Helm value wiring. Some env overrides (rate limit) didn't propagate through the chart (#9034); chart values deserve an integration test.
• Edge-case crashes. Archiving a cycle with no end date (#9169); Safari/iOS requestIdleCallback use without a guard (#9134); special characters in project name/identifier (#8969). These point to a need for more defensive input validation and browser-API feature detection.
• Deprecated AI env keys. OPENAI_API_KEY/OPENAI_API_BASE/GPT_ENGINE are marked deprecated in favor of God-mode-managed AI config; operators should migrate off the env keys.
• Installer OS coverage. The setup script has failed on some RHEL-based systems (#9199); broader OS testing would reduce install friction.

14. Quick Reference

Service ports (internal)

Must-set production variables

WEB_URL=https://plane.example.com
CORS_ALLOWED_ORIGINS=https://plane.example.com
SECRET_KEY=<50+ random chars>
LIVE_SERVER_SECRET_KEY=<random>
POSTGRES_PASSWORD=<strong>
RABBITMQ_PASSWORD=<strong>
AWS_ACCESS_KEY_ID=<strong>; AWS_SECRET_ACCESS_KEY=<strong>
CERT_EMAIL=[email removed]
DEBUG=0

Common operator commands

./setup.sh                                   # install/start/stop/upgrade/backup menu
docker compose ps                            # status
docker compose logs -f api worker            # logs
docker exec api python manage.py migrate     # apply migrations
docker exec api python manage.py create_instance_admin [email removed]
docker exec api python manage.py test_email --to_email [email removed]
docker exec plane-db pg_dump -U plane plane > backup.sql

API quick facts