diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..b2aa565 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,68 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is the **Plane developer documentation site** built with **VitePress** (Vue 3-based static site generator). It covers REST API reference, self-hosting guides, and developer tools documentation for the Plane project management platform. + +Live site: https://developers.plane.so + +## Commands + +```bash +pnpm install # Install dependencies (use --frozen-lockfile in CI) +pnpm dev # Start dev server at http://localhost:5173 +pnpm build # Production build +pnpm preview # Preview production build +pnpm check:format # Check Prettier formatting +pnpm fix:format # Auto-fix Prettier formatting +``` + +**CI checks on PRs** (to `master`): Prettier formatting + VitePress build must pass. + +## Architecture + +- **`docs/`** — All documentation content and VitePress config + - **`docs/.vitepress/config.mts`** — Main VitePress config: navigation, sidebar structure, SEO, Algolia search, analytics. This is a large file (~39KB) that defines the entire site structure. + - **`docs/.vitepress/theme/`** — Custom theme with Vue components and global styles + - **`docs/api-reference/`** — REST API endpoint docs (180+ endpoints across 25+ categories) + - **`docs/self-hosting/`** — Deployment guides (Docker, Kubernetes, etc.) + - **`docs/dev-tools/`** — Webhooks, OAuth apps, agents, MCP server docs + +## Custom Vue Components + +Used directly in markdown files — defined in `docs/.vitepress/theme/components/`: + +| Component | Usage | +| ---------------------- | ----------------------------------------------------------------- | +| `` | API parameter with name, type, required badge, expandable details | +| `` | Multi-language code tabs (cURL, Python, JavaScript) | +| `` | Syntax-highlighted API response JSON | +| `` | Feature card with icon, title, description | +| `` | Responsive grid layout (2, 3, or 4 columns) | + +## API Documentation Pattern + +API endpoint pages follow a strict two-column layout pattern: + +```markdown +
+
+ +
+
+ +
+
+``` + +Each endpoint page: one file per endpoint, includes path/body params, OAuth scopes, and code examples in cURL/Python/JavaScript. + +## Conventions + +- **Frontmatter**: Every markdown page needs `title`, `description`, and `keywords` fields +- **Images**: Stored in `docs/.vitepress/public/images/`, referenced with absolute paths (`/images/...`) +- **Branch workflow**: Branch from `master`, use `fix/`, `feat/`, `docs/`, `update/` prefixes +- **Formatting**: Prettier enforced — 120 char width, 2-space indent, semicolons, double quotes, ES5 trailing commas +- **Sidebar updates**: When adding new pages, update the sidebar config in `docs/.vitepress/config.mts` diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aeccf53..87c7b4b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -106,11 +106,11 @@ Write clear, concise commit messages: ### Pull Requests -1. Create a branch from `preview` +1. Create a branch from `master` 2. Make your changes 3. Test locally with `pnpm dev` 4. Build and verify with `pnpm build && pnpm preview` -5. Submit a pull request to the `preview` branch +5. Submit a pull request to the `master` branch ### PR Guidelines diff --git a/docs/dev-tools/build-plane-app/create-oauth-application.md b/docs/dev-tools/build-plane-app/create-oauth-application.md index e74129a..1d5f85b 100644 --- a/docs/dev-tools/build-plane-app/create-oauth-application.md +++ b/docs/dev-tools/build-plane-app/create-oauth-application.md @@ -6,7 +6,12 @@ keywords: plane oauth application, create plane app, client id secret, plane app # Create an OAuth Application -1. Navigate to **Workspace Settings** → **Integrations**. `https://app.plane.so//settings/integrations/` +1. Navigate to **Workspace Settings** → **Integrations**. + +```text +https://app.plane.so//settings/integrations/ +``` + 2. Click **Build your own**. 3. Fill in the required details: diff --git a/docs/dev-tools/build-plane-app/examples.md b/docs/dev-tools/build-plane-app/examples.md index f881845..f20fc3d 100644 --- a/docs/dev-tools/build-plane-app/examples.md +++ b/docs/dev-tools/build-plane-app/examples.md @@ -242,4 +242,4 @@ if __name__ == "__main__": ## Publish to Marketplace -Apps can be listed on the [Plane Marketplace](https://plane.so/marketplace/integrations). Contact [support@plane.so](mailto:support@plane.so) to list your app. \ No newline at end of file +Apps can be listed on the [Plane Marketplace](https://plane.so/marketplace/integrations). Contact [support@plane.so](mailto:support@plane.so) to list your app. diff --git a/docs/dev-tools/build-plane-app/oauth-scopes.md b/docs/dev-tools/build-plane-app/oauth-scopes.md index 6c06eaf..f42ddcd 100644 --- a/docs/dev-tools/build-plane-app/oauth-scopes.md +++ b/docs/dev-tools/build-plane-app/oauth-scopes.md @@ -10,125 +10,125 @@ This document lists all OAuth scopes available when building a Plane app. Reques ## Project scopes -| Scope | Description | -|-------|-------------| -| `projects:read` | Read projects | -| `projects:write` | Create and update projects | -| `projects.features:read` | Read project features | -| `projects.features:write` | Create and update project features | -| `projects.members:read` | Read project members | -| `projects.members:write` | Manage project members | -| `projects.states:read` | Read project states | -| `projects.states:write` | Create and update project states | -| `projects.labels:read` | Read project labels | -| `projects.labels:write` | Create and update project labels | -| `projects.intakes:read` | Read project intakes | -| `projects.intakes:write` | Create and update project intakes | -| `projects.epics:read` | Read project epics | -| `projects.epics:write` | Create and update project epics | -| `projects.cycles:read` | Read project cycles | -| `projects.cycles:write` | Create and update project cycles | -| `projects.pages:read` | Read project pages | -| `projects.pages:write` | Create and update project pages | -| `projects.modules:read` | Read project modules | -| `projects.modules:write` | Create and update project modules | -| `projects.work_items:read` | Read project work items | -| `projects.work_items:write` | Create and update project work items | -| `projects.work_items.comments:read` | Read work item comments | -| `projects.work_items.comments:write` | Create and update work item comments | -| `projects.work_items.attachments:read` | Read work item attachments | -| `projects.work_items.attachments:write` | Create and update work item attachments | -| `projects.work_items.links:read` | Read work item links | -| `projects.work_items.links:write` | Create and update work item links | -| `projects.work_items.relations:read` | Read work item relations | -| `projects.work_items.relations:write` | Create and update work item relations | -| `projects.work_items.activities:read` | Read work item activities | -| `projects.work_items.activities:write` | Create and update work item activities | -| `projects.work_items.worklogs:read` | Read work item worklogs | -| `projects.work_items.worklogs:write` | Create and update work item worklogs | -| `projects.work_item_types:read` | Read work item types | -| `projects.work_item_types:write` | Create and update work item types | -| `projects.work_item_properties:read` | Read work item properties | -| `projects.work_item_properties:write` | Create and update work item properties | -| `projects.work_item_property_options:read` | Read work item property options | +| Scope | Description | +| ------------------------------------------- | -------------------------------------------- | +| `projects:read` | Read projects | +| `projects:write` | Create and update projects | +| `projects.features:read` | Read project features | +| `projects.features:write` | Create and update project features | +| `projects.members:read` | Read project members | +| `projects.members:write` | Manage project members | +| `projects.states:read` | Read project states | +| `projects.states:write` | Create and update project states | +| `projects.labels:read` | Read project labels | +| `projects.labels:write` | Create and update project labels | +| `projects.intakes:read` | Read project intakes | +| `projects.intakes:write` | Create and update project intakes | +| `projects.epics:read` | Read project epics | +| `projects.epics:write` | Create and update project epics | +| `projects.cycles:read` | Read project cycles | +| `projects.cycles:write` | Create and update project cycles | +| `projects.pages:read` | Read project pages | +| `projects.pages:write` | Create and update project pages | +| `projects.modules:read` | Read project modules | +| `projects.modules:write` | Create and update project modules | +| `projects.work_items:read` | Read project work items | +| `projects.work_items:write` | Create and update project work items | +| `projects.work_items.comments:read` | Read work item comments | +| `projects.work_items.comments:write` | Create and update work item comments | +| `projects.work_items.attachments:read` | Read work item attachments | +| `projects.work_items.attachments:write` | Create and update work item attachments | +| `projects.work_items.links:read` | Read work item links | +| `projects.work_items.links:write` | Create and update work item links | +| `projects.work_items.relations:read` | Read work item relations | +| `projects.work_items.relations:write` | Create and update work item relations | +| `projects.work_items.activities:read` | Read work item activities | +| `projects.work_items.activities:write` | Create and update work item activities | +| `projects.work_items.worklogs:read` | Read work item worklogs | +| `projects.work_items.worklogs:write` | Create and update work item worklogs | +| `projects.work_item_types:read` | Read work item types | +| `projects.work_item_types:write` | Create and update work item types | +| `projects.work_item_properties:read` | Read work item properties | +| `projects.work_item_properties:write` | Create and update work item properties | +| `projects.work_item_property_options:read` | Read work item property options | | `projects.work_item_property_options:write` | Create and update work item property options | -| `projects.work_item_property_values:read` | Read work item property values | -| `projects.work_item_property_values:write` | Create and update work item property values | -| `projects.milestones:read` | Read project milestones | -| `projects.milestones:write` | Create and update project milestones | +| `projects.work_item_property_values:read` | Read work item property values | +| `projects.work_item_property_values:write` | Create and update work item property values | +| `projects.milestones:read` | Read project milestones | +| `projects.milestones:write` | Create and update project milestones | ## Wiki scopes -| Scope | Description | -|-------|-------------| -| `wiki.pages:read` | Read wiki pages | +| Scope | Description | +| ------------------ | ---------------------------- | +| `wiki.pages:read` | Read wiki pages | | `wiki.pages:write` | Create and update wiki pages | ## Customer scopes -| Scope | Description | -|-------|-------------| -| `customers:read` | Read customers | -| `customers:write` | Create and update customers | -| `customers.requests:read` | Read customer requests | -| `customers.requests:write` | Create and update customer requests | -| `customers.properties:read` | Read customer properties | -| `customers.properties:write` | Create and update customer properties | -| `customers.property_values:read` | Read customer property values | +| Scope | Description | +| --------------------------------- | ------------------------------------------ | +| `customers:read` | Read customers | +| `customers:write` | Create and update customers | +| `customers.requests:read` | Read customer requests | +| `customers.requests:write` | Create and update customer requests | +| `customers.properties:read` | Read customer properties | +| `customers.properties:write` | Create and update customer properties | +| `customers.property_values:read` | Read customer property values | | `customers.property_values:write` | Create and update customer property values | -| `customers.work_items:read` | Read customer work items | -| `customers.work_items:write` | Create and update customer work items | +| `customers.work_items:read` | Read customer work items | +| `customers.work_items:write` | Create and update customer work items | ## Initiatives scopes -| Scope | Description | -|-------|-------------| -| `initiatives:read` | Read initiatives | -| `initiatives:write` | Create and update initiatives | -| `initiatives.projects:read` | Read initiative projects | +| Scope | Description | +| ---------------------------- | ------------------------------------- | +| `initiatives:read` | Read initiatives | +| `initiatives:write` | Create and update initiatives | +| `initiatives.projects:read` | Read initiative projects | | `initiatives.projects:write` | Create and update initiative projects | -| `initiatives.epics:read` | Read initiative epics | -| `initiatives.epics:write` | Create and update initiative epics | -| `initiatives.labels:read` | Read initiative labels | -| `initiatives.labels:write` | Create and update initiative labels | +| `initiatives.epics:read` | Read initiative epics | +| `initiatives.epics:write` | Create and update initiative epics | +| `initiatives.labels:read` | Read initiative labels | +| `initiatives.labels:write` | Create and update initiative labels | ## Workspace scopes -| Scope | Description | -|-------|-------------| -| `workspaces.members:read` | Read workspace members | -| `workspaces.features:read` | Read workspace features | +| Scope | Description | +| --------------------------- | ------------------------------------ | +| `workspaces.members:read` | Read workspace members | +| `workspaces.features:read` | Read workspace features | | `workspaces.features:write` | Create and update workspace features | ## Stickies scopes -| Scope | Description | -|-------|-------------| -| `stickies:read` | Read stickies | +| Scope | Description | +| ---------------- | -------------------------- | +| `stickies:read` | Read stickies | | `stickies:write` | Create and update stickies | ## Teamspaces scopes -| Scope | Description | -|-------|-------------| -| `teamspaces:read` | Read teamspaces | -| `teamspaces:write` | Create and update teamspaces | -| `teamspaces.projects:read` | Read teamspace projects | +| Scope | Description | +| --------------------------- | ------------------------------------ | +| `teamspaces:read` | Read teamspaces | +| `teamspaces:write` | Create and update teamspaces | +| `teamspaces.projects:read` | Read teamspace projects | | `teamspaces.projects:write` | Create and update teamspace projects | -| `teamspaces.members:read` | Read teamspace members | -| `teamspaces.members:write` | Create and update teamspace members | +| `teamspaces.members:read` | Read teamspace members | +| `teamspaces.members:write` | Create and update teamspace members | ## Profile scopes -| Scope | Description | -|-------|-------------| +| Scope | Description | +| -------------- | ----------------- | | `profile:read` | Read user profile | ## Agent Run scopes -| Scope | Description | -|-------|-------------| -| `agent_runs:read` | Read agent runs | -| `agent_runs:write` | Create and update agent runs | -| `agent_runs.activities:read` | Read agent run activities | -| `agent_runs.activities:write` | Create and update agent run activities | \ No newline at end of file +| Scope | Description | +| ----------------------------- | -------------------------------------- | +| `agent_runs:read` | Read agent runs | +| `agent_runs:write` | Create and update agent runs | +| `agent_runs.activities:read` | Read agent run activities | +| `agent_runs.activities:write` | Create and update agent run activities | diff --git a/docs/dev-tools/build-plane-app/overview.md b/docs/dev-tools/build-plane-app/overview.md index 0a165f5..a1e8600 100644 --- a/docs/dev-tools/build-plane-app/overview.md +++ b/docs/dev-tools/build-plane-app/overview.md @@ -52,6 +52,7 @@ Follow these steps to build your first Plane app: ### 1. Create an OAuth application Register your app in Plane to get credentials: + - Navigate to **Workspace Settings** → **Integrations** - Configure your app's URLs and permissions - Store your **Client ID** and **Client Secret** securely @@ -61,6 +62,7 @@ Register your app in Plane to get credentials: ### 2. Choose your authentication flow Decide between Bot Token or User Token based on your use case: + - **Bot Token** - For agents, webhooks, and automation - **User Token** - For user-specific actions and permissions @@ -69,6 +71,7 @@ Decide between Bot Token or User Token based on your use case: ### 3. Implement OAuth Set up the OAuth flow to obtain access tokens: + - Redirect users to Plane's consent screen - Handle the callback with authorization code - Exchange code for access tokens @@ -79,6 +82,7 @@ Set up the OAuth flow to obtain access tokens: ### 4. Handle webhooks Set up webhook handlers to receive real-time events: + - Verify webhook signatures for security - Process events like work item updates, comments, and more - Respond to events with automated actions @@ -102,6 +106,7 @@ Free ngrok URLs change on restart. Update your app settings when the URL changes ### Official SDKs Speed up development with official SDKs for Node.js and Python: + - OAuth helpers for token management - Typed API clients for all endpoints - Built-in error handling and retries @@ -111,6 +116,7 @@ Speed up development with official SDKs for Node.js and Python: ### Complete examples See full working implementations: + - TypeScript (Express) example - Python (Flask) example - OAuth flow, webhooks, and API integration diff --git a/docs/self-hosting/editions-and-versions.md b/docs/self-hosting/editions-and-versions.md index a919d2e..f505aac 100644 --- a/docs/self-hosting/editions-and-versions.md +++ b/docs/self-hosting/editions-and-versions.md @@ -4,7 +4,6 @@ description: Compare Plane Community, Pro, Business, and Enterprise editions. Un keywords: plane editions, plane community edition, plane pro, plane enterprise, plane business, self-hosting comparison, plane pricing tiers --- - # Understanding Plane's editions Plane comes in four editions by how its deployed. Our Cloud is our only hosted edition as of 2025. Additionally, we offer three unique self-hosted editions tailored to meet two sets of unique needs—the open-source Community Edition, the recommended Commercial Edition, and the Airgapped Edition. @@ -43,21 +42,20 @@ Built for organizations with strict security and compliance requirements, the Ai The Airgapped Edition offers: -- **Complete isolation** -Operates entirely within your network perimeter with no external dependencies or outbound connections. - -- **Full feature parity** -Includes all features available in the standard Commercial Edition, including advanced work management, security controls, and governance tools +- **Complete isolation** + Operates entirely within your network perimeter with no external dependencies or outbound connections. -- **Version updates** - Updates from your own docker registry. +- **Full feature parity** + Includes all features available in the standard Commercial Edition, including advanced work management, security controls, and governance tools -- **Self-contained architecture** -All services, dependencies, and resources are bundled for deployment in restricted networks +- **Version updates** + Updates from your own docker registry. -- **Compliance-ready** -Designed to meet requirements for environments that prohibit external network communication +- **Self-contained architecture** + All services, dependencies, and resources are bundled for deployment in restricted networks +- **Compliance-ready** + Designed to meet requirements for environments that prohibit external network communication ## Why we separate editions @@ -83,7 +81,6 @@ Each of our editions is built on a distinct codebase. Versions with each differ For both the Commercial, Airgapped, and Community Editions, version updates are in your control. Regular updates ensure you’re benefiting from the latest features and improvements. See [Update Plane](/self-hosting/manage/upgrade-plane) for how to upgrade your versions. - ## Changelog -We maintain a detailed changelog for all editions. [Check it out](https://plane.so/changelog) and bookmark it to stay informed about the latest features, bug fixes, and improvements by edition. \ No newline at end of file +We maintain a detailed changelog for all editions. [Check it out](https://plane.so/changelog) and bookmark it to stay informed about the latest features, bug fixes, and improvements by edition. diff --git a/docs/self-hosting/govern/advanced-search.md b/docs/self-hosting/govern/advanced-search.md index 91a8e8a..8a23685 100644 --- a/docs/self-hosting/govern/advanced-search.md +++ b/docs/self-hosting/govern/advanced-search.md @@ -4,15 +4,14 @@ description: Enable full-text search in Plane with OpenSearch. Configure advance keywords: plane opensearch, full-text search, advanced search, search indexing, elasticsearch, self-hosting, plane search --- - # Configure OpenSearch for advanced search - Plane uses OpenSearch to provide advanced search capabilities across your workspace. This guide walks you through setting up OpenSearch integration on your self-hosted instance. ## Before you begin You'll need: + - An OpenSearch 2.x instance (self-hosted or managed service like AWS OpenSearch). ## What you get with advanced search @@ -28,54 +27,59 @@ Users can access advanced search using the global search shortcut (Cmd/Ctrl + K) ## Configure OpenSearch -Set environment variables in your Plane configuration. See [Environment variables reference](/self-hosting/govern/environment-variables#opensearch) for details. +Set environment variables in your Plane configuration. See [Environment variables reference](/self-hosting/govern/environment-variables#opensearch) for details. ### For Docker deployments 1. **Add configuration to your environment file** Edit `/opt/plane/plane.env`. - ```bash - # OpenSearch Settings - OPENSEARCH_ENABLED=1 - OPENSEARCH_URL=https://your-opensearch-instance:9200/ - OPENSEARCH_USERNAME=admin - OPENSEARCH_PASSWORD=your-secure-password - OPENSEARCH_INDEX_PREFIX=plane - ``` + + ```bash + # OpenSearch Settings + OPENSEARCH_ENABLED=1 + OPENSEARCH_URL=https://your-opensearch-instance:9200/ + OPENSEARCH_USERNAME=admin + OPENSEARCH_PASSWORD=your-secure-password + OPENSEARCH_INDEX_PREFIX=plane + ``` 2. **Restart Plane services** - ```bash - prime-cli restart - ``` + + ```bash + prime-cli restart + ``` or if managing containers directly: - ```bash - docker compose down - docker compose up -d - ``` + + ```bash + docker compose down + docker compose up -d + ``` 3. **Create search indices** Access the API container and create the necessary indices: - ```bash - # Access the API container - docker exec -it plane-api-1 sh - # Create all search indices (run once) - python manage.py manage_search_index index rebuild --force - ``` + ```bash + # Access the API container + docker exec -it plane-api-1 sh + + # Create all search indices (run once) + python manage.py manage_search_index index rebuild --force + ``` 4. **Index your existing data** Index all existing content into OpenSearch: - ```bash - # For small datasets - python manage.py manage_search_index document index --force - # For large datasets (recommended) - python manage.py manage_search_index --background document index --force - ``` + ```bash + # For small datasets + python manage.py manage_search_index document index --force + + # For large datasets (recommended) + python manage.py manage_search_index --background document index --force + ``` The background option processes indexing through Celery workers, which is better for instances with large amounts of data. @@ -86,59 +90,65 @@ The Plane Helm chart provides auto-setup for OpenSearch. If you're using your ow 1. **Configure Helm values** Get the current values file: - ```bash - helm show values plane/plane-enterprise > values.yaml - ``` + + ```bash + helm show values plane/plane-enterprise > values.yaml + ``` Edit `values.yaml` to add OpenSearch configuration: - ```yaml - env: - # OpenSearch configuration - opensearch_remote_url: 'https://your-opensearch-instance:9200/' - opensearch_remote_username: 'admin' - opensearch_remote_password: 'your-secure-password' - opensearch_index_prefix: 'plane' - ``` + + ```yaml + env: + # OpenSearch configuration + opensearch_remote_url: "https://your-opensearch-instance:9200/" + opensearch_remote_username: "admin" + opensearch_remote_password: "your-secure-password" + opensearch_index_prefix: "plane" + ``` Refer to the [Plane Helm chart documentation](https://artifacthub.io/packages/helm/makeplane/plane-enterprise?modal=values&path=env.opensearch_remote_url) for complete values structure. 2. **Upgrade your deployment** - ```bash - helm upgrade --install plane-app plane/plane-enterprise \ - --create-namespace \ - --namespace plane \ - -f values.yaml \ - --timeout 10m \ - --wait \ - --wait-for-jobs - ``` + + ```bash + helm upgrade --install plane-app plane/plane-enterprise \ + --create-namespace \ + --namespace plane \ + -f values.yaml \ + --timeout 10m \ + --wait \ + --wait-for-jobs + ``` 3. **Create search indices** Run these commands in the API pod. - ```bash - # Get the API pod name - API_POD=$(kubectl get pods -n plane --no-headers | grep api | head -1 | awk '{print $1}') - # Create all search indices (run once) - kubectl exec -n plane $API_POD -- python manage.py manage_search_index index rebuild --force - ``` + ```bash + # Get the API pod name + API_POD=$(kubectl get pods -n plane --no-headers | grep api | head -1 | awk '{print $1}') + + # Create all search indices (run once) + kubectl exec -n plane $API_POD -- python manage.py manage_search_index index rebuild --force + ``` 4. **Index your existing data** - Run these commands in the API pod. - ```bash - # For small datasets - kubectl exec -n plane $API_POD -- python manage.py manage_search_index document index --force + Run these commands in the API pod. + + ```bash + # For small datasets + kubectl exec -n plane $API_POD -- python manage.py manage_search_index document index --force - # For large datasets (recommended) - kubectl exec -n plane $API_POD -- python manage.py manage_search_index --background document index --force - ``` + # For large datasets (recommended) + kubectl exec -n plane $API_POD -- python manage.py manage_search_index --background document index --force + ``` ## Verify the setup ### Check OpenSearch connection Test that Plane can connect to your OpenSearch instance: + ```bash # Access your API container or pod docker exec -it plane-api-1 sh # For Docker @@ -150,6 +160,7 @@ python manage.py shell ``` Then run: + ```python from django.conf import settings from opensearchpy import OpenSearch @@ -171,6 +182,7 @@ print(client.cat.indices(format='json')) ### Verify indices were created List all created indices: + ```bash python manage.py manage_search_index list ``` @@ -189,6 +201,7 @@ You should see indices for work items, projects, cycles, modules, pages, and oth ### Resync data If search results become stale or inconsistent, resync your data: + ```bash python manage.py manage_search_index document index --force ``` @@ -198,6 +211,7 @@ This reindexes all content without recreating the index structure. ### Complete rebuild For a complete reset (recreates indices and reindexes all data): + ```bash # Recreate all indices python manage.py manage_search_index index rebuild --force @@ -213,11 +227,13 @@ Use this if index structure needs updating or if you're experiencing persistent Check API logs OpenSearch-related errors: **Docker:** + ```bash docker compose logs api | grep -i opensearch ``` **Kubernetes:** + ```bash kubectl logs -n plane -l app.kubernetes.io/component=api | grep -i opensearch ``` @@ -247,6 +263,7 @@ Instead, Plane batches updates through Redis. When a signal fires, the update go The batching pattern also provides resilience. If OpenSearch is temporarily unavailable, updates accumulate in Redis and process once connectivity returns. This requires Redis 6.2+ which supports the LPOP count operation needed for efficient batch retrieval. ### The complete flow + ![OpenSeach flow](/images/open-search/opensearch-flow.webp) When you search, queries bypass this synchronization process entirely. The Plane API sends your search query directly to OpenSearch, which returns results almost instantly. Your database isn't involved in search queries at all — this is the key to search performance. @@ -259,16 +276,16 @@ The answer lies in how different entities need different search behaviors. Work Each index is optimized for its content type: -| Index | Content | Search Features | -|-------|---------|-----------------| -| `{prefix}_issues` | Work items | Full-text search, field weighting (title > description), state filtering | -| `{prefix}_issue_comments` | Comments | Comment search within work items, parent-child relationships | -| `{prefix}_projects` | Projects | Project discovery, metadata filtering (dates, counts, status) | -| `{prefix}_cycles` | Cycles | Cycle search, time-based filtering and aggregations | -| `{prefix}_modules` | Modules | Module/sprint search, planning aggregations | -| `{prefix}_pages` | Pages | Page content search, rich text analysis for long-form content | -| `{prefix}_workspaces` | Workspaces | Workspace search and discovery | -| `{prefix}_issue_views` | Saved views | Saved view search and filtering | -| `{prefix}_teamspaces` | Teamspaces | Teamspace discovery | - -The `{prefix}` is whatever you configured in `OPENSEARCH_INDEX_PREFIX`, or empty if you didn't set a prefix. This prefix exists because you might run multiple Plane instances pointing to the same OpenSearch cluster. The prefix prevents different instances from accidentally sharing or conflicting with each other's indices. \ No newline at end of file +| Index | Content | Search Features | +| ------------------------- | ----------- | ------------------------------------------------------------------------ | +| `{prefix}_issues` | Work items | Full-text search, field weighting (title > description), state filtering | +| `{prefix}_issue_comments` | Comments | Comment search within work items, parent-child relationships | +| `{prefix}_projects` | Projects | Project discovery, metadata filtering (dates, counts, status) | +| `{prefix}_cycles` | Cycles | Cycle search, time-based filtering and aggregations | +| `{prefix}_modules` | Modules | Module/sprint search, planning aggregations | +| `{prefix}_pages` | Pages | Page content search, rich text analysis for long-form content | +| `{prefix}_workspaces` | Workspaces | Workspace search and discovery | +| `{prefix}_issue_views` | Saved views | Saved view search and filtering | +| `{prefix}_teamspaces` | Teamspaces | Teamspace discovery | + +The `{prefix}` is whatever you configured in `OPENSEARCH_INDEX_PREFIX`, or empty if you didn't set a prefix. This prefix exists because you might run multiple Plane instances pointing to the same OpenSearch cluster. The prefix prevents different instances from accidentally sharing or conflicting with each other's indices. diff --git a/docs/self-hosting/govern/authentication.md b/docs/self-hosting/govern/authentication.md index a2a41fb..23198e9 100644 --- a/docs/self-hosting/govern/authentication.md +++ b/docs/self-hosting/govern/authentication.md @@ -4,7 +4,6 @@ description: Configure authentication methods for self-hosted Plane. Setup OAuth keywords: plane authentication, auth providers, sso setup, oauth configuration, saml, oidc, ldap, self-hosting security --- - # Overview Plane offers several methods you can choose from to let your users log in to your Plane instance. Configure these methods in Authentication on /god-mode of your instance. @@ -21,4 +20,4 @@ Plane lets your users log in with codes sent over email. This is disabled if SMT ### Passwords -Your users can log in with passwords that they or you set for them. This is toggled on when SMTP isn't configured for your instance. Disable it if you would like to use another authentication method below. \ No newline at end of file +Your users can log in with passwords that they or you set for them. This is toggled on when SMTP isn't configured for your instance. Disable it if you would like to use another authentication method below. diff --git a/docs/self-hosting/govern/communication.md b/docs/self-hosting/govern/communication.md index 022bd5d..e4a0d34 100644 --- a/docs/self-hosting/govern/communication.md +++ b/docs/self-hosting/govern/communication.md @@ -4,7 +4,6 @@ description: Configure SMTP email settings for Plane. Setup email notifications keywords: plane smtp, email notifications, smtp configuration, email setup, self-hosting, plane email, mail server --- - # Configure SMTP for email notifications Either during your set-up or sometime later, you will want to set SMTP settings to let your users get emails to reset passwords, onboard themselves right, and get notifications for changes, and receive exports of your data. @@ -35,7 +34,6 @@ Navigate to `Email` in `/god-mode`and you will see ↓. - **Password**\ Specify the password for the SMTP configuration here. - ::: tip **Google Workspaces** @@ -44,7 +42,6 @@ If your Plane instance is not accessible on the internet, Gmail may block profil To resolve this issue, you must configure the Image URL proxy allowlist in your Google Workspace settings to include your Plane instance's URL. Refer to Google’s documentation for instructions: [Allowlist image URLs](https://support.google.com/a/answer/3299041?hl=en). ::: - ## Configuration for popular email services providers ### Amazon SES @@ -56,4 +53,4 @@ To resolve this issue, you must configure the Image URL proxy allowlist in your 5. Select **Show User SMTP Credentials** to view the user's SMTP credentials. 6. Return to your Plane instance's `/god-mode` and enter the obtained details. -Ensure to review [**email quotas**](https://docs.aws.amazon.com/ses/latest/dg/quotas.html) for your Amazon SES server. Consider managing email recipients using groups to optimize usage. \ No newline at end of file +Ensure to review [**email quotas**](https://docs.aws.amazon.com/ses/latest/dg/quotas.html) for your Amazon SES server. Consider managing email recipients using groups to optimize usage. diff --git a/docs/self-hosting/govern/configure-ssl.md b/docs/self-hosting/govern/configure-ssl.md index e10adad..d215976 100644 --- a/docs/self-hosting/govern/configure-ssl.md +++ b/docs/self-hosting/govern/configure-ssl.md @@ -4,7 +4,6 @@ description: Configure SSL/TLS certificates for Plane. Setup HTTPS encryption fo keywords: plane ssl, https setup, tls certificate, ssl configuration, lets encrypt, secure deployment, self-hosting security --- - # Set up SSL This guide shows you how to configure SSL/TLS certificates for your self-hosted Plane instance. Plane handles certificate provisioning and renewal automatically using Let's Encrypt. @@ -18,6 +17,7 @@ If you're using an external reverse proxy (nginx, Caddy, Traefik) or a load bala ## Before you begin Ensure you have: + - A registered domain name pointing to your Plane server - DNS records configured (A or CNAME record pointing to your server's IP) - Ports 80 and 443 open on your server's firewall @@ -32,6 +32,7 @@ Ensure you have: ### Open the configuration file Edit your Plane environment configuration: + ```bash vim /opt/plane/plane.env ``` @@ -39,6 +40,7 @@ vim /opt/plane/plane.env ### Set required variables Add or update these environment variables: + ```bash # SSL Configuration CERT_EMAIL=admin@yourcompany.com @@ -60,11 +62,13 @@ Your full Plane URL **with** the `https://` protocol. This tells Plane services ### DNS provider configuration (optional) If you're using Cloudflare or another DNS provider with API access, you can use DNS validation instead of HTTP validation. This is useful if: + - Your server is behind a firewall that blocks port 80 - You need wildcard certificates - HTTP validation isn't working due to network restrictions **For Cloudflare:** + ```bash CERT_ACME_DNS=acme_dns cloudflare ``` @@ -78,11 +82,13 @@ Check the [acme.sh DNS API documentation](https://github.com/acmesh-official/acm ## Apply SSL configuration Restart Plane to apply the SSL settings: + ```bash sudo prime-cli restart ``` Prime CLI will: + 1. Stop all Plane services 2. Request a new SSL certificate from Let's Encrypt 3. Configure the built-in proxy to use HTTPS @@ -93,6 +99,7 @@ This process typically takes 30-60 seconds. ## Verify SSL is working Check that your Plane instance is accessible via HTTPS: + ```bash curl -I https://plane.yourcompany.com ``` @@ -101,7 +108,6 @@ You should see a response with `HTTP/2 200` or `HTTP/1.1 200` and SSL-related he Visit your Plane instance in a browser at `https://plane.yourcompany.com`. You should see a secure connection (padlock icon) without certificate warnings. - ## Using custom SSL certificates -Custom SSL certificates (from a corporate CA or purchased certificates) are not currently supported in Plane's deployment. \ No newline at end of file +Custom SSL certificates (from a corporate CA or purchased certificates) are not currently supported in Plane's deployment. diff --git a/docs/self-hosting/govern/database-and-storage.md b/docs/self-hosting/govern/database-and-storage.md index ad901ab..1257d54 100644 --- a/docs/self-hosting/govern/database-and-storage.md +++ b/docs/self-hosting/govern/database-and-storage.md @@ -4,7 +4,6 @@ description: Configure external database and storage for Plane. Setup PostgreSQL keywords: plane external database, postgresql setup, redis configuration, s3 storage, minio, self-hosting, plane storage --- - # Configure external services The Prime CLI lets you easily configure your Commercial Edition instance, providing options to customize the PostgreSQL database, Redis, external storage, and other advanced settings. @@ -13,97 +12,99 @@ The Prime CLI lets you easily configure your Commercial Edition instance, provid **Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. ::: -1. Run the Prime CLI with ↓: - - ```sudo prime-cli``` - -2. Once the CLI is running, enter `configure`, which will guide you through a step-by-step form where you can specify the following: - - - `Listening port` - Define the port for the built-in reverse proxy. - *Default*: `80` - - - `Max file-upload size` - Set the maximum file size (in MB) that members can upload. - *Default*: `5 MB` - - - `External Postgres URL` - Provide the URL of your external PostgreSQL instance if you want to switch from the default Plane configuration. - *Default*: `Postgres 15.5` in the Docker container. - - ::: warning - Don’t use a database on your local machine. If you use `localhost` in the URL, it won’t work. Make sure to use a database hosted on a network-accessible server. - - Avoid using special characters in your PostgreSQL password. - ::: - - - `External Redis URL` - Specify the URL of your external Redis instance to override the default Redis configuration. - *Default*: `Redis 7.2.4` - - - `External storage` - Plane currently supports only S3 compatible storages. - *Default*: `MinIO` - - 1. Ensure your IAM user has the following permissions on your S3 bucket. - - **s3:GetObject** - To access the objects. - - **s3:PutObject** - To upload new assets using the presigned url. - 2. Configure the CORS policy on your bucket to enable presigned uploads. Use the example policy below, making sure to replace `` with your actual domain. - ``` - [ - { - "AllowedHeaders": [ - "*" - ], - "AllowedMethods": [ - "GET", - "POST", - "PUT", - "DELETE", - "HEAD" - ], - "AllowedOrigins": [ - "", - ], - "ExposeHeaders": [ - "ETag", - "x-amz-server-side-encryption", - "x-amz-request-id", - "x-amz-id-2" - ], - "MaxAgeSeconds": 3000 - } - ] - ``` - 3. Switch to your external storage by providing the following values: - - S3 access key ID  - - S3 secret access key - - S3 bucket name - - S3 region  - - S3 endpoint URL - -3. After confirming your choices, your instance will automatically restart with the updated configuration. +1. Run the Prime CLI with ↓: + +`sudo prime-cli` + +2. Once the CLI is running, enter `configure`, which will guide you through a step-by-step form where you can specify the following: + +- `Listening port` + Define the port for the built-in reverse proxy. + _Default_: `80` + +- `Max file-upload size` + Set the maximum file size (in MB) that members can upload. + _Default_: `5 MB` + +- `External Postgres URL` + Provide the URL of your external PostgreSQL instance if you want to switch from the default Plane configuration. + _Default_: `Postgres 15.5` in the Docker container. + +::: warning +Don’t use a database on your local machine. If you use `localhost` in the URL, it won’t work. Make sure to use a database hosted on a network-accessible server. + +Avoid using special characters in your PostgreSQL password. +::: + +- `External Redis URL` + Specify the URL of your external Redis instance to override the default Redis configuration. + _Default_: `Redis 7.2.4` + +- `External storage` + Plane currently supports only S3 compatible storages. + _Default_: `MinIO` + 1. Ensure your IAM user has the following permissions on your S3 bucket. + - **s3:GetObject** + To access the objects. + - **s3:PutObject** + To upload new assets using the presigned url. + 2. Configure the CORS policy on your bucket to enable presigned uploads. Use the example policy below, making sure to replace `` with your actual domain. + + ``` + [ + { + "AllowedHeaders": [ + "*" + ], + "AllowedMethods": [ + "GET", + "POST", + "PUT", + "DELETE", + "HEAD" + ], + "AllowedOrigins": [ + "", + ], + "ExposeHeaders": [ + "ETag", + "x-amz-server-side-encryption", + "x-amz-request-id", + "x-amz-id-2" + ], + "MaxAgeSeconds": 3000 + } + ] + ``` + + 3. Switch to your external storage by providing the following values: + - S3 access key ID  + - S3 secret access key + - S3 bucket name + - S3 region  + - S3 endpoint URL + +3. After confirming your choices, your instance will automatically restart with the updated configuration. ::: details Community Edition To configure external Postgres, Redis, and S3 storage for the Plane Community Edition, you’ll need to adjust several environment variables in the plane.env file. Follow this guide to set up each component using the correct values for your external services. -1. Open the `plane.env` file on your server where Plane is installed. - -2. In the **DB SETTINGS** section, update the variables to connect to your external Postgres instance: - ```bash - # DB SETTINGS - PGHOST=your-external-postgres-host # Replace with the hostname or IP address of your Postgres server. - PGDATABASE= # Leave blank when using external database. - POSTGRES_USER=your-postgres-username # The username to access Postgres. - POSTGRES_PASSWORD=your-postgres-password # Password for the Postgres user. - POSTGRES_DB=your-database-name # The name of the database Plane should connect to. - POSTGRES_PORT=5432 # Port where Postgres is accessible (usually 5432). - PGDATA=/var/lib/postgresql/data # No need to change this for external Postgres. - DATABASE_URL= # Leave this empty if you're providing values for the variables above. If you choose to use the DATABASE_URL, you can leave all the other database-related variables empty. - ``` +1. Open the `plane.env` file on your server where Plane is installed. + +2. In the **DB SETTINGS** section, update the variables to connect to your external Postgres instance: + + ```bash + # DB SETTINGS + PGHOST=your-external-postgres-host # Replace with the hostname or IP address of your Postgres server. + PGDATABASE= # Leave blank when using external database. + POSTGRES_USER=your-postgres-username # The username to access Postgres. + POSTGRES_PASSWORD=your-postgres-password # Password for the Postgres user. + POSTGRES_DB=your-database-name # The name of the database Plane should connect to. + POSTGRES_PORT=5432 # Port where Postgres is accessible (usually 5432). + PGDATA=/var/lib/postgresql/data # No need to change this for external Postgres. + DATABASE_URL= # Leave this empty if you're providing values for the variables above. If you choose to use the DATABASE_URL, you can leave all the other database-related variables empty. + ``` ::: warning Don’t use a database on your local machine. If you use `localhost` in the URL, it won’t work. Make sure to use a database hosted on a network-accessible server. @@ -111,30 +112,31 @@ To configure external Postgres, Redis, and S3 storage for the Plane Community Ed Avoid using special characters in your PostgreSQL password. ::: -3. In the **REDIS SETTINGS** section, update the variables to connect to your external Redis instance: - ```bash - # REDIS SETTINGS - REDIS_HOST=your-external-redis-host # Hostname or IP of the Redis server. - REDIS_PORT=6379 # Port where Redis is accessible (default is 6379). - REDIS_URL= # Leave this empty if you're providing values for the variables above. If you choose to use the REDIS_URL, you can leave all the other redis-related variables empty. - ``` - -4. In the **DATA STORE SETTINGS** section, update the variables for any S3-compatible storage: - ```bash - # DATA STORE SETTINGS - USE_MINIO=0 # Set to 0 if using an external S3, 1 if using MinIO (default). - AWS_REGION=your-s3-region # For AWS, set the region, e.g., "us-west-1". - AWS_ACCESS_KEY_ID=your-s3-access-key # Access key for S3. - AWS_SECRET_ACCESS_KEY=your-s3-secret-key # Secret key for S3. - AWS_S3_ENDPOINT_URL=https://your-s3-endpoint # URL for S3 API endpoint (e.g., "https://s3.amazonaws.com" for AWS). - AWS_S3_BUCKET_NAME=your-s3-bucket-name # Name of the S3 bucket for storing Plane data. - MINIO_ROOT_USER= # Leave blank when using external S3. - MINIO_ROOT_PASSWORD= # Leave blank when using external S3. - BUCKET_NAME= # Leave blank when using external S3. - FILE_SIZE_LIMIT=5242880 # Set maximum file upload size in bytes (5MB here). - ``` -5. Save your changes to the `plane.env` file. - -6. Restart Plane services to apply the new settings using the `setup.sh` script. - -::: \ No newline at end of file +3. In the **REDIS SETTINGS** section, update the variables to connect to your external Redis instance: + + ```bash + # REDIS SETTINGS + REDIS_HOST=your-external-redis-host # Hostname or IP of the Redis server. + REDIS_PORT=6379 # Port where Redis is accessible (default is 6379). + REDIS_URL= # Leave this empty if you're providing values for the variables above. If you choose to use the REDIS_URL, you can leave all the other redis-related variables empty. + ``` + +4. In the **DATA STORE SETTINGS** section, update the variables for any S3-compatible storage: + ```bash + # DATA STORE SETTINGS + USE_MINIO=0 # Set to 0 if using an external S3, 1 if using MinIO (default). + AWS_REGION=your-s3-region # For AWS, set the region, e.g., "us-west-1". + AWS_ACCESS_KEY_ID=your-s3-access-key # Access key for S3. + AWS_SECRET_ACCESS_KEY=your-s3-secret-key # Secret key for S3. + AWS_S3_ENDPOINT_URL=https://your-s3-endpoint # URL for S3 API endpoint (e.g., "https://s3.amazonaws.com" for AWS). + AWS_S3_BUCKET_NAME=your-s3-bucket-name # Name of the S3 bucket for storing Plane data. + MINIO_ROOT_USER= # Leave blank when using external S3. + MINIO_ROOT_PASSWORD= # Leave blank when using external S3. + BUCKET_NAME= # Leave blank when using external S3. + FILE_SIZE_LIMIT=5242880 # Set maximum file upload size in bytes (5MB here). + ``` +5. Save your changes to the `plane.env` file. + +6. Restart Plane services to apply the new settings using the `setup.sh` script. + +::: diff --git a/docs/self-hosting/govern/environment-variables.md b/docs/self-hosting/govern/environment-variables.md index b39445b..132e772 100644 --- a/docs/self-hosting/govern/environment-variables.md +++ b/docs/self-hosting/govern/environment-variables.md @@ -4,7 +4,6 @@ description: Configure environment variables for Plane. Complete reference of al keywords: plane environment variables, configuration reference, env settings, plane config, self-hosting settings, plane env --- - # Environment variables reference This guide provides a comprehensive overview of all environment variables used in the Commercial Edition. These variables allow you to customize your Plane instance to best fit your organization's needs. @@ -12,9 +11,10 @@ This guide provides a comprehensive overview of all environment variables used i ## Where to find the .env file The environment file for Plane Commercial Edition is located at: - ```bash - /opt/plane/plane.env - ``` + +```bash +/opt/plane/plane.env +``` This is where you'll make all configuration changes. Remember to restart the instance after making changes to ensure they take effect. @@ -22,141 +22,141 @@ This is where you'll make all configuration changes. Remember to restart the ins ### General settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **INSTALL_DIR** | Directory where Plane is installed. | `/opt/plane` | -| **DOMAIN_NAME** | Primary domain name for your Plane instance. This determines how users will access your installation. | `localhost` | -| **APP_RELEASE_VERSION** | The version of Plane Commercial Edition you're running. This helps with troubleshooting and ensures compatibility. | *Current release version* | -| **WEB_URL** | The complete base URL for the web application including protocol (e.g., `https://plane.example.com`).|`http://localhost`| -| **CORS_ALLOWED_ORIGINS** | Comma-separated list of origins allowed to make cross-origin requests to your API. Usually, this should include your WEB_URL. |`http://localhost`| -| **DEBUG** | Toggles debug mode for more verbose logging and debugging information.| `0` (disabled) | +| Variable | Description | Default Value | +| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------- | +| **INSTALL_DIR** | Directory where Plane is installed. | `/opt/plane` | +| **DOMAIN_NAME** | Primary domain name for your Plane instance. This determines how users will access your installation. | `localhost` | +| **APP_RELEASE_VERSION** | The version of Plane Commercial Edition you're running. This helps with troubleshooting and ensures compatibility. | _Current release version_ | +| **WEB_URL** | The complete base URL for the web application including protocol (e.g., `https://plane.example.com`). | `http://localhost` | +| **CORS_ALLOWED_ORIGINS** | Comma-separated list of origins allowed to make cross-origin requests to your API. Usually, this should include your WEB_URL. | `http://localhost` | +| **DEBUG** | Toggles debug mode for more verbose logging and debugging information. | `0` (disabled) | ### Scaling and performance -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **WEB_REPLICAS** | Number of web server replicas for load balancing. | `1` | -| **SPACE_REPLICAS** | Number of space service replicas for workspaces. | `1` | -| **ADMIN_REPLICAS** | Number of admin service replicas. | `1` | -| **API_REPLICAS** | Number of API service replicas. | `1` | -| **WORKER_REPLICAS** | Number of worker service replicas for background tasks. | `1` | -| **BEAT_WORKER_REPLICAS** | Number of beat worker replicas for scheduled tasks. | `1` | -| **LIVE_REPLICAS** | Number of live service replicas for real-time updates. | `1` | -| **GUNICORN_WORKERS** | Number of Gunicorn workers for handling web requests. Increase for better performance on high-traffic instances. | `2` | +| Variable | Description | Default Value | +| ------------------------ | ---------------------------------------------------------------------------------------------------------------- | ------------- | +| **WEB_REPLICAS** | Number of web server replicas for load balancing. | `1` | +| **SPACE_REPLICAS** | Number of space service replicas for workspaces. | `1` | +| **ADMIN_REPLICAS** | Number of admin service replicas. | `1` | +| **API_REPLICAS** | Number of API service replicas. | `1` | +| **WORKER_REPLICAS** | Number of worker service replicas for background tasks. | `1` | +| **BEAT_WORKER_REPLICAS** | Number of beat worker replicas for scheduled tasks. | `1` | +| **LIVE_REPLICAS** | Number of live service replicas for real-time updates. | `1` | +| **GUNICORN_WORKERS** | Number of Gunicorn workers for handling web requests. Increase for better performance on high-traffic instances. | `2` | ### Networking and security -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **LISTEN_HTTP_PORT** | Port for HTTP traffic. | `80` | -| **LISTEN_HTTPS_PORT** | Port for HTTPS traffic. | `443` | -| **APP_PROTOCOL** | Protocol to be used, either `http` or `https`. | `http` | -| **TRUSTED_PROXIES** | CIDR notation of trusted proxies for request forwarding. Important when behind load balancers or reverse proxies. | `0.0.0.0/0` | -| **SSL_VERIFY** | Whether to verify SSL certificates for outgoing connections. Set to `0` only in development environments. | `1` | +| Variable | Description | Default Value | +| --------------------- | ----------------------------------------------------------------------------------------------------------------- | ------------- | +| **LISTEN_HTTP_PORT** | Port for HTTP traffic. | `80` | +| **LISTEN_HTTPS_PORT** | Port for HTTPS traffic. | `443` | +| **APP_PROTOCOL** | Protocol to be used, either `http` or `https`. | `http` | +| **TRUSTED_PROXIES** | CIDR notation of trusted proxies for request forwarding. Important when behind load balancers or reverse proxies. | `0.0.0.0/0` | +| **SSL_VERIFY** | Whether to verify SSL certificates for outgoing connections. Set to `0` only in development environments. | `1` | ### SSL and certificates -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **CERT_EMAIL** | Email used for SSL certificate registration with Let's Encrypt or other ACME providers. |`admin@example.com`| -| **CERT_ACME_CA** | ACME Certificate Authority URL for SSL certificate issuance. | `https://acme-v02.api.letsencrypt.org/directory` | -| **CERT_ACME_DNS** | DNS provider configuration for SSL certificate domain validation. Format varies by provider. | | -| **SITE_ADDRES** | The domain name and port required by Caddy for serving your Plane instance. This determines how Caddy will handle incoming requests. | `localhost:80` | +| Variable | Description | Default Value | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ | +| **CERT_EMAIL** | Email used for SSL certificate registration with Let's Encrypt or other ACME providers. | `admin@example.com` | +| **CERT_ACME_CA** | ACME Certificate Authority URL for SSL certificate issuance. | `https://acme-v02.api.letsencrypt.org/directory` | +| **CERT_ACME_DNS** | DNS provider configuration for SSL certificate domain validation. Format varies by provider. | | +| **SITE_ADDRES** | The domain name and port required by Caddy for serving your Plane instance. This determines how Caddy will handle incoming requests. | `localhost:80` | ### Database settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **PGHOST** | Hostname or IP address of your PostgreSQL server. | `plane-db` | -| **PGDATABASE** | Name of the PostgreSQL database Plane will use. | `plane` | -| **POSTGRES_USER** | Username for PostgreSQL authentication. | `plane` | -| **POSTGRES_PASSWORD** | Password for PostgreSQL authentication. **Critical:** Use a strong, unique password here. |`plane`| -| **POSTGRES_DB** | Same as PGDATABASE - the name of the PostgreSQL database. | `plane` | -| **POSTGRES_PORT** | TCP port your PostgreSQL server is listening on. | `5432` | -| **PGDATA** | Directory path where PostgreSQL data is stored. Only relevant if you're managing PostgreSQL within the same container/system. | `/var/lib/postgresql/data` | -| **DATABASE_URL** | Full connection string for PostgreSQL. If provided, this takes precedence over individual connection parameters. Format: `postgresql://username:password@host:port/dbname` | | +| Variable | Description | Default Value | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| **PGHOST** | Hostname or IP address of your PostgreSQL server. | `plane-db` | +| **PGDATABASE** | Name of the PostgreSQL database Plane will use. | `plane` | +| **POSTGRES_USER** | Username for PostgreSQL authentication. | `plane` | +| **POSTGRES_PASSWORD** | Password for PostgreSQL authentication. **Critical:** Use a strong, unique password here. | `plane` | +| **POSTGRES_DB** | Same as PGDATABASE - the name of the PostgreSQL database. | `plane` | +| **POSTGRES_PORT** | TCP port your PostgreSQL server is listening on. | `5432` | +| **PGDATA** | Directory path where PostgreSQL data is stored. Only relevant if you're managing PostgreSQL within the same container/system. | `/var/lib/postgresql/data` | +| **DATABASE_URL** | Full connection string for PostgreSQL. If provided, this takes precedence over individual connection parameters. Format: `postgresql://username:password@host:port/dbname` | | ### Redis settings -| Variable | Description | Default Value | -|----------|-------------|---------------| +| Variable | Description | Default Value | +| -------------- | -------------------------------------------- | ------------- | | **REDIS_HOST** | Hostname or IP address of your Redis server. | `plane-redis` | -| **REDIS_PORT** | TCP port your Redis server is listening on. | `6379` | -| **REDIS_URL** | Full connection string for Redis.| | +| **REDIS_PORT** | TCP port your Redis server is listening on. | `6379` | +| **REDIS_URL** | Full connection string for Redis. | | ### RabbitMQ settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **RABBITMQ_HOST** | Hostname or IP address of your RabbitMQ server. | `plane-mq` | -| **RABBITMQ_PORT** | TCP port your RabbitMQ server is listening on. | `5672` | -| **RABBITMQ_DEFAULT_USER** | Username for RabbitMQ authentication. | `plane` | -| **RABBITMQ_DEFAULT_PASS** | Password for RabbitMQ authentication. | `plane` | -| **RABBITMQ_DEFAULT_VHOST** | Virtual host for RabbitMQ, providing logical separation of resources. | `plane` | -| **AMQP_URL** | Full connection string for RabbitMQ. Format: `amqp://username:password@host:port/vhost` | | +| Variable | Description | Default Value | +| -------------------------- | --------------------------------------------------------------------------------------- | ------------- | +| **RABBITMQ_HOST** | Hostname or IP address of your RabbitMQ server. | `plane-mq` | +| **RABBITMQ_PORT** | TCP port your RabbitMQ server is listening on. | `5672` | +| **RABBITMQ_DEFAULT_USER** | Username for RabbitMQ authentication. | `plane` | +| **RABBITMQ_DEFAULT_PASS** | Password for RabbitMQ authentication. | `plane` | +| **RABBITMQ_DEFAULT_VHOST** | Virtual host for RabbitMQ, providing logical separation of resources. | `plane` | +| **AMQP_URL** | Full connection string for RabbitMQ. Format: `amqp://username:password@host:port/vhost` | | ### Authentication and security -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **SECRET_KEY** | Secret key used for various cryptographic operations, including JWT token signing. | | -| **MACHINE_SIGNATURE** | Unique identifier for your instance, used for licensing and authentication.| | + +| Variable | Description | Default Value | +| --------------------- | ---------------------------------------------------------------------------------- | ------------- | +| **SECRET_KEY** | Secret key used for various cryptographic operations, including JWT token signing. | | +| **MACHINE_SIGNATURE** | Unique identifier for your instance, used for licensing and authentication. | | ### File Storage (MinIO / S3) -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **USE_MINIO** | Determines whether to use MinIO for object storage. Set to `1` to enable MinIO, `0` to use configured S3 or local storage. | `1` | -| **AWS_REGION** | AWS region for S3 storage services. | | -| **AWS_ACCESS_KEY_ID** | Access key for MinIO or AWS S3 authentication. | | -| **AWS_SECRET_ACCESS_KEY** | Secret key for MinIO or AWS S3 authentication. | | -| **AWS_S3_ENDPOINT_URL** | Custom endpoint URL for MinIO or S3-compatible storage. | `http://plane-minio:9000`| -| **AWS_S3_BUCKET_NAME** | S3 bucket name for file storage. | `uploads` | -| **MINIO_ROOT_USER** | Username for MinIO authentication. This is effectively your MinIO admin account. | `access-key` | -| **MINIO_ROOT_PASSWORD** | Password for MinIO root user authentication. Keep this secure as it provides full access to your storage. | `secret-key` | -| **BUCKET_NAME** | S3 bucket name where all file uploads will be stored. This bucket will be automatically created if it doesn't exist. | `uploads` | -| **FILE_SIZE_LIMIT** | Maximum file upload size in bytes. | `5242880` (5MB) | -| **MINIO_ENDPOINT_SSL** | Force HTTPS for MinIO when dealing with SSL termination. Set to `1` to enable. | `0` | +| Variable | Description | Default Value | +| ------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ------------------------- | +| **USE_MINIO** | Determines whether to use MinIO for object storage. Set to `1` to enable MinIO, `0` to use configured S3 or local storage. | `1` | +| **AWS_REGION** | AWS region for S3 storage services. | | +| **AWS_ACCESS_KEY_ID** | Access key for MinIO or AWS S3 authentication. | | +| **AWS_SECRET_ACCESS_KEY** | Secret key for MinIO or AWS S3 authentication. | | +| **AWS_S3_ENDPOINT_URL** | Custom endpoint URL for MinIO or S3-compatible storage. | `http://plane-minio:9000` | +| **AWS_S3_BUCKET_NAME** | S3 bucket name for file storage. | `uploads` | +| **MINIO_ROOT_USER** | Username for MinIO authentication. This is effectively your MinIO admin account. | `access-key` | +| **MINIO_ROOT_PASSWORD** | Password for MinIO root user authentication. Keep this secure as it provides full access to your storage. | `secret-key` | +| **BUCKET_NAME** | S3 bucket name where all file uploads will be stored. This bucket will be automatically created if it doesn't exist. | `uploads` | +| **FILE_SIZE_LIMIT** | Maximum file upload size in bytes. | `5242880` (5MB) | +| **MINIO_ENDPOINT_SSL** | Force HTTPS for MinIO when dealing with SSL termination. Set to `1` to enable. | `0` | ### GitHub integration -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **GITHUB_CLIENT_ID** | OAuth client ID for GitHub integration. | | -| **GITHUB_CLIENT_SECRET** | OAuth client secret for GitHub integration. | | -| **GITHUB_APP_NAME** | GitHub App name for enhanced GitHub integration. | | -| **GITHUB_APP_ID** | GitHub App ID for enhanced GitHub integration. | | -| **GITHUB_PRIVATE_KEY** | Private key for GitHub App authentication. | | +| Variable | Description | Default Value | +| ------------------------ | ------------------------------------------------ | ------------- | +| **GITHUB_CLIENT_ID** | OAuth client ID for GitHub integration. | | +| **GITHUB_CLIENT_SECRET** | OAuth client secret for GitHub integration. | | +| **GITHUB_APP_NAME** | GitHub App name for enhanced GitHub integration. | | +| **GITHUB_APP_ID** | GitHub App ID for enhanced GitHub integration. | | +| **GITHUB_PRIVATE_KEY** | Private key for GitHub App authentication. | | ### Slack integration -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **SLACK_CLIENT_ID** | OAuth client ID for Slack integration. | | -| **SLACK_CLIENT_SECRET** | OAuth client secret for Slack integration. | | +| Variable | Description | Default Value | +| ----------------------- | ------------------------------------------ | ------------- | +| **SLACK_CLIENT_ID** | OAuth client ID for Slack integration. | | +| **SLACK_CLIENT_SECRET** | OAuth client secret for Slack integration. | | ### GitLab integration -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **GITLAB_CLIENT_ID** | OAuth client ID for GitLab integration. | | -| **GITLAB_CLIENT_SECRET** | OAuth client secret for GitLab integration. | | +| Variable | Description | Default Value | +| ------------------------ | ------------------------------------------- | ------------- | +| **GITLAB_CLIENT_ID** | OAuth client ID for GitLab integration. | | +| **GITLAB_CLIENT_SECRET** | OAuth client secret for GitLab integration. | | ### OpenSearch -| Variable | Description | Default Value | -|----------|-------------|---------| -| `OPENSEARCH_ENABLED` | Enable OpenSearch integration | `1` | -| `OPENSEARCH_URL` | OpenSearch endpoint URL | `https://opensearch.example.com:9200/` | -| `OPENSEARCH_USERNAME` | Authentication username | `admin` | -| `OPENSEARCH_PASSWORD` | Authentication password | `your-secure-password` | -| `OPENSEARCH_INDEX_PREFIX` | Prefix for all index names (useful for multi-tenant setups) | (empty) | +| Variable | Description | Default Value | +| ------------------------- | ----------------------------------------------------------- | -------------------------------------- | +| `OPENSEARCH_ENABLED` | Enable OpenSearch integration | `1` | +| `OPENSEARCH_URL` | OpenSearch endpoint URL | `https://opensearch.example.com:9200/` | +| `OPENSEARCH_USERNAME` | Authentication username | `admin` | +| `OPENSEARCH_PASSWORD` | Authentication password | `your-secure-password` | +| `OPENSEARCH_INDEX_PREFIX` | Prefix for all index names (useful for multi-tenant setups) | (empty) | ### API settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **API_KEY_RATE_LIMIT** | Rate limit for API requests to prevent abuse. Format: `number/timeunit` | `60/minute` | - +| Variable | Description | Default Value | +| ---------------------- | ----------------------------------------------------------------------- | ------------- | +| **API_KEY_RATE_LIMIT** | Rate limit for API requests to prevent abuse. Format: `number/timeunit` | `60/minute` | ::: details Community Edition @@ -165,93 +165,93 @@ This guide provides a comprehensive overview of all environment variables availa ## Where to find the environment file The environment configuration file is located at: - ```bash - plane-selfhost/plane-app/plane.env - ``` + +```bash +plane-selfhost/plane-app/plane.env +``` ## Environment Variables ### General settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **APP_DOMAIN** | Domain name for your Plane instance. This determines how users will access your installation. | `localhost` | -| **APP_RELEASE** | Release version of Plane. Helps with compatibility and troubleshooting. | `stable` | -| **WEB_URL** | The complete base URL for the web application including protocol. Essential for email links and integrations. | `http://${APP_DOMAIN}` | -| **CORS_ALLOWED_ORIGINS** | Comma-separated list of origins allowed to make cross-origin requests to your API. | `http://${APP_DOMAIN}` | -| **DEBUG** | Toggles debug mode for verbose logging. Set to `1` to enable, `0` to disable. Not recommended in production as it may expose sensitive information. | `0` | -| **LISTEN_HTTP_PORT** | Port for HTTP traffic. The primary port your users will connect to. | `80` | -| **LISTEN_HTTPS_PORT** | Port for HTTPS traffic. The primary port your users will connect to. | `443` | +| Variable | Description | Default Value | +| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------- | +| **APP_DOMAIN** | Domain name for your Plane instance. This determines how users will access your installation. | `localhost` | +| **APP_RELEASE** | Release version of Plane. Helps with compatibility and troubleshooting. | `stable` | +| **WEB_URL** | The complete base URL for the web application including protocol. Essential for email links and integrations. | `http://${APP_DOMAIN}` | +| **CORS_ALLOWED_ORIGINS** | Comma-separated list of origins allowed to make cross-origin requests to your API. | `http://${APP_DOMAIN}` | +| **DEBUG** | Toggles debug mode for verbose logging. Set to `1` to enable, `0` to disable. Not recommended in production as it may expose sensitive information. | `0` | +| **LISTEN_HTTP_PORT** | Port for HTTP traffic. The primary port your users will connect to. | `80` | +| **LISTEN_HTTPS_PORT** | Port for HTTPS traffic. The primary port your users will connect to. | `443` | ### Scaling and performance -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **WEB_REPLICAS** | Number of web server replicas for serving the frontend UI. Increase for better load distribution. | `1` | -| **SPACE_REPLICAS** | Number of space service replicas handling workspace-related operations. | `1` | -| **ADMIN_REPLICAS** | Number of admin service replicas for administrative functions. | `1` | -| **API_REPLICAS** | Number of API service replicas processing API requests. | `1` | -| **WORKER_REPLICAS** | Number of worker service replicas handling background tasks. | `1` | -| **BEAT_WORKER_REPLICAS** | Number of beat worker replicas for scheduled/periodic tasks. | `1` | -| **LIVE_REPLICAS** | Number of live service replicas for real-time updates and WebSocket connections. | `1` | -| **GUNICORN_WORKERS** | Number of Gunicorn workers per API instance. Increase for better request handling capacity. | `1` | +| Variable | Description | Default Value | +| ------------------------ | ------------------------------------------------------------------------------------------------- | ------------- | +| **WEB_REPLICAS** | Number of web server replicas for serving the frontend UI. Increase for better load distribution. | `1` | +| **SPACE_REPLICAS** | Number of space service replicas handling workspace-related operations. | `1` | +| **ADMIN_REPLICAS** | Number of admin service replicas for administrative functions. | `1` | +| **API_REPLICAS** | Number of API service replicas processing API requests. | `1` | +| **WORKER_REPLICAS** | Number of worker service replicas handling background tasks. | `1` | +| **BEAT_WORKER_REPLICAS** | Number of beat worker replicas for scheduled/periodic tasks. | `1` | +| **LIVE_REPLICAS** | Number of live service replicas for real-time updates and WebSocket connections. | `1` | +| **GUNICORN_WORKERS** | Number of Gunicorn workers per API instance. Increase for better request handling capacity. | `1` | ### API settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **API_KEY_RATE_LIMIT** | Rate limit for API requests to prevent abuse. Format: `number/timeunit` | `60/minute` | +| Variable | Description | Default Value | +| ---------------------- | ----------------------------------------------------------------------- | ------------- | +| **API_KEY_RATE_LIMIT** | Rate limit for API requests to prevent abuse. Format: `number/timeunit` | `60/minute` | ### Database settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **PGHOST** | Hostname or IP address of your PostgreSQL server. | `plane-db` | -| **PGDATABASE** | Name of the PostgreSQL database Plane will use. | `plane` | -| **POSTGRES_USER** | Username for PostgreSQL authentication. | `plane` | -| **POSTGRES_PASSWORD** | Password for PostgreSQL authentication. Use a strong, unique password. | `plane` | -| **POSTGRES_DB** | Same as PGDATABASE - the name of the PostgreSQL database. | `plane` | -| **POSTGRES_PORT** | TCP port your PostgreSQL server is listening on. | `5432` | -| **PGDATA** | Directory path where PostgreSQL data is stored. Only relevant if you're managing PostgreSQL directly. | `/var/lib/postgresql/data` | -| **DATABASE_URL** | Full connection string for PostgreSQL. If provided, overrides individual settings. Format: `postgresql://username:password@host:port/dbname` | | +| Variable | Description | Default Value | +| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | +| **PGHOST** | Hostname or IP address of your PostgreSQL server. | `plane-db` | +| **PGDATABASE** | Name of the PostgreSQL database Plane will use. | `plane` | +| **POSTGRES_USER** | Username for PostgreSQL authentication. | `plane` | +| **POSTGRES_PASSWORD** | Password for PostgreSQL authentication. Use a strong, unique password. | `plane` | +| **POSTGRES_DB** | Same as PGDATABASE - the name of the PostgreSQL database. | `plane` | +| **POSTGRES_PORT** | TCP port your PostgreSQL server is listening on. | `5432` | +| **PGDATA** | Directory path where PostgreSQL data is stored. Only relevant if you're managing PostgreSQL directly. | `/var/lib/postgresql/data` | +| **DATABASE_URL** | Full connection string for PostgreSQL. If provided, overrides individual settings. Format: `postgresql://username:password@host:port/dbname` | | ### Redis settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **REDIS_HOST** | Hostname or IP address of your Redis server. | `plane-redis` | -| **REDIS_PORT** | TCP port your Redis server is listening on. | `6379` | -| **REDIS_URL** | Full connection string for Redis. Format: `redis://username:password@host:port` | | +| Variable | Description | Default Value | +| -------------- | ------------------------------------------------------------------------------- | ------------- | +| **REDIS_HOST** | Hostname or IP address of your Redis server. | `plane-redis` | +| **REDIS_PORT** | TCP port your Redis server is listening on. | `6379` | +| **REDIS_URL** | Full connection string for Redis. Format: `redis://username:password@host:port` | | ### RabbitMQ settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **RABBITMQ_HOST** | Hostname or IP address of your RabbitMQ server. | `plane-mq` | -| **RABBITMQ_PORT** | TCP port your RabbitMQ server is listening on. | `5672` | -| **RABBITMQ_USER** | Username for RabbitMQ authentication. | `plane` | -| **RABBITMQ_PASSWORD** | Password for RabbitMQ authentication. Use a strong, unique password. | `plane` | -| **RABBITMQ_VHOST** | Virtual host for RabbitMQ, providing logical separation of resources. | `plane` | -| **AMQP_URL** | Full connection string for RabbitMQ. If not provided, it's constructed from individual settings. | `amqp://plane:plane@plane-mq:5672/plane` | +| Variable | Description | Default Value | +| --------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------- | +| **RABBITMQ_HOST** | Hostname or IP address of your RabbitMQ server. | `plane-mq` | +| **RABBITMQ_PORT** | TCP port your RabbitMQ server is listening on. | `5672` | +| **RABBITMQ_USER** | Username for RabbitMQ authentication. | `plane` | +| **RABBITMQ_PASSWORD** | Password for RabbitMQ authentication. Use a strong, unique password. | `plane` | +| **RABBITMQ_VHOST** | Virtual host for RabbitMQ, providing logical separation of resources. | `plane` | +| **AMQP_URL** | Full connection string for RabbitMQ. If not provided, it's constructed from individual settings. | `amqp://plane:plane@plane-mq:5672/plane` | ### File Storage (MinIO / S3) -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **USE_MINIO** | Whether to use MinIO for object storage. Set to `1` to enable, `0` to use other configured storage. | `1` | -| **MINIO_ENDPOINT_SSL** | Force HTTPS for MinIO when handling SSL termination. Set to `1` to enable. | `0` | -| **AWS_REGION** | AWS region for S3 storage services. Applies when using S3 or MinIO. | | -| **AWS_ACCESS_KEY_ID** | Access key for MinIO or AWS S3 authentication. | `access-key` | -| **AWS_SECRET_ACCESS_KEY** | Secret key for MinIO or AWS S3 authentication. | `secret-key` | -| **AWS_S3_ENDPOINT_URL** | Endpoint URL for MinIO or S3-compatible storage. | | -| **AWS_S3_BUCKET_NAME** | S3 bucket name for file storage. All uploads will be stored in this bucket. | `uploads` | -| **FILE_SIZE_LIMIT** | Maximum file upload size in bytes. | `5242880` (5MB) | - +| Variable | Description | Default Value | +| ------------------------- | --------------------------------------------------------------------------------------------------- | --------------- | +| **USE_MINIO** | Whether to use MinIO for object storage. Set to `1` to enable, `0` to use other configured storage. | `1` | +| **MINIO_ENDPOINT_SSL** | Force HTTPS for MinIO when handling SSL termination. Set to `1` to enable. | `0` | +| **AWS_REGION** | AWS region for S3 storage services. Applies when using S3 or MinIO. | | +| **AWS_ACCESS_KEY_ID** | Access key for MinIO or AWS S3 authentication. | `access-key` | +| **AWS_SECRET_ACCESS_KEY** | Secret key for MinIO or AWS S3 authentication. | `secret-key` | +| **AWS_S3_ENDPOINT_URL** | Endpoint URL for MinIO or S3-compatible storage. | | +| **AWS_S3_BUCKET_NAME** | S3 bucket name for file storage. All uploads will be stored in this bucket. | `uploads` | +| **FILE_SIZE_LIMIT** | Maximum file upload size in bytes. | `5242880` (5MB) | ### Security settings -| Variable | Description | Default Value | -|----------|-------------|---------------| -| **SECRET_KEY** | Secret key used for cryptographic operations like session handling and token generation. Should be a long, random string. | | +| Variable | Description | Default Value | +| -------------- | ------------------------------------------------------------------------------------------------------------------------- | ------------- | +| **SECRET_KEY** | Secret key used for cryptographic operations like session handling and token generation. Should be a long, random string. | | -::: \ No newline at end of file +::: diff --git a/docs/self-hosting/govern/external-secrets.md b/docs/self-hosting/govern/external-secrets.md index 7c997d5..fdea889 100644 --- a/docs/self-hosting/govern/external-secrets.md +++ b/docs/self-hosting/govern/external-secrets.md @@ -4,7 +4,6 @@ description: Use external secrets operators with Plane on Kubernetes. Integrate keywords: plane external secrets, kubernetes secrets, vault integration, aws secrets manager, secret management, self-hosting --- - # Configure external secrets for Kubernetes deployments This guide explains how to integrate Plane with external secret management solutions, enabling secure and centralized management of sensitive configuration data. The examples provided cover AWS Secrets Manager and HashiCorp Vault integrations, but you can adapt these patterns to your preferred secret management solution. @@ -17,87 +16,89 @@ This guide explains how to integrate Plane with external secret management solut 4. Create IAM policy (e.g., `external-secret-access-policy`) with the following JSON: - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Action": [ - "secretsmanager:GetResourcePolicy", - "secretsmanager:GetSecretValue", - "secretsmanager:DescribeSecret", - "secretsmanager:ListSecretVersionIds" - ], - "Resource": [ - "arn:aws:secretsmanager:::secret:*" - ] - } - ] - } - ``` - Replace `` and `` with your AWS region and account ID. + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "secretsmanager:GetResourcePolicy", + "secretsmanager:GetSecretValue", + "secretsmanager:DescribeSecret", + "secretsmanager:ListSecretVersionIds" + ], + "Resource": ["arn:aws:secretsmanager:::secret:*"] + } + ] + } + ``` + + Replace `` and `` with your AWS region and account ID. 5. Create IAM role (e.g., external-secret-access-role) with the following trust relationship: - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "AWS": "" - }, - "Action": "sts:AssumeRole" - } - ] - } - ``` - - Replace `` with the ARN of the user created in step 1. + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": "" + }, + "Action": "sts:AssumeRole" + } + ] + } + ``` + + Replace `` with the ARN of the user created in step 1. 6. Attach the AWS IAM policy created in step 4 to the IAM role. -7. Create secrets in AWS Secrets Manager with your Plane configuration values. For example, store RabbitMQ credentials with a name like `prod/secrets/rabbitmq`. +7. Create secrets in AWS Secrets Manager with your Plane configuration values. For example, store RabbitMQ credentials with a name like `prod/secrets/rabbitmq`. - |Key|Value| - |-------|--------| - |RABBITMQ_DEFAULT_USER|plane| - |RABBITMQ_DEFAULT_PASS|plane123| + | Key | Value | + | --------------------- | -------- | + | RABBITMQ_DEFAULT_USER | plane | + | RABBITMQ_DEFAULT_PASS | plane123 | - Follow this pattern to manage all the [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in AWS Secrets Manager. + Follow this pattern to manage all the [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in AWS Secrets Manager. 8. Create a Kubernetes secret containing AWS credentials in your application namespace: - ```sh - kubectl create secret generic aws-creds-secret \ - --from-literal=access-key= \ - --from-literal=secret-access-key= \ - -n - ``` + + ```sh + kubectl create secret generic aws-creds-secret \ + --from-literal=access-key= \ + --from-literal=secret-access-key= \ + -n + ``` 9. Apply the following YAML to create a ClusterSecretStore resource: - ```yaml - apiVersion: external-secrets.io/v1 - kind: ClusterSecretStore - metadata: - name: cluster-aws-secretsmanager - namespace: - spec: - provider: - aws: - service: SecretsManager - role: arn:aws:iam:::role/ - region: eu-west-1 - auth: - accessKeyIDSecretRef: - name: aws-creds-secret - key: access-key - secretAccessKeySecretRef: - name: aws-creds-secret - key: secret-access-key - ``` - Replace `` and `` with your AWS account ID and the role name created in Step 5. + + ```yaml + apiVersion: external-secrets.io/v1 + kind: ClusterSecretStore + metadata: + name: cluster-aws-secretsmanager + namespace: + spec: + provider: + aws: + service: SecretsManager + role: arn:aws:iam:::role/ + region: eu-west-1 + auth: + accessKeyIDSecretRef: + name: aws-creds-secret + key: access-key + secretAccessKeySecretRef: + name: aws-creds-secret + key: secret-access-key + ``` + + Replace `` and `` with your AWS account ID and the role name created in Step 5. 10. Create an ExternalSecret resource to fetch secrets from AWS and create a corresponding Kubernetes secret: ```yaml @@ -115,13 +116,13 @@ This guide explains how to integrate Plane with external secret management solut name: rabbitmq-secret # Target Kubernetes secret name creationPolicy: Owner data: - - secretKey: RABBITMQ_DEFAULT_USER - remoteRef: - key: prod/secrets/rabbitmq - property: RABBITMQ_DEFAULT_USER - - secretKey: RABBITMQ_DEFAULT_PASS - remoteRef: - key: prod/secrets/rabbitmq + - secretKey: RABBITMQ_DEFAULT_USER + remoteRef: + key: prod/secrets/rabbitmq + property: RABBITMQ_DEFAULT_USER + - secretKey: RABBITMQ_DEFAULT_PASS + remoteRef: + key: prod/secrets/rabbitmq ``` Make sure to set all [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in the AWS Secrets Manager, and then access them via ExternalSecret resources in your Kubernetes cluster. @@ -134,62 +135,64 @@ Make sure to set all [environment variables](/self-hosting/methods/kubernetes#ex 3. Create a secret with your Plane configuration values (e.g., `secrets/rabbitmq_secrets`). For this example, we're setting up RabbitMQ credentials: - |Key|Value| - |-------|--------| - |RABBITMQ_DEFAULT_USER|plane| - |RABBITMQ_DEFAULT_PASS|plane123| + | Key | Value | + | --------------------- | -------- | + | RABBITMQ_DEFAULT_USER | plane | + | RABBITMQ_DEFAULT_PASS | plane123 | - Follow this pattern to manage all the other [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in the Vault. + Follow this pattern to manage all the other [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in the Vault. 4. Create a Kubernetes secret containing your Vault token in your application namespace: - ```sh - kubectl create secret generic vault-token -n --from-literal=token= - ``` + + ```sh + kubectl create secret generic vault-token -n --from-literal=token= + ``` 5. Apply the following YAML to create a ClusterSecretStore resource: - ```yaml - apiVersion: external-secrets.io/v1 - kind: ClusterSecretStore - metadata: - name: vault-backend - namespace: - spec: - provider: - vault: - server: "https://" # the address of your vault instance - path: "secrets" # path for accessing the secrets - version: "v2" # Vault API version - auth: - tokenSecretRef: - name: "vault-token" # Use a k8s secret called vault-token - key: "token" # Use this key to access the vault token - ``` - Replace `` with your Vault server address. + ```yaml + apiVersion: external-secrets.io/v1 + kind: ClusterSecretStore + metadata: + name: vault-backend + namespace: + spec: + provider: + vault: + server: "https://" # the address of your vault instance + path: "secrets" # path for accessing the secrets + version: "v2" # Vault API version + auth: + tokenSecretRef: + name: "vault-token" # Use a k8s secret called vault-token + key: "token" # Use this key to access the vault token + ``` + + Replace `` with your Vault server address. 6. Create an ExternalSecret resource to fetch secrets from Vault and create a corresponding Kubernetes secret: - ```yaml - apiVersion: external-secrets.io/v1 - kind: ExternalSecret - metadata: - name: rabbitmq-external-secrets - namespace: # application-namespace - spec: - refreshInterval: "1m" - secretStoreRef: - name: vault-backend # ClusterSecretStore name - kind: ClusterSecretStore - target: - name: rabbitmq-secret # Target Kubernetes secret name - creationPolicy: Owner - data: - - secretKey: RABBITMQ_DEFAULT_USER - remoteRef: - key: secrets/data/rabbitmq_secrets - property: RABBITMQ_DEFAULT_USER - - secretKey: RABBITMQ_DEFAULT_PASS - remoteRef: - key: secrets/data/rabbitmq_secrets - ``` - -Follow this pattern to manage all the environment variables in the Vault, then access them via ExternalSecret resources in your Kubernetes cluster. \ No newline at end of file + ```yaml + apiVersion: external-secrets.io/v1 + kind: ExternalSecret + metadata: + name: rabbitmq-external-secrets + namespace: # application-namespace + spec: + refreshInterval: "1m" + secretStoreRef: + name: vault-backend # ClusterSecretStore name + kind: ClusterSecretStore + target: + name: rabbitmq-secret # Target Kubernetes secret name + creationPolicy: Owner + data: + - secretKey: RABBITMQ_DEFAULT_USER + remoteRef: + key: secrets/data/rabbitmq_secrets + property: RABBITMQ_DEFAULT_USER + - secretKey: RABBITMQ_DEFAULT_PASS + remoteRef: + key: secrets/data/rabbitmq_secrets + ``` + +Follow this pattern to manage all the environment variables in the Vault, then access them via ExternalSecret resources in your Kubernetes cluster. diff --git a/docs/self-hosting/govern/github-oauth.md b/docs/self-hosting/govern/github-oauth.md index 5617c21..16eebdf 100644 --- a/docs/self-hosting/govern/github-oauth.md +++ b/docs/self-hosting/govern/github-oauth.md @@ -4,7 +4,6 @@ description: Configure GitHub OAuth authentication for Plane. Enable GitHub sign keywords: plane github oauth, github sign-in, github authentication, github login, oauth provider, self-hosting, plane sso --- - # Github OAuth Plane supports GitHub OAuth so your users can sign-in with GitHub instead. @@ -33,4 +32,4 @@ Plane supports GitHub OAuth so your users can sign-in with GitHub instead. 2. Add the client ID + the client secret from the GitHub app you just registered. 3. Click `Save `. -Your Plane instance should now work with GitHub sign-in. \ No newline at end of file +Your Plane instance should now work with GitHub sign-in. diff --git a/docs/self-hosting/govern/google-oauth.md b/docs/self-hosting/govern/google-oauth.md index 9528cde..92f486f 100644 --- a/docs/self-hosting/govern/google-oauth.md +++ b/docs/self-hosting/govern/google-oauth.md @@ -4,7 +4,6 @@ description: Setup Google OAuth authentication for Plane. Step-by-step guide to keywords: plane google oauth, google sign-in, google authentication, google login, oauth provider, self-hosting, plane sso --- - # Google OAuth Plane already ships with out-of-the-box support for Google OAuth. This is the easiest option to configure for Google Workspace users. @@ -27,9 +26,10 @@ First, you will need to identify Plane as an approved OAuth app to Google. Append the path that users should be redirected to after they have authenticated with Google. `https:///auth/google/callback` and `https:///auth/mobile/google/callback/` where `` is your self-hosted instance's domain. 3. Click **Create**. 4. Get the Client ID and Client secret under **OAuth 2.0 Client IDs** on the **Credentials** screen. - ![](/images/authentication/google/google-auth-4.png) + ![](/images/authentication/google/google-auth-4.png) ## Configure Plane + ![Google Oauth Configuration](/images/custom-sso/google-oauth.png) 1. Go to `Google` on the Authentication screen of `/god mode`. @@ -38,5 +38,6 @@ First, you will need to identify Plane as an approved OAuth app to Google. Your Plane instance should now work with `Sign in with Google`. - -::: infoWe don't restrict domains in with Google OAuth yet. It's on our roadmap.::: \ No newline at end of file +::: info +We don't restrict domains in with Google OAuth yet. It's on our roadmap. +::: diff --git a/docs/self-hosting/govern/instance-admin.md b/docs/self-hosting/govern/instance-admin.md index 8ae8f07..e81a7ae 100644 --- a/docs/self-hosting/govern/instance-admin.md +++ b/docs/self-hosting/govern/instance-admin.md @@ -4,7 +4,6 @@ description: Configure Plane instance admin settings. Learn about God mode and a keywords: plane instance admin, god mode, admin panel, plane administration, instance settings, self-hosting admin --- - # Instance admin and God mode An instance is a single self-managed installation of Plane on a private cloud or server that the `Instance admin` controls and administers. A single instance can house multiple workspaces. @@ -24,53 +23,57 @@ New instances allow skipping going to God Mode and setting up your workspace ins God Mode features a few screens as shown below. -### General +### General + The General settings page allows you to view or configure core instance details and telemetry preferences. Here’s what you can manage: - **Name of instance** -Customize the name of your instance. + Customize the name of your instance. - **Email** -Displays the instance admin email address. + Displays the instance admin email address. - **Instance ID** -Displays a unique identifier for your instance. + Displays a unique identifier for your instance. - **Chat with us** -Enable or disable in-app chat support for users. Disabling telemetry automatically turns this off. + Enable or disable in-app chat support for users. Disabling telemetry automatically turns this off. - **Let Plane collect anonymous usage data** -Plane collects anonymized usage data (no PII) to help improve features and overall experience. You can turn this off anytime. See [Telemetry](/self-hosting/telemetry) for more info. + Plane collects anonymized usage data (no PII) to help improve features and overall experience. You can turn this off anytime. See [Telemetry](/self-hosting/telemetry) for more info. ![](/images/instance-admin/god-mode-general.webp) ### Workspaces + The Workspaces section allows you to manage all workspaces within your Plane instance. -- **View all Workspaces** -Access a complete list of workspaces on your instance. +- **View all Workspaces** + Access a complete list of workspaces on your instance. - **Create Workspaces** -You can create new workspaces directly from this section. If workspace creation is restricted, only the instance admin will have this ability. + You can create new workspaces directly from this section. If workspace creation is restricted, only the instance admin will have this ability. -- **Restrict Workspace creation** -Toggle the **Prevent anyone from creating a workspace** option to prevent anyone else from creating workspaces. Once enabled, only you (the instance admin) can create new workspaces. +- **Restrict Workspace creation** + Toggle the **Prevent anyone from creating a workspace** option to prevent anyone else from creating workspaces. Once enabled, only you (the instance admin) can create new workspaces. To add users to a workspace, you will need to [invite them](https://docs.plane.so/core-concepts/workspaces/members#add-member) after creating it. - + ::: info Workspace deletion is currently not supported. ::: ![](/images/instance-admin/god-mode-workspaces.webp) -### Email +### Email + Set up your SMTP server here so you can send essential emails—password resets, exports, changes to your instance—and Plane-enabled emails—onboarding, tips and tricks, new features— to all your users. [Learn more here](/self-hosting/govern/communication). ![](/images/instance-admin/god-mode-email.webp) ### Authentication + Control what SSO and OAuth services your users can use to sign up and log in to your Plane instance. You can also toggle unique code and password logins on and off from here. [Learn more here](/self-hosting/govern/authentication). - **Allow anyone to sign up without an invite** @@ -95,59 +98,61 @@ You can use your own third-party libraries to update images in project settings. ![](/images/instance-admin/god-mode-images.webp) ## Add instance admin + To grant a user full administrative access (including God mode) to your self-hosted Plane instance, you'll need to assign them the Instance Admin role. Instance admins have unrestricted control over all configurations and settings within the instance. To promote an existing user to Instance Admin, execute the following command in your terminal: + ```bash docker exec /bin/bash -c "python manage.py create_instance_admin " -``` +``` + Ensure that the provided email matches the user's registered account. This command will instantly elevate their privileges to full administrative access. --------- +--- Soon, we will introduce God Mode for our Cloud users as well so they can manage their workspaces better. To get notified about this, [sign up here](https://ece39166.sibforms.com/serve/MUIFANgaMWIARsq1n0lMNrch19pdY2HJm9FkSXAeq1DrCoXJBmO9Yq6SPgtzu7rL0lQBmCvvz2A2arVl5WaDxYu6YhNW4PKNAis0DMXmpRnwm5633BvXqIYILqZuyqYiGS7_QjJ0Ozh4R2uctd8RwiiTLSHWpnV2njQt6DPV5cVr8FH3K-TouNAlBScOJxbCpjj8fYo2ULsEJeAL). ## FAQs - ::: details How do you know who an Instance admin is? - Whoever spins up the instance or upgrades to v0.14, we assume, is the instance admin. When you see Let's secure your instance, enter your email-password combo. If you are already using Plane with those credentials, you will be logged in and will see /god-mode features. If not, we will create a new user on your local instance and you will see /god-mode. +::: details How do you know who an Instance admin is? +Whoever spins up the instance or upgrades to v0.14, we assume, is the instance admin. When you see Let's secure your instance, enter your email-password combo. If you are already using Plane with those credentials, you will be logged in and will see /god-mode features. If not, we will create a new user on your local instance and you will see /god-mode. - Our shrewd guess right now is users are technical enough to upgrade to or bring up a new instance with v0.14 are instance admins. If there’s a case where this isn’t true, please reach out to us before you upgrade or set up your fresh instance. - ::: - - ::: details What if I don’t complete secure instance set-up at the time of the upgrade? - We strongly recommend completing set-up at upgrade so your regular users can access Plane without trouble. Because we are introducing several sensitive admin features in `God Mode`, we will show an instance-not-set-up screen to your regular users until such a time that you can complete the setup. - ![success-on-setup-existing-instances-self-hosted](/images/faq-2.png) - ::: +Our shrewd guess right now is users are technical enough to upgrade to or bring up a new instance with v0.14 are instance admins. If there’s a case where this isn’t true, please reach out to us before you upgrade or set up your fresh instance. +::: - ::: details What has changed with how existing regular users of my instance log in? - All existing users will log in with their usual email address-password combos if they are already doing it. If they haven’t been using a password when not OAuthing into Plane, they will now need to. If OAuth is enabled, users can continue using your OAuth methods. New users will need to choose a password or OAuth into Plane. - ::: +::: details What if I don’t complete secure instance set-up at the time of the upgrade? +We strongly recommend completing set-up at upgrade so your regular users can access Plane without trouble. Because we are introducing several sensitive admin features in `God Mode`, we will show an instance-not-set-up screen to your regular users until such a time that you can complete the setup. +![success-on-setup-existing-instances-self-hosted](/images/faq-2.png) +::: - ::: details What will happen to the default captain@plane.so account that you shipped so far? - For all new instances, there won’t be a `captain@plane.so` account. Instance set-up will allow you to set up a workspace and set workspace and project admins. +::: details What has changed with how existing regular users of my instance log in? +All existing users will log in with their usual email address-password combos if they are already doing it. If they haven’t been using a password when not OAuthing into Plane, they will now need to. If OAuth is enabled, users can continue using your OAuth methods. New users will need to choose a password or OAuth into Plane. +::: - For existing instances, the instance admin’s email will be added to each project with the same permissions as `captain@plane.so’s` so you can remove that email completely from your workspaces and projects. - ::: +::: details What will happen to the default captain@plane.so account that you shipped so far? +For all new instances, there won’t be a `captain@plane.so` account. Instance set-up will allow you to set up a workspace and set workspace and project admins. - ::: details This is unreal, but I have an instance that has a /god-mode path already. I can’t access my Plane instance. Help! - That is unreal! Please reach out to us immediately on [support](https://discord.com/login?redirect_to=%2Fchannels%2F1031547764020084846%2F1094927053867995176) or on our [Discord](https://discord.com/invite/A92xrEGCge) and mark your message urgent. We will help you get your instance back pronto. +For existing instances, the instance admin’s email will be added to each project with the same permissions as `captain@plane.so’s` so you can remove that email completely from your workspaces and projects. +::: - ::: +::: details This is unreal, but I have an instance that has a /god-mode path already. I can’t access my Plane instance. Help! +That is unreal! Please reach out to us immediately on [support](https://discord.com/login?redirect_to=%2Fchannels%2F1031547764020084846%2F1094927053867995176) or on our [Discord](https://discord.com/invite/A92xrEGCge) and mark your message urgent. We will help you get your instance back pronto. - ::: details How will emails for password resets and onboarding be sent to users of my instance(s)? - We have always let you configure your own SMTP server to send emails from within your instance. It’s also why we are being deliberate about leading the instance admin of an existing instance to `/god-mode` first. After completing secure instance set-up now, you can configure your SMTP server on the UI instead of via `.env` variables. We strongly recommend you do that to avoid password-reset failures and failures in email delivery. +::: - Please [reach out](https://discord.com/login?redirect_to=%2Fchannels%2F1031547764020084846%2F1094927053867995176) to us on [Discord](https://discord.com/invite/A92xrEGCge) if you haven’t set up SMTP and are facing troubles with your users logging in. - ::: +::: details How will emails for password resets and onboarding be sent to users of my instance(s)? +We have always let you configure your own SMTP server to send emails from within your instance. It’s also why we are being deliberate about leading the instance admin of an existing instance to `/god-mode` first. After completing secure instance set-up now, you can configure your SMTP server on the UI instead of via `.env` variables. We strongly recommend you do that to avoid password-reset failures and failures in email delivery. - ::: details Why are you introducing passwords for app.plane.so users? What’s happening with unique links to sign up and sign in? - Unique links are secure and relatively easier, but we have heard from enough of our Cloud users that they would like to log in using a more permanent and easier method. Should you want to continue using unique codes, you are covered. We will keep that option alive for good. +Please [reach out](https://discord.com/login?redirect_to=%2Fchannels%2F1031547764020084846%2F1094927053867995176) to us on [Discord](https://discord.com/invite/A92xrEGCge) if you haven’t set up SMTP and are facing troubles with your users logging in. +::: - While using Google or GitHub are good options already, not all of you would want to use them. For those that prefer a password and would like to do away with codes, we want to make that option available. - ::: +::: details Why are you introducing passwords for app.plane.so users? What’s happening with unique links to sign up and sign in? +Unique links are secure and relatively easier, but we have heard from enough of our Cloud users that they would like to log in using a more permanent and easier method. Should you want to continue using unique codes, you are covered. We will keep that option alive for good. - ::: details Is there a God Mode for Cloud admins, too? - Not now, but soon enough, there will be a `God Mode` for Cloud admins. - ::: +While using Google or GitHub are good options already, not all of you would want to use them. For those that prefer a password and would like to do away with codes, we want to make that option available. +::: +::: details Is there a God Mode for Cloud admins, too? +Not now, but soon enough, there will be a `God Mode` for Cloud admins. +::: diff --git a/docs/self-hosting/govern/integrations/github.md b/docs/self-hosting/govern/integrations/github.md index 7f85f97..82d3549 100644 --- a/docs/self-hosting/govern/integrations/github.md +++ b/docs/self-hosting/govern/integrations/github.md @@ -4,7 +4,6 @@ description: Connect GitHub to your self-hosted Plane instance. Sync pull reques keywords: plane github integration, github sync, pull request tracking, commit linking, github app, self-hosting, plane devops --- - # Configure GitHub for Plane integration This guide walks you through setting up a GitHub App to enable GitHub integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for GitHub, you’ll need to set up the necessary authentication, permissions, and webhooks to ensure smooth integration. @@ -12,12 +11,13 @@ This guide walks you through setting up a GitHub App to enable GitHub integratio This guide covers configuration for both: - **[GitHub Cloud](/self-hosting/govern/integrations/github#github-cloud)** -The standard cloud-hosted GitHub service + The standard cloud-hosted GitHub service - **[GitHub Enterprise Server](/self-hosting/govern/integrations/github#github-enterprise-server)** -Self-hosted GitHub instances for organizations with specific compliance or security requirements + Self-hosted GitHub instances for organizations with specific compliance or security requirements In this guide, you’ll: + 1. [Create and configure a GitHub App](/self-hosting/govern/integrations/github#create-github-app) 2. [Set up permissions and events](/self-hosting/govern/integrations/github#set-up-permissions-and-events) 3. [Configure your Plane instance](/self-hosting/govern/integrations/github#configure-plane-instance) @@ -25,7 +25,7 @@ In this guide, you’ll: ::: warning **Activate GitHub integration** -After creating and configuring the GitHub app and configuring the instance as detailed on this page, you'll need to [setup the GitHub integration](https://docs.plane.so/integrations/github) within Plane. +After creating and configuring the GitHub app and configuring the instance as detailed on this page, you'll need to [setup the GitHub integration](https://docs.plane.so/integrations/github) within Plane. ::: ## Create GitHub App @@ -107,6 +107,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your 5. In the **Post installation** section, add the below **Setup URL**. **For Plane cloud instance** + ```bash https://silo.plane.so/api/oauth/github-enterprise/auth/callback ``` @@ -116,6 +117,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your ```bash https:///silo/api/oauth/github-enterprise/auth/callback ``` + Redirects users to this URL after GitHub app installation. ![Add setup URL](/images/integrations/github/add-setup-url.webp) @@ -124,6 +126,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your 7. In the **Webhook** section, add the below **Webhook URL**. **For Plane cloud instance** + ```bash https://silo.plane.so/api/github-enterprise/github-webhook ``` @@ -133,50 +136,49 @@ To configure GitHub integration, you'll need to create a GitHub App within your ```bash https:///silo/api/github-enterprise/github-webhook ``` + This allows Plane to receive updates from GitHub repositories. ![Add Webhook URL](/images/integrations/github/add-webhook-url.webp) ::: - ### Set up permissions and events 1. Add repository and account permissions by setting the **Access** dropdown next to each permission, as shown in the tables below. - ![Setup permissions](/images/integrations/github/setup-permissions.webp) + ![Setup permissions](/images/integrations/github/setup-permissions.webp) - **Repository permissions** + **Repository permissions** - |Permission           |Access level    |Purpose| - |---------|---------------------|-----------| - |Issues|Read and write|Enables reading, creating, updating, closing, and commenting on issues within the repository.| - |Metadata|Read-only|Provides read-only access to repository metadata, such as its name, description, and visibility.| - |Pull requests|Read and write|Allows reading, creating, updating, merging, and commenting on pull requests.| + | Permission            | Access level     | Purpose | + | ---------------------------------------------------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------ | + | Issues | Read and write | Enables reading, creating, updating, closing, and commenting on issues within the repository. | + | Metadata | Read-only | Provides read-only access to repository metadata, such as its name, description, and visibility. | + | Pull requests | Read and write | Allows reading, creating, updating, merging, and commenting on pull requests. | - **Account permissions** + **Account permissions** - |Permission          |Access level    |Purpose| - |---------|------------|-----------| - |Email addresses|Read-only|Grants access to users' email addresses, typically for notifications or communication.| - |Profile|Read and write|Enables access to user profile details like name, username, and avatar.| + | Permission           | Access level     | Purpose | + | ---------------------------------------------------------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------- | + | Email addresses | Read-only | Grants access to users' email addresses, typically for notifications or communication. | + | Profile | Read and write | Enables access to user profile details like name, username, and avatar. | +2. In the **Subscribe to events** section, turn on all the required events below. -2. In the **Subscribe to events** section, turn on all the required events below. + ![Subscribe to events](/images/integrations/github/subscribe-to-events.webp) - ![Subscribe to events](/images/integrations/github/subscribe-to-events.webp) - - |Event                                            |Purpose| - |---------|------------| - |Installation target| This is where the repositories or organizations where your GitHub App is installed. This determines which repositories Plane can sync with.| - |Meta|Includes metadata about the app's configuration and setup. This is essential for maintaining integration stability.| - |Issue comment| Triggers when a comment is added, edited, or deleted on an issue. Useful for keeping comments synced between Plane and GitHub.| - |Issues|Triggers when an issue is created, updated, closed, reopened, assigned, labeled, or transferred. Ensures issue status and details remain consistent between Plane and GitHub.| - |Pull request|Fires when a pull request is opened, closed, merged, edited, or labeled. Essential for tracking development progress.| - |Pull request review|Activates when a review is submitted, edited, or dismissed. Keeps review activities aligned between Plane and GitHub.| - |Pull request review comment|Fires when a review comment is added, modified, or removed. Ensures feedback is reflected across both platforms.| - |Pull request review thread|Triggers when a review discussion thread is resolved or reopened. Helps maintain visibility on code review discussions.| - |Push|Activates when new commits are pushed to a repository. Useful for tracking code updates and changes.| - |Repository sub issues|Tracks issues within a repository that are linked to or managed by another issue. Ensures accurate synchronization of related issues.| + | Event                                             | Purpose | + | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | Installation target | This is where the repositories or organizations where your GitHub App is installed. This determines which repositories Plane can sync with. | + | Meta | Includes metadata about the app's configuration and setup. This is essential for maintaining integration stability. | + | Issue comment | Triggers when a comment is added, edited, or deleted on an issue. Useful for keeping comments synced between Plane and GitHub. | + | Issues | Triggers when an issue is created, updated, closed, reopened, assigned, labeled, or transferred. Ensures issue status and details remain consistent between Plane and GitHub. | + | Pull request | Fires when a pull request is opened, closed, merged, edited, or labeled. Essential for tracking development progress. | + | Pull request review | Activates when a review is submitted, edited, or dismissed. Keeps review activities aligned between Plane and GitHub. | + | Pull request review comment | Fires when a review comment is added, modified, or removed. Ensures feedback is reflected across both platforms. | + | Pull request review thread | Triggers when a review discussion thread is resolved or reopened. Helps maintain visibility on code review discussions. | + | Push | Activates when new commits are pushed to a repository. Useful for tracking code updates and changes. | + | Repository sub issues | Tracks issues within a repository that are linked to or managed by another issue. Ensures accurate synchronization of related issues. | 3. Click the **Create GitHub App** button at the bottom of the page. @@ -251,6 +253,7 @@ To configure GitHub integration, you'll need to create a GitHub App within your - Private key 7. Convert the Private key to convert it to base64. Since private keys are typically multi-line, they can cause parsing errors or issues when setting environment variables. To avoid this, run the following command to convert the key to base64: + ```bash cat private_key.pem | base64 -w 0 ``` @@ -259,7 +262,6 @@ To configure GitHub integration, you'll need to create a GitHub App within your ::: - ## Troubleshooting ### Invalid private key @@ -271,14 +273,18 @@ To configure GitHub integration, you'll need to create a GitHub App within your This error usually occurs when the private key is not correctly generated. To fix this, follow the below steps. 1. Generate a new private key. -2. Convert the private key to base64. - ```bash - cat private_key.pem | base64 -w 0 - ``` +2. Convert the private key to base64. + +```bash + cat private_key.pem | base64 -w 0 +``` + 3. Add the private key to the `.env` file. - ```bash - GITHUB_PRIVATE_KEY= - ``` + +```bash + GITHUB_PRIVATE_KEY= +``` + 4. Save the file and restart the instance. ### Unable to connect GitHub organization account or personal account @@ -300,8 +306,8 @@ This error usually occurs when the callback URL is not correctly configured or t This error usually occurs when the application secret is not correctly configured. To fix this, follow the below steps. -1. Delete the `plane_app_details_github` key from redis cache. ```del plane_app_details_github```. -2. Set the `SILO_BASE_URL` in env with plane self hosted url and restart the api server. ```export SILO_BASE_URL=https://``` +1. Delete the `plane_app_details_github` key from redis cache. `del plane_app_details_github`. +2. Set the `SILO_BASE_URL` in env with plane self hosted url and restart the api server. `export SILO_BASE_URL=https://` 3. Run this command in api server shell `python manage.py reset_marketplace_app_secrets` to reset the application secrets. 4. Try to connect again to the organization account to Plane. @@ -309,4 +315,4 @@ This error usually occurs when the application secret is not correctly configure This error usually occurs when the GitHub integration is not correctly configured. To fix this, follow the below steps. -1. Make sure you've `opted out` of Server Token expiration and reconnect once again to the organization account to Plane. Check in Github App Settings > Optional Features \ No newline at end of file +1. Make sure you've `opted out` of Server Token expiration and reconnect once again to the organization account to Plane. Check in Github App Settings > Optional Features diff --git a/docs/self-hosting/govern/integrations/gitlab.md b/docs/self-hosting/govern/integrations/gitlab.md index bdb4441..5bbcdf6 100644 --- a/docs/self-hosting/govern/integrations/gitlab.md +++ b/docs/self-hosting/govern/integrations/gitlab.md @@ -4,7 +4,6 @@ description: Connect GitLab to your self-hosted Plane instance. Sync merge reque keywords: plane gitlab integration, gitlab sync, merge request tracking, gitlab webhook, self-hosting, plane devops --- - # Configure GitLab for Plane integration This guide walks you through setting up a GitLab application to enable GitLab integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for GitLab, you’ll need to create an application, configure authentication, and set the necessary permissions to ensure seamless integration. @@ -12,10 +11,10 @@ This guide walks you through setting up a GitLab application to enable GitLab in This guide covers configuration for both: - **[GitLab.com](/self-hosting/govern/integrations/gitlab#gitlab-cloud)** -The standard cloud-hosted GitLab service + The standard cloud-hosted GitLab service - **[GitLab Self-managed](/self-hosting/govern/integrations/gitlab#gitlab-self-managed)** -Self-hosted GitLab instances for organizations with specific compliance or security requirements + Self-hosted GitLab instances for organizations with specific compliance or security requirements In this guide, you’ll: @@ -25,7 +24,7 @@ In this guide, you’ll: ::: warning **Activate GitLab integration** -After creating and configuring the GitLab application and configuring the instance as detailed on this page, you'll need to [setup the GitLab integration](https://docs.plane.so/integrations/gitlab) within Plane. +After creating and configuring the GitLab application and configuring the instance as detailed on this page, you'll need to [setup the GitLab integration](https://docs.plane.so/integrations/gitlab) within Plane. ::: ## Create GitLab Application @@ -41,28 +40,28 @@ After creating and configuring the GitLab application and configuring the instan 3. Navigate to the **Applications** tab. 4. Click on **Add new application** to begin the setup. - ![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp) + ![Add GitLab application](/images/integrations/gitlab/add-gitlab-application.webp) 5. Provide a **Name** for your application. 6. Enter the following **Redirect URI**, replacing [YOUR_DOMAIN] with your actual domain: - ```bash - https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback - ``` + ```bash + https://[YOUR_DOMAIN]/silo/api/gitlab/auth/callback + ``` 7. Check the **Confidential** box. - ![Add app details](/images/integrations/gitlab/add-app-details.webp) + ![Add app details](/images/integrations/gitlab/add-app-details.webp) 8. Set permissions by selecting the required **Scopes**. The table below explains each scope: - |Permission|Explanation| - |----------|-----------| - |`api`|Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests.| - |`read_api`|Allows read-only access to all groups, projects, container registry, and package registry.| - |`read_user`|Grants read-only access to user profiles via the /user API endpoint, including username, public email, and full name. Also provides access to /users endpoints.| - |`read_repository`|Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API.| - |`profile`|Grants read-only access to the user's profile data using OpenID Connect.| - |`email`|Provides read-only access to the user's primary email address using OpenID Connect.| + | Permission | Explanation | + | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `api` | Grants full read/write access to the API, including all groups, projects, container registry, dependency proxy, and package registry. Required for API requests. | + | `read_api` | Allows read-only access to all groups, projects, container registry, and package registry. | + | `read_user` | Grants read-only access to user profiles via the /user API endpoint, including username, public email, and full name. Also provides access to /users endpoints. | + | `read_repository` | Enables read-only access to repositories in private projects via Git-over-HTTP or the Repository Files API. | + | `profile` | Grants read-only access to the user's profile data using OpenID Connect. | + | `email` | Provides read-only access to the user's primary email address using OpenID Connect. | 9. Click **Save Application** to finalize the setup. @@ -77,28 +76,26 @@ After creating and configuring the GitLab application and configuring the instan Fill in the application details with the following configuration: - **Name** -Enter a descriptive name for your application (e.g., `Plane Local Dev` or `Plane Integration`). + Enter a descriptive name for your application (e.g., `Plane Local Dev` or `Plane Integration`). - **Redirect URI** -The redirect URI depends on your Plane deployment: + The redirect URI depends on your Plane deployment: + + **For Plane Cloud:** + + `https://silo.plane.so/api/oauth/gitlab-enterprise/auth/callback` - **For Plane Cloud:** - ``` - https://silo.plane.so/api/oauth/gitlab-enterprise/auth/callback - ``` + **For Plane Self-Hosted:** -**For Plane Self-Hosted:** - ``` - https:///silo/api/oauth/gitlab-enterprise/auth/callback - ``` + `https:///silo/api/oauth/gitlab-enterprise/auth/callback` Replace `` with your actual Plane instance domain. - **Confidential** -Keep the **Confidential** checkbox enabled. This ensures the application uses a client secret for secure authentication. + Keep the **Confidential** checkbox enabled. This ensures the application uses a client secret for secure authentication. - **Scopes** -Select the following scopes to grant Plane the necessary permissions: + Select the following scopes to grant Plane the necessary permissions: - **api** - Grants complete read/write access to the API, including all groups and projects - **read_api** - Grants read access to the API, including all groups and projects @@ -111,7 +108,6 @@ Select the following scopes to grant Plane the necessary permissions: ::: - ## Configure Plane instance :::tabs key:gitlab-edition @@ -119,14 +115,15 @@ Select the following scopes to grant Plane the necessary permissions: == GitLab Cloud {#gitlab-cloud} 1. Copy the **Application ID** and **Secret** from the newly created application. - ![Copy credentials](/images/integrations/gitlab/copy-credentials.webp) + ![Copy credentials](/images/integrations/gitlab/copy-credentials.webp) 2. Add these environment variables with the values to your Plane instance's `.env` file. - ```bash - GITLAB_CLIENT_ID= - GITLAB_CLIENT_SECRET= - ``` + ```bash + GITLAB_CLIENT_ID= + GITLAB_CLIENT_SECRET= + ``` + 3. Save the file and restart the instance. 4. Once you've completed the instance configuration, [activate the GitLab integration in Plane](https://docs.plane.so/integrations/gitlab?edition=gitlab-cloud). @@ -134,9 +131,8 @@ Select the following scopes to grant Plane the necessary permissions: == GitLab Self-managed {#gitlab-self-managed} 1. Copy the **Application ID** and **Secret** from the newly created application. - ![Copy credentials](/images/integrations/gitlab/copy-credentials.webp) + ![Copy credentials](/images/integrations/gitlab/copy-credentials.webp) 2. Once you've created the application, [activate the GitLab Self-managed integration in Plane](https://docs.plane.so/integrations/gitlab?edition=gitlab-self-managed). ::: - diff --git a/docs/self-hosting/govern/integrations/sentry.md b/docs/self-hosting/govern/integrations/sentry.md index c14e020..d39c4d9 100644 --- a/docs/self-hosting/govern/integrations/sentry.md +++ b/docs/self-hosting/govern/integrations/sentry.md @@ -4,21 +4,22 @@ description: Connect Sentry error monitoring to your self-hosted Plane instance. keywords: plane sentry integration, error tracking, sentry alerts, bug tracking, error monitoring, self-hosting, plane devops --- - # Configure Sentry for Plane integration This guide shows you how to set up Sentry integration for your self-hosted Plane instance. Unlike Plane Cloud where Sentry comes pre-configured, self-hosted instances require you to create a custom integration in Sentry and configure your Plane deployment with the necessary credentials. ::: info **What you'll accomplish:** + 1. Create a Sentry custom integration with proper permissions and webhooks 2. Configure your Plane instance with Sentry credentials 3. Enable error tracking and automatic issue creation from Sentry alerts -::: + ::: ## Before you begin You'll need: + - Administrator access to your Sentry organization - Access to your Plane instance configuration files - Your Plane instance domain (e.g., `plane.yourcompany.com`) @@ -33,14 +34,14 @@ A custom integration (also called a public integration) connects your Sentry org 4. Select **Public Integration**. 5. Fill in these fields on the integration creation screen: - | Field | Value | - |-------|-------| - | **Name** | `Plane` (or any name you prefer) | - | **Author** | Your organization name | - | **Webhook URL** | `https://[YOUR_DOMAIN]/silo/api/sentry/sentry-webhook/` | - | **Redirect URL** | `https://[YOUR_DOMAIN]/silo/api/oauth/sentry/auth/callback` | - | **Verify Installation** | Disabled (recommended) | - | **Alert Rule Action** | Enabled | + | Field | Value | + | ----------------------- | ----------------------------------------------------------- | + | **Name** | `Plane` (or any name you prefer) | + | **Author** | Your organization name | + | **Webhook URL** | `https://[YOUR_DOMAIN]/silo/api/sentry/sentry-webhook/` | + | **Redirect URL** | `https://[YOUR_DOMAIN]/silo/api/oauth/sentry/auth/callback` | + | **Verify Installation** | Disabled (recommended) | + | **Alert Rule Action** | Enabled | ::: tip Replace `[YOUR_DOMAIN]` with your actual Plane instance domain. For example, if your Plane instance is at `plane.company.com`, your Webhook URL would be `https://plane.company.com/silo/api/sentry/sentry-webhook/` @@ -64,6 +65,7 @@ Enables automatic Plane work item creation when Sentry alert rules trigger. The schema defines how Sentry and Plane interact—what fields appear when creating issues and how alert rules behave. Paste this schema into the **Schema** field: + ```json { "elements": [ @@ -230,16 +232,16 @@ The second element enables automatic work item creation when Sentry alerts fire. Configure these permissions to allow Sentry to interact with Plane appropriately: -| Permission | Access Level | Why This Matters | -|------------|--------------|------------------| -| **Project** | Read | Access project details, tags, and debug files from Sentry | -| **Team** | Read | Retrieve team member lists for assignee dropdowns | -| **Release** | No Access | Not required for Plane integration | -| **Distribution** | No Access | Not required for Plane integration | -| **Issue & Event** | Read & Write | Create and link issues, sync status updates bidirectionally | -| **Organization** | Read | Resolve organization IDs and retrieve repository information | -| **Member** | Read | Access member details for assignee functionality | -| **Alerts** | Read | Enable alert rule actions for automatic issue creation | +| Permission | Access Level | Why This Matters | +| ----------------- | ------------ | ------------------------------------------------------------ | +| **Project** | Read | Access project details, tags, and debug files from Sentry | +| **Team** | Read | Retrieve team member lists for assignee dropdowns | +| **Release** | No Access | Not required for Plane integration | +| **Distribution** | No Access | Not required for Plane integration | +| **Issue & Event** | Read & Write | Create and link issues, sync status updates bidirectionally | +| **Organization** | Read | Resolve organization IDs and retrieve repository information | +| **Member** | Read | Access member details for assignee functionality | +| **Alerts** | Read | Enable alert rule actions for automatic issue creation | @@ -249,13 +251,13 @@ Webhooks keep Plane and Sentry synchronized. When issues change in Sentry, Plane Enable the **issue** webhook with these events: -| Event | Why It's Needed | -|-------|-----------------| -| **created** | Notify Plane when new Sentry issues are detected | -| **resolved** | Update linked Plane work items when Sentry issues are resolved | -| **assigned** | Sync assignee changes from Sentry to Plane | -| **archived** | Reflect archived status in Plane | -| **unresolved** | Update Plane when resolved issues reopen | +| Event | Why It's Needed | +| -------------- | -------------------------------------------------------------- | +| **created** | Notify Plane when new Sentry issues are detected | +| **resolved** | Update linked Plane work items when Sentry issues are resolved | +| **assigned** | Sync assignee changes from Sentry to Plane | +| **archived** | Reflect archived status in Plane | +| **unresolved** | Update Plane when resolved issues reopen | @@ -267,7 +269,7 @@ After saving your integration, Sentry generates OAuth credentials: - **Client Secret** - A private key used to authenticate API requests ::: warning -**Important** +**Important** The Client Secret is only displayed once immediately after creating the integration. Copy it now and store it securely. If you lose it, you'll need to regenerate the integration. ::: @@ -280,9 +282,11 @@ Add Sentry credentials to your Plane instance so it can communicate with Sentry' ### Locate your configuration file **For Docker deployments:** + - Edit `plane.env` in your Plane installation directory **For Kubernetes deployments:** + - Edit your `custom-values.yaml` file or ConfigMap containing environment variables ### Add environment variables @@ -290,6 +294,7 @@ Add Sentry credentials to your Plane instance so it can communicate with Sentry' Add these variables to your Plane configuration: **For Docker (`plane.env`):** + ```bash # Sentry Integration SENTRY_BASE_URL=https://sentry.io @@ -299,25 +304,26 @@ SENTRY_INTEGRATION_SLUG=plane ``` **For Kubernetes (`custom-values.yaml`):** + ```yaml env: silo_envs: - sentry_base_url: 'https://sentry.io' - sentry_client_id: '' - sentry_client_secret: '' - sentry_integration_slug: 'plane' + sentry_base_url: "https://sentry.io" + sentry_client_id: "" + sentry_client_secret: "" + sentry_integration_slug: "plane" ``` Replace `` and `` with the credentials from Step 1. ### Environment variable reference -| Variable | Required | Default | Description | -|----------|----------|---------|-------------| -| `SENTRY_BASE_URL` | No | `https://sentry.io` | Base URL of your Sentry instance. For self-hosted Sentry, use your Sentry domain (e.g., `https://sentry.company.com`) | -| `SENTRY_CLIENT_ID` | Yes | - | Client ID from your Sentry custom integration | -| `SENTRY_CLIENT_SECRET` | Yes | - | Client Secret from your Sentry custom integration (only shown once during creation) | -| `SENTRY_INTEGRATION_SLUG` | No | - | The slug identifier for your integration. Find this in your integration's URL: `https://org.sentry.io/settings/developer-settings/plane-local` (here `plane-local` is the slug) | +| Variable | Required | Default | Description | +| ------------------------- | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `SENTRY_BASE_URL` | No | `https://sentry.io` | Base URL of your Sentry instance. For self-hosted Sentry, use your Sentry domain (e.g., `https://sentry.company.com`) | +| `SENTRY_CLIENT_ID` | Yes | - | Client ID from your Sentry custom integration | +| `SENTRY_CLIENT_SECRET` | Yes | - | Client Secret from your Sentry custom integration (only shown once during creation) | +| `SENTRY_INTEGRATION_SLUG` | No | - | The slug identifier for your integration. Find this in your integration's URL: `https://org.sentry.io/settings/developer-settings/plane-local` (here `plane-local` is the slug) | ::: info **Using self-hosted Sentry?** @@ -329,12 +335,14 @@ If you're running your own Sentry instance, change `SENTRY_BASE_URL` to your Sen Apply the configuration changes: **For Docker:** + ```bash docker compose down docker compose up -d ``` **For Kubernetes:** + ```bash helm upgrade plane-app plane-enterprise.tgz \ --namespace plane \ @@ -345,5 +353,4 @@ helm upgrade plane-app plane-enterprise.tgz \ Once you’ve completed the instance configuration, [activate the Sentry integration](https://docs.plane.so/integrations/sentry#set-up-sentry-integration) in Plane. - -For questions about Sentry integration, contact [support@plane.so](mailto:support@plane.so). \ No newline at end of file +For questions about Sentry integration, contact [support@plane.so](mailto:support@plane.so). diff --git a/docs/self-hosting/govern/integrations/slack.md b/docs/self-hosting/govern/integrations/slack.md index 0a417b4..7372416 100644 --- a/docs/self-hosting/govern/integrations/slack.md +++ b/docs/self-hosting/govern/integrations/slack.md @@ -4,19 +4,19 @@ description: Connect Slack to your self-hosted Plane instance. Get notifications keywords: plane slack integration, slack notifications, slack bot, workspace notifications, slack webhook, self-hosting, plane communication --- - # Configure Slack for Plane integration This guide walks you through setting up a Slack App to enable Slack integration for your Plane workspace on a self-hosted instance. Since self-hosted environments don’t come pre-configured for Slack, you’ll need to set up the necessary authentication, permissions, and event subscriptions to ensure seamless communication between Plane and Slack. In this guide, you’ll: + 1. [Create and configure a Slack App](/self-hosting/govern/integrations/slack#create-slack-app) 2. [Configure your Plane instance](/self-hosting/govern/integrations/slack#configure-plane-instance) ::: warning **Activate Slack integration** -After creating and configuring the Slack app and configuring the instance as detailed on this page, you'll need to [set up the Slack integration](https://docs.plane.so/integrations/slack) within Plane. +After creating and configuring the Slack app and configuring the instance as detailed on this page, you'll need to [set up the Slack integration](https://docs.plane.so/integrations/slack) within Plane. ::: ## Create Slack App @@ -26,16 +26,15 @@ To configure Slack integration, you'll need to create a Slack App within your or 1. Go to [Your Apps](https://api.slack.com/apps) on Slack. 2. Click **Create an App**. - ![Create Slack App](/images/integrations/slack/create-slack-app.webp) + ![Create Slack App](/images/integrations/slack/create-slack-app.webp) 3. Choose **From a manifest**. - ![Choose Manifest](/images/integrations/slack/choose-from-manifest.webp) + ![Choose Manifest](/images/integrations/slack/choose-from-manifest.webp) 4. Select the workspace where you want the app installed. 5. Remove the default manifest and paste the one below, making sure to update the placeholders with your actual values. - ![Manifest](/images/integrations/slack/app-from-manifest.webp) - + ![Manifest](/images/integrations/slack/app-from-manifest.webp) :::tabs key:manifest-file @@ -43,102 +42,89 @@ To configure Slack integration, you'll need to create a Slack App within your or ```json { - "display_information": { - "name": "[YOUR_APP_NAME]", - "description": "[YOUR_APP_DESCRIPTION]", - "background_color": "#224dab" + "display_information": { + "name": "[YOUR_APP_NAME]", + "description": "[YOUR_APP_DESCRIPTION]", + "background_color": "#224dab" + }, + "features": { + "bot_user": { + "display_name": "[YOUR_APP_NAME]", + "always_online": false }, - "features": { - "bot_user": { - "display_name": "[YOUR_APP_NAME]", - "always_online": false - }, - "shortcuts": [ - { - "name": "Create new issue", - "type": "message", - "callback_id": "issue_shortcut", - "description": "Create a new issue in plane" - }, - { - "name": "Link Work Item", - "type": "message", - "callback_id": "link_work_item", - "description": "Links thread with an existing work item" - } - ], - "slash_commands": [ - { - "command": "/plane", - "url": "https://[YOUR_DOMAIN]silo/api/slack/command/", - "description": "Create issue in Plane", - "should_escape": false - } - ], - "unfurl_domains": [ - "[YOUR_DOMAIN]" - ] + "shortcuts": [ + { + "name": "Create new issue", + "type": "message", + "callback_id": "issue_shortcut", + "description": "Create a new issue in plane" + }, + { + "name": "Link Work Item", + "type": "message", + "callback_id": "link_work_item", + "description": "Links thread with an existing work item" + } + ], + "slash_commands": [ + { + "command": "/plane", + "url": "https://[YOUR_DOMAIN]/silo/api/slack/command/", + "description": "Create issue in Plane", + "should_escape": false + } + ], + "unfurl_domains": ["[YOUR_DOMAIN]"] + }, + "oauth_config": { + "redirect_urls": [ + "https://[YOUR_DOMAIN]/silo/api/slack/team/auth/callback/", + "https://[YOUR_DOMAIN]/silo/api/slack/user/auth/callback/" + ], + "scopes": { + "user": ["chat:write", "identify", "im:read", "im:write", "links:write", "links:read"], + "bot": [ + "channels:join", + "channels:read", + "users:read", + "users:read.email", + "chat:write", + "chat:write.customize", + "channels:history", + "groups:history", + "mpim:history", + "im:history", + "links:read", + "links:write", + "groups:read", + "im:read", + "mpim:read", + "reactions:read", + "reactions:write", + "files:read", + "files:write", + "im:write", + "commands" + ] + } + }, + "settings": { + "event_subscriptions": { + "request_url": "https://[YOUR_DOMAIN]/silo/api/slack/events", + "bot_events": ["link_shared", "message.channels", "message.im"] }, - "oauth_config": { - "redirect_urls": [ - "https://[YOUR_DOMAIN]silo/api/slack/team/auth/callback/", - "https://[YOUR_DOMAIN]silo/api/slack/user/auth/callback/" - ], - "scopes": { - "user": [ - "chat:write", - "identify", - "im:read", - "im:write", - "links:write", - "links:read" - ], - "bot": [ - "channels:join", - "channels:read", - "users:read", - "users:read.email", - "chat:write", - "chat:write.customize", - "channels:history", - "groups:history", - "mpim:history", - "im:history", - "links:read", - "links:write", - "groups:read", - "im:read", - "mpim:read", - "reactions:read", - "reactions:write", - "files:read", - "files:write", - "im:write", - "commands" - ] - } + "interactivity": { + "is_enabled": true, + "request_url": "https://[YOUR_DOMAIN]/silo/api/slack/action/", + "message_menu_options_url": "https://[YOUR_DOMAIN]/silo/api/slack/options/" }, - "settings": { - "event_subscriptions": { - "request_url": "https://[YOUR_DOMAIN]silo/api/slack/events", - "bot_events": [ - "link_shared", - "message.channels", - "message.im" - ] - }, - "interactivity": { - "is_enabled": true, - "request_url": "https://[YOUR_DOMAIN]silo/api/slack/action/", - "message_menu_options_url": "https://[YOUR_DOMAIN]silo/api/slack/options/" - }, - "org_deploy_enabled": false, - "socket_mode_enabled": false, - "token_rotation_enabled": true - } + "org_deploy_enabled": false, + "socket_mode_enabled": false, + "token_rotation_enabled": true + } } ``` - + == YAML {yaml} ```yaml @@ -161,15 +147,15 @@ shortcuts: description: Links thread with an existing work item slash_commands: - command: /plane - url: https://[YOUR_DOMAIN]silo/api/slack/command/ + url: https://[YOUR_DOMAIN]/silo/api/slack/command/ description: Create issue in Plane should_escape: false unfurl_domains: - [YOUR_DOMAIN] oauth_config: redirect_urls: - - https://[YOUR_DOMAIN]silo/api/slack/team/auth/callback/ - - https://[YOUR_DOMAIN]silo/api/slack/user/auth/callback/ + - https://[YOUR_DOMAIN]/silo/api/slack/team/auth/callback/ + - https://[YOUR_DOMAIN]/silo/api/slack/user/auth/callback/ scopes: user: - chat:write @@ -202,23 +188,24 @@ scopes: - commands settings: event_subscriptions: - request_url: https://[YOUR_DOMAIN]silo/api/slack/events + request_url: https://[YOUR_DOMAIN]/silo/api/slack/events bot_events: - link_shared - message.channels - message.im interactivity: is_enabled: true - request_url: https://[YOUR_DOMAIN]silo/api/slack/action/ - message_menu_options_url: https://[YOUR_DOMAIN]silo/api/slack/options/ + request_url: https://[YOUR_DOMAIN]/silo/api/slack/action/ + message_menu_options_url: https://[YOUR_DOMAIN]/silo/api/slack/options/ org_deploy_enabled: false socket_mode_enabled: false token_rotation_enabled: true ``` + ::: 6. Review the permissions and click **Create**. - ![Review summary](/images/integrations/slack/review-summary.webp) + ![Review summary](/images/integrations/slack/review-summary.webp) ### Manifest reference @@ -226,83 +213,84 @@ The manifest file defines the configuration for integrating Plane with Slack. It #### Features -| Feature | Explanation | -| --- | --- | -| `bot_user` | Required to send thread messages while syncing issues or sending Plane notifications to Slack.| -| `slack_commands` | A Slack command (`/plane`) allows users to create issues directly from Slack using a slash command. | -| `shortcuts` | After activation, users can create issues from messages inside Slack.| -| `unfurl_domain` | Specifies the domain where Plane is hosted. When an issue, cycle, or module link is pasted in Slack, it generates a preview of the entity. | +| Feature | Explanation | +| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | +| `bot_user` | Required to send thread messages while syncing issues or sending Plane notifications to Slack. | +| `slack_commands` | A Slack command (`/plane`) allows users to create issues directly from Slack using a slash command. | +| `shortcuts` | After activation, users can create issues from messages inside Slack. | +| `unfurl_domain` | Specifies the domain where Plane is hosted. When an issue, cycle, or module link is pasted in Slack, it generates a preview of the entity. | #### Variables -|Variable|Explanation| -|------------|--------| -|`YOUR_DOMAIN`|The domain where Plane is hosted. This is required for sending webhook events and authentication callbacks.| -|`YOUR_APP_NAME`|The name you want to give your Slack app. "Plane" is a good default option.| -|`YOUR_APP_DESCRIPTION`|A short description of your Slack app’s purpose.| +| Variable | Explanation | +| ---------------------- | ----------------------------------------------------------------------------------------------------------- | +| `YOUR_DOMAIN` | The domain where Plane is hosted. This is required for sending webhook events and authentication callbacks. | +| `YOUR_APP_NAME` | The name you want to give your Slack app. "Plane" is a good default option. | +| `YOUR_APP_DESCRIPTION` | A short description of your Slack app’s purpose. | #### Event subscription For thread sync and link unfurling to work, event subscriptions must be enabled. These events send relevant activity to Plane. -| Bot event | Explanation | -| --- | --- | -| `link_shared` | When a link is shared in Slack and its hostname matches `unfurl_domain`, Plane receives the event and generates a preview of the entity. | -| `message_channels` | When a message is posted in a channel, an event is triggered in Plane to support thread sync. | -| `message_im` | When a direct message (DM) is posted, an event is triggered in Plane to support thread sync. | +| Bot event | Explanation | +| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- | +| `link_shared` | When a link is shared in Slack and its hostname matches `unfurl_domain`, Plane receives the event and generates a preview of the entity. | +| `message_channels` | When a message is posted in a channel, an event is triggered in Plane to support thread sync. | +| `message_im` | When a direct message (DM) is posted, an event is triggered in Plane to support thread sync. | #### User permissions -| Permission | Explanation | -| --- | --- | -| `chat:write` | Allows the bot to send messages in channels and conversations it is a member of. | -| `identify` | Allows the bot to verify its own identity and retrieve basic information. | -| `im:read` | Enables the bot to view direct messages (DMs) where it has been added. | -| `im:write` | Allows the bot to send direct messages (DMs) to users. | -| `links:write` | Permits the bot to add, edit, and remove link unfurls. | -| `links:read` | Allows the bot to view link unfurls and associated metadata. | +| Permission | Explanation | +| ------------- | -------------------------------------------------------------------------------- | +| `chat:write` | Allows the bot to send messages in channels and conversations it is a member of. | +| `identify` | Allows the bot to verify its own identity and retrieve basic information. | +| `im:read` | Enables the bot to view direct messages (DMs) where it has been added. | +| `im:write` | Allows the bot to send direct messages (DMs) to users. | +| `links:write` | Permits the bot to add, edit, and remove link unfurls. | +| `links:read` | Allows the bot to view link unfurls and associated metadata. | #### Bot permissions -| Permission | Explanation | -| --- | --- | -| `channels:join` | Allows the bot to join public channels. | -| `channels:read` | Permits viewing public channel information and members. | -| `users:read` | Allows viewing user information and presence status. | -| `users:read.email` | Enables access to users' email addresses. | -| `chat:write` | Allows sending messages in channels and conversations. | +| Permission | Explanation | +| ---------------------- | -------------------------------------------------------------------------- | +| `channels:join` | Allows the bot to join public channels. | +| `channels:read` | Permits viewing public channel information and members. | +| `users:read` | Allows viewing user information and presence status. | +| `users:read.email` | Enables access to users' email addresses. | +| `chat:write` | Allows sending messages in channels and conversations. | | `chat:write.customize` | Enables customization of the bot's name and profile when sending messages. | -| `channels:history` | Allows viewing message history in public channels. | -| `groups:history` | Permits viewing message history in private channels. | -| `mpim:history` | Enables access to message history in multi-person direct messages. | -| `im:history` | Allows viewing message history in direct messages. | -| `links:read` | Permits viewing link unfurls and associated metadata. | -| `links:write` | Allows adding, editing, and removing link unfurls. | -| `groups:read` | Enables viewing private channel information and members. | -| `im:read` | Allows viewing direct messages where the bot is added. | -| `mpim:read` | Permits viewing multi-person direct messages. | -| `reactions:read` | Enables viewing emoji reactions on messages. | -| `reactions:write` | Allows adding and removing emoji reactions. | -| `files:read` | Permits viewing and downloading files. | -| `files:write` | Enables uploading, editing, and deleting files. | -| `im:write` | Allows sending direct messages to users. | -| `commands` | Enables the bot to add and respond to slash commands. | +| `channels:history` | Allows viewing message history in public channels. | +| `groups:history` | Permits viewing message history in private channels. | +| `mpim:history` | Enables access to message history in multi-person direct messages. | +| `im:history` | Allows viewing message history in direct messages. | +| `links:read` | Permits viewing link unfurls and associated metadata. | +| `links:write` | Allows adding, editing, and removing link unfurls. | +| `groups:read` | Enables viewing private channel information and members. | +| `im:read` | Allows viewing direct messages where the bot is added. | +| `mpim:read` | Permits viewing multi-person direct messages. | +| `reactions:read` | Enables viewing emoji reactions on messages. | +| `reactions:write` | Allows adding and removing emoji reactions. | +| `files:read` | Permits viewing and downloading files. | +| `files:write` | Enables uploading, editing, and deleting files. | +| `im:write` | Allows sending direct messages to users. | +| `commands` | Enables the bot to add and respond to slash commands. | ## Configure Plane instance -After creating your Slack app, follow these steps: + +After creating your Slack app, follow these steps: 1. Go to the **Event Subscriptions** tab. 2. Click **Retry** to verify your event subscription URL. - ![Event subscriptions](/images/integrations/slack/event-subscriptions.webp) + ![Event subscriptions](/images/integrations/slack/event-subscriptions.webp) 3. Navigate to the **Basic Information** tab on Slack to find your `client_id` and `client_secret`. 4. Add these environment variables with the values to your Plane instance's `.env` file. - ```bash - SLACK_CLIENT_ID= - SLACK_CLIENT_SECRET= - ``` -5. Save the file and restart the instance. + ```bash + SLACK_CLIENT_ID= + SLACK_CLIENT_SECRET= + ``` +5. Save the file and restart the instance. -6. Once you've completed the instance configuration, [activate the Slack integration in Plane](https://docs.plane.so/integrations/slack). \ No newline at end of file +6. Once you've completed the instance configuration, [activate the Slack integration in Plane](https://docs.plane.so/integrations/slack). diff --git a/docs/self-hosting/govern/ldap.md b/docs/self-hosting/govern/ldap.md index 099c05f..ba64cf9 100644 --- a/docs/self-hosting/govern/ldap.md +++ b/docs/self-hosting/govern/ldap.md @@ -4,7 +4,6 @@ description: Setup LDAP authentication for Plane. Configure Lightweight Director keywords: plane ldap, ldap authentication, active directory, directory service, ldap configuration, enterprise authentication, self-hosting --- - # LDAP authentication LDAP (Lightweight Directory Access Protocol) authentication lets your team sign in to Plane using their existing corporate credentials. Instead of creating separate Plane passwords, users authenticate through your organization's directory service. @@ -22,131 +21,139 @@ You'll need: ## Configure LDAP authentication 1. Sign in to your Plane instance in [God Mode](/self-hosting/govern/instance-admin). - ![Turn on LDAP](/images/ldap/enable-ldap.webp) + ![Turn on LDAP](/images/ldap/enable-ldap.webp) 2. Select **Authentication** from the left pane. -3. Click **Configure** next to **LDAP** at the bottom of the page. +3. Click **Configure** next to **LDAP** at the bottom of the page. 4. Enter your LDAP server details. - ![LDAP configuration](/images/ldap/ldap-configuration.webp) - - **Server URI (required)** - This is the address of your LDAP server. Include the protocol and port number. + ![LDAP configuration](/images/ldap/ldap-configuration.webp) + - **Server URI (required)** + This is the address of your LDAP server. Include the protocol and port number. + + **Format:** + - For unencrypted connections: `ldap://hostname:389` + - For encrypted connections (recommended): `ldaps://hostname:636` + + **Examples:** + + ``` + ldap://ldap.company.com:389 + ldaps://ad.company.com:636 + ldap://192.168.1.100:389 + ``` + + - **Bind DN (required)** + + This is the username of the service account that Plane will use to search your directory. Think of it as Plane's "read-only" account on your LDAP server. - **Format:** - - For unencrypted connections: `ldap://hostname:389` - - For encrypted connections (recommended): `ldaps://hostname:636` + The format varies depending on your directory service: - **Examples:** - ``` - ldap://ldap.company.com:389 - ldaps://ad.company.com:636 - ldap://192.168.1.100:389 - ``` + **Active Directory examples:** - - **Bind DN (required)** + ``` + cn=PlaneService,ou=Service Accounts,dc=company,dc=com + plane-svc@company.com + ``` - This is the username of the service account that Plane will use to search your directory. Think of it as Plane's "read-only" account on your LDAP server. + **OpenLDAP examples:** - The format varies depending on your directory service: + ``` + cn=admin,dc=example,dc=com + cn=readonly,ou=services,dc=example,dc=com + ``` - **Active Directory examples:** - ``` - cn=PlaneService,ou=Service Accounts,dc=company,dc=com - plane-svc@company.com - ``` + - **Bind Password (required)** - **OpenLDAP examples:** - ``` - cn=admin,dc=example,dc=com - cn=readonly,ou=services,dc=example,dc=com - ``` + Enter the password for your service account (Bind DN). Plane encrypts and stores this securely in its database. - - **Bind Password (required)** + - **User Search Base (required)** - Enter the password for your service account (Bind DN). Plane encrypts and stores this securely in its database. + This defines where in your directory Plane should look for users. Think of it as the "starting folder" for user searches. - - **User Search Base (required)** + Use the most specific path possible for better performance. - This defines where in your directory Plane should look for users. Think of it as the "starting folder" for user searches. + **Examples:** - Use the most specific path possible for better performance. + ``` + ou=users,dc=example,dc=com + ou=employees,ou=people,dc=company,dc=com + cn=users,dc=company,dc=local + ``` - **Examples:** - ``` - ou=users,dc=example,dc=com - ou=employees,ou=people,dc=company,dc=com - cn=users,dc=company,dc=local - ``` + - **User Search Filter (optional)** - - **User Search Filter (optional)** + This tells Plane how to find users when they try to sign in. Use `{username}` as a placeholder - Plane replaces it with whatever the user types in the login field. - This tells Plane how to find users when they try to sign in. Use `{username}` as a placeholder - Plane replaces it with whatever the user types in the login field. + **Common filters by directory type:** - **Common filters by directory type:** + | Directory Type | Filter | What it does | + | ---------------- | -------------------------------- | -------------------------------- | + | OpenLDAP | `(uid={username})` | Searches by user ID | + | Active Directory | `(sAMAccountName={username})` | Searches by Windows login name | + | Active Directory | `(userPrincipalName={username})` | Searches by email-style username | + | Any | `(mail={username})` | Searches by email address | - | Directory Type | Filter | What it does | - |----------------|--------|--------------| - | OpenLDAP | `(uid={username})` | Searches by user ID | - | Active Directory | `(sAMAccountName={username})` | Searches by Windows login name | - | Active Directory | `(userPrincipalName={username})` | Searches by email-style username | - | Any | `(mail={username})` | Searches by email address | + **Default:** If you don't specify a filter, Plane uses `(uid={username})`. - **Default:** If you don't specify a filter, Plane uses `(uid={username})`. + **Combined filter example:**\ + If you want users to sign in with either their username OR email: - **Combined filter example:**\ - If you want users to sign in with either their username OR email: - ``` - (|(uid={username})(mail={username})) - ``` + ``` + (|(uid={username})(mail={username})) + ``` - - **User Attributes (optional)** + - **User Attributes (optional)** - List the LDAP attributes Plane should retrieve to create user profiles. Plane uses these to populate the user's display name and email in Plane. + List the LDAP attributes Plane should retrieve to create user profiles. Plane uses these to populate the user's display name and email in Plane. - **How Plane maps attributes:** + **How Plane maps attributes:** - | Plane needs | LDAP provides (in order of preference) | - |-------------|----------------------------------------| - | Email address | `mail`, `userPrincipalName` | - | First name | `givenName`, or first part of `cn` if `givenName` is missing | - | Last name | `sn`, or last part of `cn` if `sn` is missing | + | Plane needs | LDAP provides (in order of preference) | + | ------------- | ------------------------------------------------------------ | + | Email address | `mail`, `userPrincipalName` | + | First name | `givenName`, or first part of `cn` if `givenName` is missing | + | Last name | `sn`, or last part of `cn` if `sn` is missing | - **Recommended setting:** - ``` - mail,cn,givenName,sn,userPrincipalName,displayName - ``` + **Recommended setting:** - **Default:** If you don't specify attributes, Plane uses `mail,cn,givenName,sn`. + ``` + mail,cn,givenName,sn,userPrincipalName,displayName + ``` - - **Provider Name (optional)** + **Default:** If you don't specify attributes, Plane uses `mail,cn,givenName,sn`. - This is the label that appears on Plane's login button. Choose something your team will recognize. + - **Provider Name (optional)** - **Examples:** - - `Corporate Directory` - - `Company SSO` - - `Active Directory` + This is the label that appears on Plane's login button. Choose something your team will recognize. - **Default:** If you don't specify a name, Plane shows `LDAP`. + **Examples:** + - `Corporate Directory` + - `Company SSO` + - `Active Directory` - The login button will display as: **"Sign in with [Provider Name]"** + **Default:** If you don't specify a name, Plane shows `LDAP`. + + The login button will display as: **"Sign in with [Provider Name]"** 5. Click **Save changes** to apply your LDAP settings. Plane will validate the connection to your LDAP server. 6. Users will see **Sign in with LDAP** on Plane's login page and can use their directory credentials to sign in. - ![Sign in using LDAP](/images/ldap/sign-in-ldap.webp) + ![Sign in using LDAP](/images/ldap/sign-in-ldap.webp) ## How LDAP authentication works LDAP authentication in Plane works through a two-phase process. First, Plane locates the user in your directory, then it verifies their credentials. This separation is fundamental to how LDAP works and explains why you need both a service account (Bind DN) and the user's own credentials. ### The service account pattern + Unlike simpler authentication systems where you might directly check a username and password against a database, LDAP uses what's called a "bind" operation. Plane needs to authenticate twice: once as itself (using the Bind DN) to search your directory, and once as the user to verify their password. This is why you configure a Bind DN and password - it's Plane's identity on your LDAP server. Think of it as Plane introducing itself before asking about your users. The Bind DN only needs read access because Plane is just looking up information, never modifying your directory. ### The authentication flow + When a user tries to sign in, here's what happens behind the scenes: -**Connection and service authentication** +**Connection and service authentication** Plane connects to your LDAP server using the Server URI, then authenticates using the Bind DN credentials. If this fails, no users can sign in; the service account must work first. **User search** @@ -162,6 +169,7 @@ Once authentication succeeds, Plane retrieves the User Attributes you configured Finally, Plane creates a session for the user and redirects them into the workspace. From this point on, the user's session works identically to any other Plane session. The LDAP interaction is complete. ### Why search filters matter + The User Search Filter determines sign-in flexibility. A simple filter like `(uid={username})` requires exact usernames, but you can make it more flexible: `(mail={username})` lets users sign in with email @@ -170,6 +178,7 @@ The User Search Filter determines sign-in flexibility. A simple filter like `(ui Filters can also restrict access: `(&(uid={username})(memberOf=cn=plane-users,ou=groups,dc=company,dc=com))` only permits specific group members. ### The role of user attributes + User Attributes tell Plane which LDAP fields to retrieve after authentication. This is separate from the search filter. The filter finds the user, the attributes populate their profile. -Plane specifically looks for email addresses (required) and names (optional). If your LDAP server uses different attribute names, you need to include them. \ No newline at end of file +Plane specifically looks for email addresses (required) and names (optional). If your LDAP server uses different attribute names, you need to include them. diff --git a/docs/self-hosting/govern/oidc-sso.md b/docs/self-hosting/govern/oidc-sso.md index be152bc..94e2a77 100644 --- a/docs/self-hosting/govern/oidc-sso.md +++ b/docs/self-hosting/govern/oidc-sso.md @@ -4,7 +4,6 @@ description: Setup OIDC SSO authentication for Plane. Configure OpenID Connect s keywords: plane oidc, openid connect, sso configuration, single sign-on, oidc provider, enterprise sso, self-hosting --- - # OIDC SSO Plane enables custom SSO via any identity provider with an official and supported implementation of OIDC standards. This page cites examples from Okta, but we will soon publish provider-specific instructions in phases. @@ -18,21 +17,21 @@ You will need to configure values on your IdP first and then on Plane later. Create a Plane client or application per your IdP's documentation and configure ↓. ::: tip - `domain.tld` is the domain that you have hosted your Plane app on. +`domain.tld` is the domain that you have hosted your Plane app on. ::: -| **Config** | **Key** | -|----------------|-------------------------------------------------------| -| Origin URL | `http(s)://domain.tld/auth/oidc/` | -| Callback URL | `http(s)://domain.tld/auth/oidc/callback/` | -| Logout URL | `http(s)://domain.tld/auth/oidc/logout/` | +| **Config** | **Key** | +| ------------ | ------------------------------------------ | +| Origin URL | `http(s)://domain.tld/auth/oidc/` | +| Callback URL | `http(s)://domain.tld/auth/oidc/callback/` | +| Logout URL | `http(s)://domain.tld/auth/oidc/logout/` | ### On Plane Go to `/god-mode/authentication/oidc` on your Plane app and find the configs ↓. ::: tip - Your IdP will generate some of the following configs for you. Others, you will specify yourself. Just copy them over to each field. +Your IdP will generate some of the following configs for you. Others, you will specify yourself. Just copy them over to each field. ::: ![OIDC Configuration](/images/custom-sso/oidc-oauth.png) @@ -59,6 +58,6 @@ Go to `/god-mode/authentication/oidc` on your Plane app and find the configs ↓ To test if this URL is right, see if clicking the `Login with ` button brings up your IdP's authentication screen. - ![Login with Okta](/images/custom-sso/okta-signin.webp) + ![Login with Okta](/images/custom-sso/okta-signin.webp) -- Finally, choose a name for your IdP on Plane so you can recognize this set of configs. \ No newline at end of file +- Finally, choose a name for your IdP on Plane so you can recognize this set of configs. diff --git a/docs/self-hosting/govern/private-bucket.md b/docs/self-hosting/govern/private-bucket.md index 7f2db49..2298f9f 100644 --- a/docs/self-hosting/govern/private-bucket.md +++ b/docs/self-hosting/govern/private-bucket.md @@ -4,7 +4,6 @@ description: Switch Plane storage from public to private S3 buckets. Secure file keywords: plane private bucket, s3 private storage, signed urls, secure file uploads, storage migration, self-hosting, plane storage security --- - # Switch from public to private buckets • Commercial Edition ::: warning @@ -30,6 +29,7 @@ Simply run the command ↓. ```bash docker exec -it python manage.py update_bucket ``` + A successful run keeps any public files you already have accessible while moving you to private storage. ## For external storage • S3 or S3 compatible @@ -43,6 +43,7 @@ This step is critical if you are using external storage to ensure continued func ::: Here’s a sample CORS policy for your reference. Just replace `` with your actual domain and apply the policy to your bucket. + ```bash [ { @@ -78,51 +79,53 @@ Don't start from here if you haven't updated your CORS policy. To migrate from public to private bucket storage, follow the instructions below: -1. First, make sure you have the following permissions on your S3 bucket. If you don't, make changes to get those permissions on your bucket first. - - **s3:GetObject** - So you can access your public files so far To access existing objects publicly +1. First, make sure you have the following permissions on your S3 bucket. If you don't, make changes to get those permissions on your bucket first. + - **s3:GetObject** + So you can access your public files so far To access existing objects publicly - - **s3:ListBucket** - So you can apply policies to your bucket for public access + - **s3:ListBucket** + So you can apply policies to your bucket for public access - - **s3:PutObject** - So you can create new files + - **s3:PutObject** + So you can create new files - - **s3:PutBucketPolicy** - So you can update your buckets' policy + - **s3:PutBucketPolicy** + So you can update your buckets' policy 2. Now, run the command ↓. - ```bash - docker exec -it python manage.py update_bucket - ``` - ::: tip - 1. If the command finds the necessary permissions missing, it will generate a `permissions.json` file which you can use to update your bucket policy manually. Here’s how the `permissions.json` file should look. - - ```bash - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": "*", - "Action": "s3:GetObject", - "Resource": [ - "arn:aws:s3:::/", - "arn:aws:s3:::/" - ] - } - ] - } - ``` - - 2. To copy the `permissions.json` file to the local machine, run the command ↓. - - ```bash - docker cp :/code/permissions.json . - ``` - - ::: + + ```bash + docker exec -it python manage.py update_bucket + ``` + + ::: tip + 1. If the command finds the necessary permissions missing, it will generate a `permissions.json` file which you can use to update your bucket policy manually. Here’s how the `permissions.json` file should look. + + ```bash + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": "*", + "Action": "s3:GetObject", + "Resource": [ + "arn:aws:s3:::/", + "arn:aws:s3:::/" + ] + } + ] + } + ``` + + 2. To copy the `permissions.json` file to the local machine, run the command ↓. + + ```bash + docker cp :/code/permissions.json . + ``` + + ::: ## Troubleshoot -- [Bucket policy exceeds size limit](/self-hosting/troubleshoot/storage-errors#bucket-policy-exceeds-size-limit) \ No newline at end of file +- [Bucket policy exceeds size limit](/self-hosting/troubleshoot/storage-errors#bucket-policy-exceeds-size-limit) diff --git a/docs/self-hosting/govern/reset-password.md b/docs/self-hosting/govern/reset-password.md index ac8c248..fa1c45a 100644 --- a/docs/self-hosting/govern/reset-password.md +++ b/docs/self-hosting/govern/reset-password.md @@ -4,24 +4,28 @@ description: Reset user and admin passwords for self-hosted Plane. Recover acces keywords: plane password reset, admin password recovery, plane account recovery, self-hosting, plane login issues --- - # Reset password + Users can reset their password through the terminal of the Plane application. You need to login to backend docker container and run the below command for resetting a user’s password. 1. Get the container id for **plane-api**. - ```bash - docker ps - ``` + +```bash +docker ps +``` 2. Log in to the container. - ```bash - docker exec -it /bin/sh - ``` + +```bash +docker exec -it /bin/sh +``` 3. Run the reset password command. - ```bash - python manage.py reset_password - ``` + +```bash + python manage.py reset_password +``` + ::: tip The email should be of an already existing user on the Plane application. If the email is not attached to any user the command will throw an error. -::: \ No newline at end of file +::: diff --git a/docs/self-hosting/govern/reverse-proxy.md b/docs/self-hosting/govern/reverse-proxy.md index 5bde9a7..fbc4046 100644 --- a/docs/self-hosting/govern/reverse-proxy.md +++ b/docs/self-hosting/govern/reverse-proxy.md @@ -4,32 +4,34 @@ description: Configure Nginx, Caddy, or Traefik as a reverse proxy for self-host keywords: plane reverse proxy, nginx proxy, traefik, caddy, upstream proxy, proxy configuration, self-hosting --- - # Configure external reverse proxy -This page provides configuration for setting up an external reverse proxy with Plane. +This page provides configuration for setting up an external reverse proxy with Plane. ## Plane environment setup Make sure to update the following environment variables in your plane.env file. 1. Assign free ports for Plane to listen on. Update the following variables with two different unsused ports: - ```bash - LISTEN_HTTP_PORT= - LISTEN_HTTPS_PORT= - ``` + + ```bash + LISTEN_HTTP_PORT= + LISTEN_HTTPS_PORT= + ``` 2. Update the SITE_ADDRESS variable to `:80` - ```bash - SITE_ADDRESS=:80 - ``` - This is required so that generated links and redirects work correctly behind the proxy: + + ```bash + SITE_ADDRESS=:80 + ``` + + This is required so that generated links and redirects work correctly behind the proxy: 3. After editing plane.env, restart your instance so the changes take effect: ```bash sudo prime-cli restart ``` - + ::: warning **Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. ::: @@ -39,29 +41,27 @@ Make sure to update the following environment variables in your plane.env file. 1. Choose the appropriate [configuration template](#configuration-templates) for your reverse proxy. 2. Replace the following placeholders: - - `` - Your Plane application's domain name. - - `` - The IP address where Plane is hosted. - - `` - The port Plane listens on. - + - `` + Your Plane application's domain name. + - `` + The IP address where Plane is hosted. + - `` + The port Plane listens on. 3. For Traefik, also update `your-email@example.com` with your email. Ensure that your reverse proxy setup follows the template provided, and that the forwarded headers and ports are correctly set to match the environment variable configuration. - ## Configuration templates All configurations include: + - Automatic HTTPS redirection - WebSocket support - Standard proxy headers - SSL/TLS certificate management - - NGINX: Uses Certbot - - Caddy: Handles certificates automatically - - Traefik: Uses Let’s Encrypt - + - NGINX: Uses Certbot + - Caddy: Handles certificates automatically + - Traefik: Uses Let’s Encrypt ::: details NGINX configuration @@ -71,13 +71,13 @@ server { location / { proxy_pass http://:/; - + # Set headers for proxied request proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header X-Forwarded-Host $host; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Real-IP $remote_addr; - + proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $http_host; @@ -106,8 +106,8 @@ server { ::: - ::: details Caddy configuration + ```bash { tls { @@ -122,7 +122,7 @@ server { header_up X-Real-IP {remote_host} header_up X-Forwarded-For {remote_host} header_up Host {http.request.host} - + header_up Upgrade {http.request.header.Upgrade} header_up Connection {http.request.header.Connection} @@ -142,6 +142,7 @@ server { ::: ::: details Traefik configuration + ```bash entryPoints: web: @@ -152,7 +153,7 @@ entryPoints: to: websecure scheme: https permanent: true - + websecure: address: ":443" @@ -189,7 +190,7 @@ providers: dialTimeout: 30s responseHeaderTimeout: 30s idleConnTimeout: 90s - + middlewares: headers: headers: @@ -197,4 +198,5 @@ providers: X-Forwarded-Proto: "https" X-Real-IP: "{{ .RemoteAddr }}" ``` -::: \ No newline at end of file + +::: diff --git a/docs/self-hosting/govern/saml-sso.md b/docs/self-hosting/govern/saml-sso.md index 842c99c..577a6b9 100644 --- a/docs/self-hosting/govern/saml-sso.md +++ b/docs/self-hosting/govern/saml-sso.md @@ -4,7 +4,6 @@ description: Configure SAML SSO authentication for Plane. Setup Security Asserti keywords: plane saml, saml sso, enterprise sso, saml configuration, identity provider, okta, azure ad, self-hosting --- - # SAML SSO Plane enables custom SSO via any identity provider with an official and supported implementation of SAML standards. This page cites examples from Okta, but we will soon publish provider-specific instructions in phases. @@ -13,18 +12,18 @@ Plane enables custom SSO via any identity provider with an official and supporte You will need to configure values on your IdP first and then on Plane later. ::: tip - `domain.tld` is the domain that you have hosted your Plane app on. +`domain.tld` is the domain that you have hosted your Plane app on. ::: ### On your preferred IdP Create a Plane client or application per your IdP's documentation and configure ↓. -| **Config** | **Value** | -|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------| -| Entity ID

Metadata that identifies Plane as an authorized service on your IdP | `http(s)://domain.tld/auth/saml/` | -| ACS URL

Assertion Consumer service that your IdP will redirect to after successful authentication by a user

This is roughly the counterpart of the `Callback URL` in SAML set-ups. | `http(s)://domain.tld/auth/saml/callback/`

Plane supports HTTP-POST bindings. | -| SLS URL

Single Logout Service that your IdP will recognize to end a Plane session when a user logs out

This is roughly the counterpart of the `Logout URL` in SAML set-ups. | `http(s)://domain.tld/auth/saml/logout/` | +| **Config** | **Value** | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------- | +| Entity ID

Metadata that identifies Plane as an authorized service on your IdP | `http(s)://domain.tld/auth/saml/` | +| ACS URL

Assertion Consumer service that your IdP will redirect to after successful authentication by a user

This is roughly the counterpart of the `Callback URL` in SAML set-ups. | `http(s)://domain.tld/auth/saml/callback/`

Plane supports HTTP-POST bindings. | +| SLS URL

Single Logout Service that your IdP will recognize to end a Plane session when a user logs out

This is roughly the counterpart of the `Logout URL` in SAML set-ups. | `http(s)://domain.tld/auth/saml/logout/` | ::: tip When setting these values up on the IdP, it’s important to remember Plane does not need to provide a signing certificate like other service providers. @@ -32,18 +31,19 @@ When setting these values up on the IdP, it’s important to remember Plane does ### Let your IdP identify your users on Plane. -| **Config** | **Value** | -|----------------------------|--------------------------------------------------------| -| Name ID format | emailAddress

By default, your IdP should send back a username, but Plane recognizes email addresses as the username. Set the value to the above so Plane recognizes the user correctly. +| **Config** | **Value** | +| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Name ID format | emailAddress

By default, your IdP should send back a username, but Plane recognizes email addresses as the username. Set the value to the above so Plane recognizes the user correctly. | + ### Set additional attribute values. By default, your IdP will send the value listed under `Property`. You have to map it to the SAML attribute Plane recognizes. -| **Default property value** | **Plane SAML attribute** | -|----------------------------|--------------------------------------------| -| user.firstName | first_name | -| user.lastName | last_name | -| user.email | email | +| **Default property value** | **Plane SAML attribute** | +| -------------------------- | ------------------------ | +| user.firstName | first_name | +| user.lastName | last_name | +| user.email | email | ::: info **first_name** and **last_name** are optional but recommended for complete user profiles. If these are not provided, Plane will create the user account with just the email address. @@ -51,7 +51,7 @@ By default, your IdP will send the value listed under `Property`. You have to ma ::: ::: tip - Depending on your IdP, you will have to find both the `Name ID format` and the three other user identification properties on different screens. Please refer to your IdP's documentation when configuring these up on your IdP. Additionally, you may have to configure the IdP to sign assertions. Irrespective of that, you have to copy the signing certificate from the IdP. +Depending on your IdP, you will have to find both the `Name ID format` and the three other user identification properties on different screens. Please refer to your IdP's documentation when configuring these up on your IdP. Additionally, you may have to configure the IdP to sign assertions. Irrespective of that, you have to copy the signing certificate from the IdP. ::: ### On Plane @@ -59,7 +59,7 @@ By default, your IdP will send the value listed under `Property`. You have to ma ![SAML Configuration](/images/custom-sso/saml-oauth.png) ::: tip - You will find all of the values for the fields below in the `/metadata` endpoint your IdP generates for the Plane app or client. +You will find all of the values for the fields below in the `/metadata` endpoint your IdP generates for the Plane app or client. ::: - Copy the `ENTITY_ID` for the Plane client or app you just created over from your IdP and paste it in the field for it. @@ -76,4 +76,4 @@ By default, your IdP will send the value listed under `Property`. You have to ma ![Log-in Screen](/images/custom-sso/instance-login.png) -- Finally, paste the signing certificate from your IdP that you got in the last step of setting up your Plane client or app on your IdP above and paste it in the field for it. \ No newline at end of file +- Finally, paste the signing certificate from your IdP that you got in the last step of setting up your Plane client or app on your IdP above and paste it in the field for it. diff --git a/docs/self-hosting/manage/backup-restore.md b/docs/self-hosting/manage/backup-restore.md index 7a5f137..807c7ee 100644 --- a/docs/self-hosting/manage/backup-restore.md +++ b/docs/self-hosting/manage/backup-restore.md @@ -4,7 +4,6 @@ description: Backup and restore Plane data. Complete guide for backing up databa keywords: plane backup, plane restore, database backup, postgresql backup, data recovery, plane data export, self-hosting --- - # Backup and restore data Backing up your data regularly helps prevent data loss and allows you to restore your system quickly if necessary. Follow these instructions to back up and restore your data using Plane’s command-line interface. @@ -16,27 +15,31 @@ Backing up your data regularly helps prevent data loss and allows you to restore ::: Create a backup of your Plane data with ↓: + ```bash sudo prime-cli backup ``` This command initiates a full backup of all critical data, storing it in the default backup location at: + ```bash /opt/plane/backups ``` + Each backup file will be timestamped to ensure you can easily identify the latest or a specific backup if needed. ## Backup plane.env + If you need to back up only the `plane.env` file, you'll need to do it manually. Here’s how: 1. Navigate to the `/opt/plane` folder on your machine or server where Plane is installed.. 2. Locate the `plane.env` file. 3. Copy this file to a different location as a backup, so you can restore it if needed. - ## Restore data You can restore your data from a previous backup with ↓: + ```bash sudo prime-cli restore ``` @@ -48,9 +51,11 @@ This command prompts the restoration process, which will overwrite the current d #### Backup data To create a backup, start by running the setup script: + ```bash ./setup.sh ``` + You’ll see a menu of options—just type 7 to select "Backup Data." ``` @@ -66,6 +71,7 @@ Select an Action you want to perform: Action [2]: 7 ``` + The system will start backing up the PostgreSQL, Redis, and upload data: ``` @@ -75,69 +81,72 @@ Backing Up plane-app_uploads Backup completed successfully. Backup files are stored in /....../plane-app/backup/20240502-1120 ``` + The backup files are stored locally, so you can copy them to an external storage service if needed for extra security. #### Backup plane.env + If you need to back up only the `plane.env` file, you'll need to do it manually. Here’s how: 1. Navigate to the folder on your machine or server where Plane is installed.. 2. Locate the `plane.env` file. 3. Copy this file to a different location as a backup, so you can restore it if needed. -*** +--- #### Restore data + Follow these steps to restore data from a backup: 1. Make sure Plane-CE is installed and started, then stop it. This ensures the necessary Docker volumes are ready. 2. Use the command ↓ to download the restore script. It’s easiest to save it in the same directory as `setup.sh`. - ```bash - curl -fsSL -o restore.sh https://raw.githubusercontent.com/makeplane/plane/refs/heads/preview/deployments/cli/community/restore.sh - chmod +x restore.sh - ``` + ```bash + curl -fsSL -o restore.sh https://raw.githubusercontent.com/makeplane/plane/refs/heads/preview/deployments/cli/community/restore.sh + chmod +x restore.sh + ``` 3. Now, run the command ↓ to restore your data, specifying the path to your backup folder (the folder with the `*.tar.gz` files): - ```bash - ./restore.sh - ``` + ```bash + ./restore.sh + ``` - Here’s an example output for restoring from /opt/plane-selfhost/plane-app/backup/20240722-0914: + Here’s an example output for restoring from /opt/plane-selfhost/plane-app/backup/20240722-0914: - ```bash - -------------------------------------------- - ____ _ ///////// - | _ \| | __ _ _ __ ___ ///////// - | |_) | |/ _` | '_ \ / _ \ ///// ///// - | __/| | (_| | | | | __/ ///// ///// - |_| |_|\__,_|_| |_|\___| //// - //// - -------------------------------------------- - Project management tool from the future - -------------------------------------------- - Found /opt/plane-selfhost/plane-app/backup/20240722-0914/pgdata.tar.gz - .....Restoring plane-app_pgdata - .....Successfully restored volume plane-app_pgdata from pgdata.tar.gz + ```bash + -------------------------------------------- + ____ _ ///////// + | _ \| | __ _ _ __ ___ ///////// + | |_) | |/ _` | '_ \ / _ \ ///// ///// + | __/| | (_| | | | | __/ ///// ///// + |_| |_|\__,_|_| |_|\___| //// + //// + -------------------------------------------- + Project management tool from the future + -------------------------------------------- + Found /opt/plane-selfhost/plane-app/backup/20240722-0914/pgdata.tar.gz + .....Restoring plane-app_pgdata + .....Successfully restored volume plane-app_pgdata from pgdata.tar.gz - Found /opt/plane-selfhost/plane-app/backup/20240722-0914/redisdata.tar.gz - .....Restoring plane-app_redisdata - .....Successfully restored volume plane-app_redisdata from redisdata.tar.gz + Found /opt/plane-selfhost/plane-app/backup/20240722-0914/redisdata.tar.gz + .....Restoring plane-app_redisdata + .....Successfully restored volume plane-app_redisdata from redisdata.tar.gz - Found /opt/plane-selfhost/plane-app/backup/20240722-0914/uploads.tar.gz - .....Restoring plane-app_uploads - .....Successfully restored volume plane-app_uploads from uploads.tar.gz + Found /opt/plane-selfhost/plane-app/backup/20240722-0914/uploads.tar.gz + .....Restoring plane-app_uploads + .....Successfully restored volume plane-app_uploads from uploads.tar.gz - Restore completed successfully. - ``` + Restore completed successfully. + ``` 4. Start your Plane instance again with ↓: - ```bash - ./setup.sh start - ``` + ```bash + ./setup.sh start + ``` That’s it! You’re back up and running with your restored data. -::: \ No newline at end of file +::: diff --git a/docs/self-hosting/manage/community-to-airgapped.md b/docs/self-hosting/manage/community-to-airgapped.md index 7d7afd1..b7dece6 100644 --- a/docs/self-hosting/manage/community-to-airgapped.md +++ b/docs/self-hosting/manage/community-to-airgapped.md @@ -4,7 +4,6 @@ description: Deploy Plane in airgapped environment without internet access. Comp keywords: plane community to airgapped, edition upgrade, airgapped migration, offline deployment, air-gapped plane, self-hosting --- - # Upgrade from Community to Airgapped Edition This guide walks you through migrating your existing Plane Community Edition data to an air-gapped environment. You'll backup your current installation, transfer the data, and restore it in your air-gapped setup. @@ -22,49 +21,58 @@ Make sure you already have Commercial Airgapped Edition installed on a fresh mac ## Backup data on Community instance 1. Download the latest version of `setup.sh`. - ```bash - curl -fsSL https://github.com/makeplane/plane/releases/latest/download/setup.sh -o setup.sh - ``` + +```bash +curl -fsSL https://github.com/makeplane/plane/releases/latest/download/setup.sh -o setup.sh +``` 2. Run the setup.sh backup script to take the backup of the Community Edition instance. - ```bash - ./setup.sh backup - ``` - This will create a backup of the plane community instance in the `backup/` folder with the timestamp as the folder name. - ```bash - backup/ - └── 20250605-0938 - ├── pgdata.tar.gz - ├── rabbitmq_data.tar.gz - ├── redisdata.tar.gz - └── uploads.tar.gz - ``` + +```bash +./setup.sh backup +``` + +This will create a backup of the plane community instance in the `backup/` folder with the timestamp as the folder name. + +```bash +backup/ +└── 20250605-0938 + ├── pgdata.tar.gz + ├── rabbitmq_data.tar.gz + ├── redisdata.tar.gz + └── uploads.tar.gz +``` ## Restore data on Airgapped instance 1. Download the latest version of `restore-airgapped.sh` - ```bash - curl -fsSL https://github.com/makeplane/plane/releases/latest/download/restore-airgapped.sh -o restore-airgapped.sh - chmod +x restore-airgapped.sh - ``` - This allows you to restore the Community Edition data to the Commercial Airgapped instance. + + ```bash + curl -fsSL https://github.com/makeplane/plane/releases/latest/download/restore-airgapped.sh -o restore-airgapped.sh + chmod +x restore-airgapped.sh + ``` + + This allows you to restore the Community Edition data to the Commercial Airgapped instance. 2. Copy the `restore-airgapped.sh` script into your backup folder. 3. Move your entire backup folder to the server running the Commercial Airgapped Edition. 4. Open terminal, and execute the following command: - ```bash - sudo bash restore-airgapped.sh ./20250605-0938 - ``` - This will prompt you to enter the Commercial Airgapped Edition installation folder using whatever secure method works in your environment. + + ```bash + sudo bash restore-airgapped.sh ./20250605-0938 + ``` + + This will prompt you to enter the Commercial Airgapped Edition installation folder using whatever secure method works in your environment. 5. After the data restore is finished, start the instance. - ```bash - cd - sudo docker compose -f docker-compose.yml --env-file plane.env up -d - ``` - You can now access the Commercial Airgapped instance at `http://` + ```bash + cd + sudo docker compose -f docker-compose.yml --env-file plane.env up -d + ``` + + You can now access the Commercial Airgapped instance at `http://` -Once your migration is complete, verify that all your projects, issues, and team data have been successfully transferred to your air-gapped environment. \ No newline at end of file +Once your migration is complete, verify that all your projects, issues, and team data have been successfully transferred to your air-gapped environment. diff --git a/docs/self-hosting/manage/manage-licenses/activate-airgapped.md b/docs/self-hosting/manage/manage-licenses/activate-airgapped.md index 0363d5c..aed410d 100644 --- a/docs/self-hosting/manage/manage-licenses/activate-airgapped.md +++ b/docs/self-hosting/manage/manage-licenses/activate-airgapped.md @@ -4,7 +4,6 @@ description: Activate and configure your Plane Airgapped Edition license. Offlin keywords: plane airgapped license, offline activation, air-gapped deployment, plane license key, self-hosting --- - # Activate Airgapped Edition license Once your air-gapped installation is running, you'll need to activate your workspace with the license file. @@ -12,11 +11,11 @@ Once your air-gapped installation is running, you'll need to activate your works 1. Login to the [Prime portal](https://prime.plane.so/licenses) with the same email address you used to purchase the paid plan. 2. Go to [Manage licenses](https://prime.plane.so/licenses). 3. Click **Download license** to download the license file for your Plane version. - ![Download license file](/images/activate-license/download-license.webp) + ![Download license file](/images/activate-license/download-license.webp) 4. Navigate to the [Workspace Settings](https://docs.plane.so/core-concepts/workspaces/overview#workspace-settings) in the Plane application. 5. Select **Billing and plans** on the right pane. 6. Click the **Activate this workspace** button. - ![Upload license file](/images/activate-license/upload-airgapped-license-file.webp) + ![Upload license file](/images/activate-license/upload-airgapped-license-file.webp) 7. Upload the license file to activate your workspace. -You now have Plane running in your air-gapped environment. If you run into any issues, check the logs, or reach out to our support team for assistance. \ No newline at end of file +You now have Plane running in your air-gapped environment. If you run into any issues, check the logs, or reach out to our support team for assistance. diff --git a/docs/self-hosting/manage/manage-licenses/activate-enterprise.md b/docs/self-hosting/manage/manage-licenses/activate-enterprise.md index ac04ca4..617c571 100644 --- a/docs/self-hosting/manage/manage-licenses/activate-enterprise.md +++ b/docs/self-hosting/manage/manage-licenses/activate-enterprise.md @@ -4,7 +4,6 @@ description: Activate your Plane Enterprise Edition license. Enable advanced fea keywords: plane enterprise license, license activation, enterprise edition, plane enterprise features, self-hosting --- - # Activate Enterprise license Enterprise plan licenses are activated at the instance level through God Mode, not through individual workspace settings. This gives instance administrators centralized control over Enterprise features across all workspaces. @@ -21,4 +20,4 @@ Enterprise plan licenses are activated at the instance level through God Mode, n ![Activate Enterprise license](/images/activate-license/activate-enterprise-plan.webp) -Once activated, Enterprise features become available across all workspaces on your instance. \ No newline at end of file +Once activated, Enterprise features become available across all workspaces on your instance. diff --git a/docs/self-hosting/manage/manage-licenses/activate-pro-and-business.md b/docs/self-hosting/manage/manage-licenses/activate-pro-and-business.md index 76df737..80ffa30 100644 --- a/docs/self-hosting/manage/manage-licenses/activate-pro-and-business.md +++ b/docs/self-hosting/manage/manage-licenses/activate-pro-and-business.md @@ -4,27 +4,28 @@ description: Activate your Plane Pro or Business Edition license. Upgrade from C keywords: plane pro license, plane business license, license activation, commercial edition, plane upgrade, self-hosting --- - # Activate Pro and Business licenses -Pro and Business plan licenses are activated at the workspace level as each license is tied to a specific workspace. +Pro and Business plan licenses are activated at the workspace level as each license is tied to a specific workspace. ## Activate your license + Activate a paid plan license on your self-hosted Plane instance using a license key from the Prime portal. 1. Login to the [Prime portal](https://prime.plane.so/licenses) with the same email address you used to purchase one of our paid plans. -2. Go to [Manage licenses](https://prime.plane.so/licenses). Copy the value of the **License key** for the license you want to activate. +2. Go to [Manage licenses](https://prime.plane.so/licenses). Copy the value of the **License key** for the license you want to activate. ![Manage licenses](https://media.docs.plane.so/activate-license/copy-license-key.webp#hero) - + > [!TIP] > Click the **Get more licenses** button as in the image above on the [Prime portal](https://prime.plane.so/licenses/plans) to buy more licenses. - -3. On the Plane app, navigate to **Workspace Settings > Billing and plans** -4. Click the **Activate this Workspace** button. + +3. On the Plane app, navigate to **Workspace Settings > Billing and plans** +4. Click the **Activate this Workspace** button. ![Activate workspace](https://media.docs.plane.so/activate-license/enter-license-key-selfhosted.webp#hero-tr) + 5. Paste the license key in the **Enter license key** box. 6. Click **Activate**. You will see a confirmation. 7. That's it. To check your plan at any time and find additional details, just go to the **Billing and plans** tab in **Workspace Settings**. @@ -57,7 +58,7 @@ Here’s how to delink your license key from a workspace: 2. Click **Delink license key**. This will release the license key, making it available for use on another machine or workspace. ![Delink license key](https://media.docs.plane.so/activate-license/delink-license-key.webp#hero-tl) + 3. Restart the instance using `prime-cli restart`. 4. If you’re switching machines or reinstalling the Commercial edition, see [Move Plane instance to another server](https://developers.plane.so/self-hosting/manage/migrate-plane). 5. Ensure you are connected to the internet and reactivate the new workspace using the license key you delinked earlier. - diff --git a/docs/self-hosting/manage/migrate-plane.md b/docs/self-hosting/manage/migrate-plane.md index eec5e50..8e6f2ed 100644 --- a/docs/self-hosting/manage/migrate-plane.md +++ b/docs/self-hosting/manage/migrate-plane.md @@ -4,12 +4,12 @@ description: Migrate Plane between servers or environments. Guide for moving you keywords: plane migration, server migration, plane data transfer, infrastructure move, plane backup restore, self-hosting --- - # Move Plane instance to a new server -Switching to another machine is straightforward on the Commercial Edition. +Switching to another machine is straightforward on the Commercial Edition. ## Prerequisites + Before we dive in, ensure: - You’re running Plane's Commercial Edition. @@ -21,34 +21,39 @@ If you need to change your domain during migration, contact our support team for ::: ## Steps -1. **Delink licenses** -Log in to Plane on your current server. Head to each paid workspace like Pro or Business and [delink the licenses](/self-hosting/manage/manage-licenses/activate-pro-and-business#delink-license-key). This will free up the licenses for activation on your new server. Ideally, you have just one paid workspace. -2. **Backup data** -Create a backup of your Plane instance with ↓: - ```bash - prime-cli backup - ``` - This command will generate a backup file in the path: `/opt/plane/backups`. +1. **Delink licenses** + Log in to Plane on your current server. Head to each paid workspace like Pro or Business and [delink the licenses](/self-hosting/manage/manage-licenses/activate-pro-and-business#delink-license-key). This will free up the licenses for activation on your new server. Ideally, you have just one paid workspace. + +2. **Backup data** + Create a backup of your Plane instance with ↓: + +```bash +prime-cli backup +``` + +This command will generate a backup file in the path: `/opt/plane/backups`. + +::: warning +**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. +::: + +3. **Set up Plane on the new server** + Follow the [installation guide](/self-hosting/methods/docker-compose#install-plane) to deploy Plane on the new instance. - ::: warning - **Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. - ::: +4. **Transfer backup files** + Copy the `backups` folder from the old server, created in step 2, to the new server. Place the backup in the folder `/opt/plane`. -3. **Set up Plane on the new server** -Follow the [installation guide](/self-hosting/methods/docker-compose#install-plane) to deploy Plane on the new instance. +5. **Restore data** + On the new server, restore your data with ↓: -4. **Transfer backup files** -Copy the `backups` folder from the old server, created in step 2, to the new server. Place the backup in the folder `/opt/plane`. +```bash +prime-cli restore +``` -5. **Restore data** -On the new server, restore your data with ↓: - ```bash - prime-cli restore - ```` - Follow the prompts during the restore process to make sure everything is set up correctly. +Follow the prompts during the restore process to make sure everything is set up correctly. -6. **Reactivate license** -Finally, [reactivate your license keys](/self-hosting/manage/manage-licenses/activate-pro-and-business#activate-your-license) on the new instance. +6. **Reactivate license** + Finally, [reactivate your license keys](/self-hosting/manage/manage-licenses/activate-pro-and-business#activate-your-license) on the new instance. -This should get your Plane instance up and running on the new server. \ No newline at end of file +This should get your Plane instance up and running on the new server. diff --git a/docs/self-hosting/manage/prime-cli.md b/docs/self-hosting/manage/prime-cli.md index e6a9c12..1db2f14 100644 --- a/docs/self-hosting/manage/prime-cli.md +++ b/docs/self-hosting/manage/prime-cli.md @@ -4,12 +4,10 @@ description: Use Plane Prime CLI for managing your self-hosted instance. Command keywords: plane cli, prime cli, command line tools, plane management, plane setup commands, self-hosting, plane terminal --- - # Command line tools Our command-line tool is here to make managing your Plane instance simple. You can handle installs, upgrades, and general management without needing to be a Docker expert. - ## Prime CLI The Prime CLI provides commands for common tasks like configuring services, monitoring health, managing backups, and upgrading your Plane instance. @@ -18,90 +16,94 @@ The Prime CLI provides commands for common tasks like configuring services, moni **Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. ::: -Bring up the Prime CLI with ```sudo prime-cli``` from any directory on your machine. +Bring up the Prime CLI with `sudo prime-cli` from any directory on your machine. - The three operators you will use the most are: - - `start` - You will use this to start a service in the Docker network with the name of the service. + You will use this to start a service in the Docker network with the name of the service. - `stop` - You will use this to stop a service in the Docker network with the name of the service. + You will use this to stop a service in the Docker network with the name of the service. - `restart` - You will use this to restart a service in the Docker network with the name of the service as a `{param or flag}`. + You will use this to restart a service in the Docker network with the name of the service as a `{param or flag}`. - Often, you will want to monitor the health of your instance and see if some services are up or down. Use `monitor` to do that. - `healthcheck` is another useful utility that lets you see the status and errors, if any, of all running services -- `repair` automatically diagnoses and fixes common errors in your Plane instance. This command also resets all configuration values in the plane.env file to their defaults. +- `repair` automatically diagnoses and fixes common errors in your Plane instance. This command also resets all configuration values in the plane.env file to their defaults. - `update-cli` downloads and installs the latest version of Prime CLI. -::: tip -It is highly recommend to run this first before you download any Plane updates. The latest version of the CLI ensures your Plane upgrades happen smoothly. -::: + ::: tip + It is highly recommend to run this first before you download any Plane updates. The latest version of the CLI ensures your Plane upgrades happen smoothly. + ::: For more advanced admins that want greater control over their instance, the list of additional commands available on Prime CLI follow. -- `configure` -Brings up a step form to let you specify the following. - + +- `configure` + Brings up a step form to let you specify the following. + ::: details Steps to configure your instance -- `Listening port` -Specify the port that the built-in reverse proxy will use + +- `Listening port` + Specify the port that the built-in reverse proxy will use Default value: `80` - `Max file-upload size` -Specify a size in MBs for how big each file uploaded to your Plane app can be + Specify a size in MBs for how big each file uploaded to your Plane app can be Default value: `5 MB` - `External Postgres URL` -Specify the URL of your own hosted Postgres if you would like to change the database your Plane app uses. - + Specify the URL of your own hosted Postgres if you would like to change the database your Plane app uses. + Default database: Postgres 15.5 in the Docker container - `External Redis URL` -Specify the URL of your own hosted REdis if you would like to change the default Redis Plane ships with. + Specify the URL of your own hosted REdis if you would like to change the default Redis Plane ships with. Default Redis: Redis 7.2.4 - `External storage` -Specify your AWS S3 bucket's credentials in the format below to change storage from the default Plane ships with. + Specify your AWS S3 bucket's credentials in the format below to change storage from the default Plane ships with. - AWS Access Key ID - AWS Secret Access Key - AWS S3 Bucket Name - + Default storage: MinIO - -- Confirm your choices on the screen ↓. -This restarts your instance with the new configs. -::: -- `upgrade` +- Confirm your choices on the screen ↓. + This restarts your instance with the new configs. + ::: + +- `upgrade` checks your instance for available version upgrades and asks you for a confirmation before downloading the latest available version. + 1. Typing `YES` lets the CLI automatically download's the latest version and installs it. Then it restarts the instance to load the latest app. 2. Typing `NO` cancels the upgrade. -- `uninstall` +- `uninstall` uninstalls Plane. Before it goes through, it asks you for a confirmation. + 1. Typing `YES` lets the CLI clean up the `/opt/plane` folder, leaving behind the `/opt/plane/data` and `/opt/plane/logs` folders. 2. Typing `NO` cancels the uninstall. - ::: details Setup.sh script • Community Edition The setup script `setup.sh` provides a menu-driven interface to help you install and manage your Plane instance. #### Usage + To run the setup.sh script, use the following command in your terminal from the directory where the script is located: ```bash ./setup.sh ``` + This will launch an interactive menu with options to manage various aspects of your Plane instance. ```bash @@ -136,12 +138,11 @@ Select a Action you want to perform: > [!WARNING] > It's recommended to create a backup before upgrading your instance. See [Backup and restore](/self-hosting/manage/backup-restore#backup-data). - - **View Logs** Displays real-time logs of specific Plane services. See [View logs](/self-hosting/manage/view-logs) for more info. > [!TIP] - >Use **View Logs** to monitor service performance or troubleshoot issues. Press `CTRL+C` to exit the log view and return to the main menu. + > Use **View Logs** to monitor service performance or troubleshoot issues. Press `CTRL+C` to exit the log view and return to the main menu. - **Backup Data** Creates a backup of your current Plane installation, including all data. See [Backup and restore data](/self-hosting/manage/backup-restore#backup-data) for more info. @@ -153,4 +154,4 @@ Select a Action you want to perform: ## Troubleshoot -- [Failed to update Prime CLI](/self-hosting/troubleshoot/cli-errors#failed-to-update-prime-cli) \ No newline at end of file +- [Failed to update Prime CLI](/self-hosting/troubleshoot/cli-errors#failed-to-update-prime-cli) diff --git a/docs/self-hosting/manage/upgrade-from-0.13.2-0.14.0.md b/docs/self-hosting/manage/upgrade-from-0.13.2-0.14.0.md index f15dd88..845b8f2 100644 --- a/docs/self-hosting/manage/upgrade-from-0.13.2-0.14.0.md +++ b/docs/self-hosting/manage/upgrade-from-0.13.2-0.14.0.md @@ -4,52 +4,58 @@ description: Upgrade self-hosted Plane to the latest version. Step-by-step guide keywords: plane v0.14 upgrade, mandatory checkpoint, plane migration 0.13, breaking changes, version upgrade, self-hosting update --- - # Mandatory checkpoint at v0.14.0 If you’re upgrading from `v0.13.2` or below, there are some additional migration steps due to significant changes in the self-hosting setup. Follow these instructions to migrate your data to the new volume structure in `v0.14.0`. 1. First, stop the running `v0.13-2` (or older) instance of Plane. If it's still running, you might hit a "ports not available" error, which will prevent the `v0.14-0` containers from starting up correctly. - ```bash - docker compose down - ``` + + ```bash + docker compose down + ``` 2. Create a new folder for `v0.14-0` to ensure a clean installation. - ```bash - mkdir plane-selfhost - cd plane-selfhost - ``` + ```bash + mkdir plane-selfhost + cd plane-selfhost + ``` 3. Set up the environment variable for the `RELEASE` variable, then download and prepare the installation script: - ```bash - export RELEASE=v0.14-dev - curl -fsSL https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/install.sh | sed -e 's@BRANCH=${BRANCH:-master}@BRANCH='"$RELEASE"'@' -e 's@APP_RELEASE="stable"@APP_RELEASE='"$RELEASE"'@' > setup.sh - chmod +x setup.sh - ``` + + ```bash + export RELEASE=v0.14-dev + curl -fsSL https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/install.sh | sed -e 's@BRANCH=${BRANCH:-master}@BRANCH='"$RELEASE"'@' -e 's@APP_RELEASE="stable"@APP_RELEASE='"$RELEASE"'@' > setup.sh + chmod +x setup.sh + ``` 4. Execute the script to install Plane: - ```bash - ./setup.sh install - ``` + + ```bash + ./setup.sh install + ``` 5. Start up your new v0.14-0 Plane instance: - ```bash - ./setup.sh start - ``` + + ```bash + ./setup.sh start + ``` 6. Now stop the instance to initialize the new Docker volumes: - ```bash - ./setup.sh stop - ``` + + ```bash + ./setup.sh stop + ``` 7. Download the migration script: + ```bash curl -fsSL -o migrate.sh https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/migration-0.13-0.14.sh chmod +x migrate.sh ``` -8. Run the migration script: +8. Run the migration script: + ```bash ./migrate.sh ``` @@ -93,7 +99,8 @@ If you’re upgrading from `v0.13.2` or below, there are some additional migrati In this example, `plane-013-dev` is the prefix for `v0.13.2`, and `plane-app` is the prefix for `v0.14.0`. 10. Return to the original terminal, enter the source volume prefix `plane-013-dev` and destination volume prefix `plane-app`, and press ENTER: - ```bash + + ```bash Provide the Source Volume Prefix : plane-013-dev Provide the Destination Volume Prefix : plane-app ``` @@ -101,6 +108,7 @@ If you’re upgrading from `v0.13.2` or below, there are some additional migrati If there are any issues, an error will appear. For a successful migration, there will be no error, and the process will exit quietly. 11. Restart the upgraded v0.14.0 instance with: + ```bash ./setup.sh restart ``` @@ -109,6 +117,6 @@ If you’re upgrading from `v0.13.2` or below, there are some additional migrati 13. Once logged in, just click **Save Changes** to finalize your setup. -14. You’re all set! Log in to your updated `v0.14-0` instance to check if all of your data has migrated successfully. +14. You’re all set! Log in to your updated `v0.14-0` instance to check if all of your data has migrated successfully. -15. Now, [update to the latest version](/self-hosting/manage/upgrade-plane#update-version). \ No newline at end of file +15. Now, [update to the latest version](/self-hosting/manage/upgrade-plane#update-version). diff --git a/docs/self-hosting/manage/upgrade-plane.md b/docs/self-hosting/manage/upgrade-plane.md index 80eb784..7ce73cb 100644 --- a/docs/self-hosting/manage/upgrade-plane.md +++ b/docs/self-hosting/manage/upgrade-plane.md @@ -4,7 +4,6 @@ description: Upgrade self-hosted Plane to the latest version. Step-by-step guide keywords: plane version upgrade, update plane, plane latest version, upgrade guide, self-hosting update, plane migration --- - # Update Plane version Keeping Plane up to date ensures you’re using the latest features, improvements, and security fixes. Here’s how to upgrade your Plane installation with a single command. @@ -14,6 +13,7 @@ The upgrade process may involve a brief downtime as services are updated and res ::: ## Prerequisites + We recommend creating a backup of your data before any version updates. See [Backup data](/self-hosting/manage/backup-restore). ## Check version @@ -30,11 +30,12 @@ For Commercial Edition v1.13.0, ensure you're using the **latest version of Dock **Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`. ::: - 1. Update your Prime CLI with the command ↓: + ```bash sudo prime-cli update-cli - ``` + ``` + The latest version of the CLI ensures your Plane upgrades happen smoothly. 2. To update Plane to the latest version, run: @@ -55,14 +56,17 @@ Before starting, make a backup of your Plane instance. For detailed steps, see t #### Update version 1. Download the latest stable release with ↓: - ```bash - curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh - ``` + + ```bash + curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh + ``` 2. Execute the setup script with ↓: + ```bash ./setup.sh ``` + This will bring up a menu with several options. Select option `5` to upgrade: ```bash @@ -78,6 +82,7 @@ Before starting, make a backup of your Plane instance. For detailed steps, see t Action [2]: 5 ``` + Choosing this option stops all services and downloads the latest `docker-compose.yaml` and `variables-upgrade.env` files. The `plane.env` file won’t be overwritten, so your existing environment settings are safe. You’ll see a message indicating the services have been stopped. @@ -89,4 +94,4 @@ Before starting, make a backup of your Plane instance. For detailed steps, see t 5. Once your `plane.env` file is updated, start your Plane instance again by selecting option `2`. -::: \ No newline at end of file +::: diff --git a/docs/self-hosting/manage/view-logs.md b/docs/self-hosting/manage/view-logs.md index c9e5316..a7d4050 100644 --- a/docs/self-hosting/manage/view-logs.md +++ b/docs/self-hosting/manage/view-logs.md @@ -4,15 +4,15 @@ description: View and debug container logs for self-hosted Plane. Monitor Docker keywords: plane logs, container logs, docker logs, kubernetes logs, plane debugging, plane troubleshooting, self-hosting --- - # View container logs If you need to check the logs for troubleshooting or to monitor what’s happening in specific Plane services like the API or Worker, you can access them directly from the command line. To view logs, start by running the command ↓: - ```bash - sudo prime-cli monitor - ``` + +```bash +sudo prime-cli monitor +``` This brings up a table where you can select which container logs you want to view. @@ -27,6 +27,7 @@ This brings up a table where you can select which container logs you want to vie Here’s how to view logs for any service in Plane Community Edition, whether it’s the API, Worker, Redis, or others. This can be really helpful when troubleshooting or just getting insights into how each service is running. 1. Start by running the setup script: + ```bash ./setup.sh ``` @@ -46,6 +47,7 @@ Here’s how to view logs for any service in Plane Community Edition, whether it Action [2]: 6 ``` + 2. After choosing `6`, you’ll see a sub-menu listing all available services: ``` @@ -62,7 +64,7 @@ Here’s how to view logs for any service in Plane Community Edition, whether it 10) Minio 0) Back to Main Menu - Service: + Service: ``` 3. Pick the service whose logs you’d like to check. For example, if you want to view the **API logs**, type `3`. @@ -114,4 +116,4 @@ Here’s how to view logs for any service in Plane Community Edition, whether it 4. To exit the logs, use `CTRL+C`. This will take you back to the main menu where you can select another action or view logs from a different service. -::: \ No newline at end of file +::: diff --git a/docs/self-hosting/methods/airgapped-edition-kubernetes.md b/docs/self-hosting/methods/airgapped-edition-kubernetes.md index ec004d8..b8a7fa3 100644 --- a/docs/self-hosting/methods/airgapped-edition-kubernetes.md +++ b/docs/self-hosting/methods/airgapped-edition-kubernetes.md @@ -4,8 +4,7 @@ description: Deploy Plane on Kubernetes using Helm charts. Complete guide for pr keywords: plane airgapped kubernetes, offline k8s deployment, air-gapped helm, kubernetes offline, plane helm airgapped, self-hosting --- - -# Deploy Plane with airgapped Kubernetes +# Deploy Plane with airgapped Kubernetes ::: info Airgapped deployments are available exclusively for Business plan customers. Contact our [sales team](mailto:sales@plane.so) for pricing and licensing information. @@ -29,254 +28,262 @@ Before starting, ensure you have: While Kubernetes can run stateful services with persistent volumes, and Plane's Helm chart supports deploying PostgreSQL, MinIO, RabbitMQ, and Redis, we strongly recommend using external managed services for better reliability in backup/restore operations and disaster recovery. Consider these alternatives: + - **MinIO**: Replace with AWS S3, Google Cloud Storage, or any S3-compatible service - **Redis**: Replace with Valkey or a managed Redis service - **PostgreSQL**: Use a managed PostgreSQL service - **RabbitMQ**: Use a managed message queue service - **OpenSearch**: Use a managed OpenSearch or Elasticsearch service -::: + ::: ## Install Plane -1. **Download Plane Enterprise Helm chart** - - Get the Plane Enterprise Helm chart from the official release. Check for the latest version at [Artifact Hub](https://artifacthub.io/packages/helm/makeplane/plane-enterprise). - - ```bash - # Using wget - wget https://github.com/makeplane/helm-charts/releases/download/plane-enterprise-1.6.4/plane-enterprise-1.6.4.tgz - - # Using curl - curl -L -O https://github.com/makeplane/helm-charts/releases/download/plane-enterprise-1.6.4/plane-enterprise-1.6.4.tgz - ``` - -2. **Prepare Docker images for airgapped environment** - - Refer to [this document](/self-hosting/methods/clone-docker-images) to download the Docker images from the public repository to your internal repository. - - ::: info - This process will NOT download or clone these infrastructure images: - - `valkey:7.2.5-alpine` - - `postgres:15.7-alpine` - - `rabbitmq:3.13.6-management-alpine` - - `minio/minio:latest` - - `minio/mc:latest` - - `opensearchproject/opensearch:3.3.2` - - If you're using `local_setup: true` for any of these services, you'll need to pull and transfer these images separately. - ::: - - -3. **Configure custom values file** - - a. Extract the default values from the Helm chart. - - ```bash - helm show values plane-enterprise-1.6.4.tgz > custom-values.yaml - ``` - - b. Update Docker image references - - Edit the `custom-values.yaml` file to point to your local or private registry images and configure important settings. - - **Basic configuration:** - ```yaml - # Specify the Plane version - planeVersion: - - # Enable airgapped mode (REQUIRED) - airgapped: - enabled: true # Must be TRUE for airgapped installations - # If using custom root CA for S3 storage - s3SecretName: "s3-custom-ca" - s3SecretKey: "s3-custom-ca.crt" - ``` - - **Service images:** - ```yaml - services: - web: - image: /web-commercial - - api: - image: /backend-commercial - - space: - image: /space-commercial - - admin: - image: /admin-commercial - - live: - image: /live-commercial - - monitor: - image: /monitor-commercial - - email_service: - enabled: true - image: /email-commercial - - silo: - enabled: true - image: /silo-commercial - - iframely: - enabled: true - image: /iframely:v1.2.0 - ``` - - **Infrastructure services:** - - Configure whether to use local (in-cluster) or external services: - ```yaml - services: - # Database and infrastructure images - redis: - local_setup: true # Set to false if using external service - image: valkey/valkey:7.2.11-alpine - - postgres: - local_setup: true # Set to false if using external service - image: postgres:15.7-alpine - - rabbitmq: - local_setup: true # Set to false if using external service - image: rabbitmq:3.13.6-management-alpine - external_rabbitmq_url: '' # Required only if using remote RabbitMQ - - minio: - local_setup: true # Set to false if using external service - image: minio/minio:latest - image_mc: minio/mc:latest - ``` - - **Environment variables:** - ```yaml - env: - storageClass: '' - remote_redis_url: '' # Required only if using remote Redis - pgdb_remote_url: '' # Required only if using remote PostgreSQL - # Required if MinIO local_setup is false - aws_access_key: '' - aws_secret_access_key: '' - aws_region: '' - aws_s3_endpoint_url: '' - ``` - - c. **Configure integrations and importers** - - To set up integrations with external systems like Slack, GitHub, and GitLab, configure these values in `custom-values.yaml`: - ```yaml - services: - silo: - enabled: true - connectors: - slack: - enabled: false - client_id: '' - client_secret: '' - github: - enabled: false - client_id: '' - client_secret: '' - app_name: '' - app_id: '' - private_key: '' - gitlab: - enabled: false - client_id: '' - client_secret: '' - - env: - silo_envs: - batch_size: 100 - mq_prefetch_count: 1 - request_interval: 400 - hmac_secret_key: '' - aes_secret_key: 'dsOdt7YrvxsTIFJ37pOaEVvLxN8KGBCr' - ``` - - d. **Configure intake email** - - The email intake feature in Plane lets you capture incoming emails. Before or after setting up the application, configure DNS settings following [this guide](https://developers.plane.so/self-hosting/govern/configure-dns-email-service). - - Add these required values to `custom-values.yaml`: - ```yaml - ingress: - enabled: true - ingressClass: 'nginx' # Or as per your cluster - ingress_annotations: {} - - ssl: - tls_secret_name: '' # If you have a custom TLS secret name - # If you want to use Let's Encrypt, set createIssuer and generateCerts to true - createIssuer: false - issuer: http # Allowed: cloudflare, digitalocean, http - token: '' # Not required for http - server: https://acme-v02.api.letsencrypt.org/directory - email: plane@example.com # A valid email address - generateCerts: true - - services: - email_service: - enabled: true - replicas: 1 - memoryLimit: 1000Mi - cpuLimit: 500m - memoryRequest: 50Mi - cpuRequest: 50m - image: /email-commercial: - pullPolicy: Always - nodeSelector: {} - tolerations: [] - affinity: {} - labels: {} - annotations: {} - - env: - email_service_envs: - smtp_domain: '' - ``` +1. **Download Plane Enterprise Helm chart** + + Get the Plane Enterprise Helm chart from the official release. Check for the latest version at [Artifact Hub](https://artifacthub.io/packages/helm/makeplane/plane-enterprise). + + ```bash + # Using wget + wget https://github.com/makeplane/helm-charts/releases/download/plane-enterprise-1.6.4/plane-enterprise-1.6.4.tgz + + # Using curl + curl -L -O https://github.com/makeplane/helm-charts/releases/download/plane-enterprise-1.6.4/plane-enterprise-1.6.4.tgz + ``` + +2. **Prepare Docker images for airgapped environment** + + Refer to [this document](/self-hosting/methods/clone-docker-images) to download the Docker images from the public repository to your internal repository. + + ::: info + This process will NOT download or clone these infrastructure images: + - `valkey:7.2.5-alpine` + - `postgres:15.7-alpine` + - `rabbitmq:3.13.6-management-alpine` + - `minio/minio:latest` + - `minio/mc:latest` + - `opensearchproject/opensearch:3.3.2` + + If you're using `local_setup: true` for any of these services, you'll need to pull and transfer these images separately. + ::: + +3. **Configure custom values file** + + a. Extract the default values from the Helm chart. + + ```bash + helm show values plane-enterprise-1.6.4.tgz > custom-values.yaml + ``` + + b. Update Docker image references + + Edit the `custom-values.yaml` file to point to your local or private registry images and configure important settings. + + **Basic configuration:** + + ```yaml + # Specify the Plane version + planeVersion: + + # Enable airgapped mode (REQUIRED) + airgapped: + enabled: true # Must be TRUE for airgapped installations + # If using custom root CA for S3 storage + s3SecretName: "s3-custom-ca" + s3SecretKey: "s3-custom-ca.crt" + ``` + + **Service images:** + + ```yaml + services: + web: + image: /web-commercial + + api: + image: /backend-commercial + + space: + image: /space-commercial + + admin: + image: /admin-commercial + + live: + image: /live-commercial + + monitor: + image: /monitor-commercial + + email_service: + enabled: true + image: /email-commercial + + silo: + enabled: true + image: /silo-commercial + + iframely: + enabled: true + image: /iframely:v1.2.0 + ``` + + **Infrastructure services:** + + Configure whether to use local (in-cluster) or external services: + + ```yaml + services: + # Database and infrastructure images + redis: + local_setup: true # Set to false if using external service + image: valkey/valkey:7.2.11-alpine + + postgres: + local_setup: true # Set to false if using external service + image: postgres:15.7-alpine + + rabbitmq: + local_setup: true # Set to false if using external service + image: rabbitmq:3.13.6-management-alpine + external_rabbitmq_url: "" # Required only if using remote RabbitMQ + + minio: + local_setup: true # Set to false if using external service + image: minio/minio:latest + image_mc: minio/mc:latest + ``` + + **Environment variables:** + + ```yaml + env: + storageClass: "" + remote_redis_url: "" # Required only if using remote Redis + pgdb_remote_url: "" # Required only if using remote PostgreSQL + # Required if MinIO local_setup is false + aws_access_key: "" + aws_secret_access_key: "" + aws_region: "" + aws_s3_endpoint_url: "" + ``` + + c. **Configure integrations and importers** + + To set up integrations with external systems like Slack, GitHub, and GitLab, configure these values in `custom-values.yaml`: + + ```yaml + services: + silo: + enabled: true + connectors: + slack: + enabled: false + client_id: "" + client_secret: "" + github: + enabled: false + client_id: "" + client_secret: "" + app_name: "" + app_id: "" + private_key: "" + gitlab: + enabled: false + client_id: "" + client_secret: "" + + env: + silo_envs: + batch_size: 100 + mq_prefetch_count: 1 + request_interval: 400 + hmac_secret_key: "" + aes_secret_key: "dsOdt7YrvxsTIFJ37pOaEVvLxN8KGBCr" + ``` + + d. **Configure intake email** + + The email intake feature in Plane lets you capture incoming emails. Before or after setting up the application, configure DNS settings following [this guide](https://developers.plane.so/self-hosting/govern/configure-dns-email-service). + + Add these required values to `custom-values.yaml`: + + ```yaml + ingress: + enabled: true + ingressClass: 'nginx' # Or as per your cluster + ingress_annotations: {} + + ssl: + tls_secret_name: '' # If you have a custom TLS secret name + # If you want to use Let's Encrypt, set createIssuer and generateCerts to true + createIssuer: false + issuer: http # Allowed: cloudflare, digitalocean, http + token: '' # Not required for http + server: https://acme-v02.api.letsencrypt.org/directory + email: plane@example.com # A valid email address + generateCerts: true + + services: + email_service: + enabled: true + replicas: 1 + memoryLimit: 1000Mi + cpuLimit: 500m + memoryRequest: 50Mi + cpuRequest: 50m + image: /email-commercial: + pullPolicy: Always + nodeSelector: {} + tolerations: [] + affinity: {} + labels: {} + annotations: {} + + env: + email_service_envs: + smtp_domain: '' + ``` 4. **Install or upgrade with custom values** - Install Plane Enterprise using your customized values file: - ```bash - helm upgrade plane-app plane-enterprise-1.6.4.tgz \ - --install \ - --create-namespace \ - --namespace plane \ - -f custom-values.yaml \ - --timeout 10m \ - --wait \ - --wait-for-jobs - ``` + Install Plane Enterprise using your customized values file: + + ```bash + helm upgrade plane-app plane-enterprise-1.6.4.tgz \ + --install \ + --create-namespace \ + --namespace plane \ + -f custom-values.yaml \ + --timeout 10m \ + --wait \ + --wait-for-jobs + ``` 5. **Verify installation** - Check that all components are running: - ```bash - # Check all pods - kubectl get pods -n plane + Check that all components are running: + + ```bash + # Check all pods + kubectl get pods -n plane - # Check services - kubectl get services -n plane + # Check services + kubectl get services -n plane - # Check ingress - kubectl get ingress -n plane + # Check ingress + kubectl get ingress -n plane - # Check persistent volumes - kubectl get pv,pvc -n plane + # Check persistent volumes + kubectl get pv,pvc -n plane - # Get the ingress URL - kubectl get ingress -n plane -o wide - ``` + # Get the ingress URL + kubectl get ingress -n plane -o wide + ``` - You now have Plane running in your air-gapped environment. If you run into any issues, check the logs using the commands above, or reach out to our support team for assistance. + You now have Plane running in your air-gapped environment. If you run into any issues, check the logs using the commands above, or reach out to our support team for assistance. 6. [Activate your license key](/self-hosting/manage/manage-licenses/activate-airgapped). ## Additional configuration -For more advanced Plane configuration options, refer to the [Kubernetes documentation](https://developers.plane.so/self-hosting/methods/kubernetes#configuration-settings). \ No newline at end of file +For more advanced Plane configuration options, refer to the [Kubernetes documentation](https://developers.plane.so/self-hosting/methods/kubernetes#configuration-settings). diff --git a/docs/self-hosting/methods/airgapped-edition.md b/docs/self-hosting/methods/airgapped-edition.md index 1cf63e9..7651dcc 100644 --- a/docs/self-hosting/methods/airgapped-edition.md +++ b/docs/self-hosting/methods/airgapped-edition.md @@ -4,8 +4,7 @@ description: Deploy Plane in airgapped environment without internet access. Comp keywords: plane airgapped, offline deployment, air-gapped docker, plane offline install, disconnected environment, self-hosting --- - -# Deploy Plane with Airgapped Docker +# Deploy Plane with Airgapped Docker :::info Airgapped deployments are available exclusively for Business plan customers. Contact our [sales team](mailto:sales@plane.so) for pricing and licensing information. @@ -26,119 +25,124 @@ Before starting, ensure you have: While Docker can run stateful services with persistent volumes, we strongly recommend using external managed services for better reliability in backup/restore operations and disaster recovery. Consider these alternatives: + - **MinIO**: Replace with AWS S3, Google Cloud Storage, or any S3-compatible service - **Redis**: Replace with Valkey or a managed Redis service - **PostgreSQL**: Use a managed PostgreSQL service - **RabbitMQ**: Use a managed message queue service - **OpenSearch**: Use a managed OpenSearch or Elasticsearch service -::: + ::: ## Install Plane -1. **Prepare Docker images for airgapped environment** +1. **Prepare Docker images for airgapped environment** - Refer to [this document](/self-hosting/methods/clone-docker-images) to download the Docker images from the Plane artifact registry to your internal registry. + Refer to [this document](/self-hosting/methods/clone-docker-images) to download the Docker images from the Plane artifact registry to your internal registry. - :::info - This process will NOT download or clone these infrastructure images: - - `valkey/valkey:7.2.11-alpine` - - `postgres:15.7-alpine` - - `rabbitmq:3.13.6-management-alpine` - - `minio/minio:latest` - - `minio/mc:latest` - - `opensearchproject/opensearch:3.3.2` + :::info + This process will NOT download or clone these infrastructure images: + - `valkey/valkey:7.2.11-alpine` + - `postgres:15.7-alpine` + - `rabbitmq:3.13.6-management-alpine` + - `minio/minio:latest` + - `minio/mc:latest` + - `opensearchproject/opensearch:3.3.2` - If you're using local infrastructure services, you'll need to pull and transfer these images separately. - ::: + If you're using local infrastructure services, you'll need to pull and transfer these images separately. + ::: 2. **Download Docker Compose configuration** - ```bash - # Download docker-compose.yml - curl -fsSL https://prime.plane.so/releases//docker-compose.yml -o docker-compose.yml + ```bash + # Download docker-compose.yml + curl -fsSL https://prime.plane.so/releases//docker-compose.yml -o docker-compose.yml - # Download environment template - curl -fsSL https://prime.plane.so/releases//variables.env -o plane.env - ``` + # Download environment template + curl -fsSL https://prime.plane.so/releases//variables.env -o plane.env + ``` 3. **Configure environment variables** - Edit the `plane.env` file to configure your deployment: - - ```bash - # Generate a unique machine signature - export MACHINE_SIGNATURE=$(uuidgen) - - # Set your domain - export DOMAIN_NAME=plane.yourcompany.com - export WEB_URL=https://plane.yourcompany.com - export CORS_ALLOWED_ORIGINS=https://plane.yourcompany.com - ``` - - **Update image references** in `docker-compose.yml` to point to your private registry: - - ```yaml - services: - web: - image: your-registry.io/plane/web-commercial:${APP_RELEASE_VERSION} - - api: - image: your-registry.io/plane/backend-commercial:${APP_RELEASE_VERSION} - - space: - image: your-registry.io/plane/space-commercial:${APP_RELEASE_VERSION} - - admin: - image: your-registry.io/plane/admin-commercial:${APP_RELEASE_VERSION} - - live: - image: your-registry.io/plane/live-commercial:${APP_RELEASE_VERSION} - - monitor: - image: your-registry.io/plane/monitor-commercial:${APP_RELEASE_VERSION} - - silo: - image: your-registry.io/plane/silo-commercial:${APP_RELEASE_VERSION} - ``` - - **Infrastructure services** (if using local setup): - ```yaml - services: - redis: - image: valkey/valkey:7.2.11-alpine - - postgres: - image: postgres:15.7-alpine - - rabbitmq: - image: rabbitmq:3.13.6-management-alpine - - minio: - image: minio/minio:latest - ``` + Edit the `plane.env` file to configure your deployment: + + ```bash + # Generate a unique machine signature + export MACHINE_SIGNATURE=$(uuidgen) + + # Set your domain + export DOMAIN_NAME=plane.yourcompany.com + export WEB_URL=https://plane.yourcompany.com + export CORS_ALLOWED_ORIGINS=https://plane.yourcompany.com + ``` + + **Update image references** in `docker-compose.yml` to point to your private registry: + + ```yaml + services: + web: + image: your-registry.io/plane/web-commercial:${APP_RELEASE_VERSION} + + api: + image: your-registry.io/plane/backend-commercial:${APP_RELEASE_VERSION} + + space: + image: your-registry.io/plane/space-commercial:${APP_RELEASE_VERSION} + + admin: + image: your-registry.io/plane/admin-commercial:${APP_RELEASE_VERSION} + + live: + image: your-registry.io/plane/live-commercial:${APP_RELEASE_VERSION} + + monitor: + image: your-registry.io/plane/monitor-commercial:${APP_RELEASE_VERSION} + + silo: + image: your-registry.io/plane/silo-commercial:${APP_RELEASE_VERSION} + ``` + + **Infrastructure services** (if using local setup): + + ```yaml + services: + redis: + image: valkey/valkey:7.2.11-alpine + + postgres: + image: postgres:15.7-alpine + + rabbitmq: + image: rabbitmq:3.13.6-management-alpine + + minio: + image: minio/minio:latest + ``` ## Start Plane 1. Start the services: - ```bash - docker compose --env-file plane.env up -d - ``` + + ```bash + docker compose --env-file plane.env up -d + ``` 2. Watch the logs to make sure everything starts properly. - - To monitor the database migration process: - ```bash - docker compose logs -f migrator - ``` + - To monitor the database migration process: + + ```bash + docker compose logs -f migrator + ``` + + - To monitor the API service startup: + + ```bash + docker compose logs -f api + ``` - - To monitor the API service startup: - ```bash - docker compose logs -f api - ``` + The API is healthy when you see: `api-1 listening at` - The API is healthy when you see: `api-1 listening at` + Once all services are running smoothly, you can access Plane by opening your browser and going to the domain you configured. - Once all services are running smoothly, you can access Plane by opening your browser and going to the domain you configured. - - You now have Plane running in your air-gapped environment. If you run into any issues, check the logs using the commands above, or reach out to our support team for assistance. + You now have Plane running in your air-gapped environment. If you run into any issues, check the logs using the commands above, or reach out to our support team for assistance. -3. [Activate your license key](/self-hosting/manage/manage-licenses/activate-airgapped) \ No newline at end of file +3. [Activate your license key](/self-hosting/manage/manage-licenses/activate-airgapped) diff --git a/docs/self-hosting/methods/airgapped-requirements.md b/docs/self-hosting/methods/airgapped-requirements.md index 822527a..5f415ce 100644 --- a/docs/self-hosting/methods/airgapped-requirements.md +++ b/docs/self-hosting/methods/airgapped-requirements.md @@ -4,7 +4,6 @@ description: System requirements and architecture overview for Plane airgapped d keywords: plane airgapped requirements, air-gapped architecture, offline prerequisites, system requirements, airgapped planning, self-hosting --- - # Airgapped deployment architecture ::: info @@ -32,16 +31,16 @@ For a detailed breakdown of Plane's services and infrastructure dependencies, se **Critical guarantees for airgapped environments** - **No telemetry** -Plane does not send application data, usage metrics, or telemetry outside the cluster. No analytics, crash reports, or usage statistics leave your network. + Plane does not send application data, usage metrics, or telemetry outside the cluster. No analytics, crash reports, or usage statistics leave your network. - **Offline licensing** -License validation happens through uploaded license files downloaded from the Prime portal. No internet connection required after initial license file transfer. + License validation happens through uploaded license files downloaded from the Prime portal. No internet connection required after initial license file transfer. - **Zero external dependencies** -After initial image import, no external network connectivity is required for Plane to operate. All features work entirely within your isolated environment. + After initial image import, no external network connectivity is required for Plane to operate. All features work entirely within your isolated environment. - **Internal-only communication** -All service-to-service communication stays within your cluster. Services never attempt to reach external APIs, CDNs, or third-party services. + All service-to-service communication stays within your cluster. Services never attempt to reach external APIs, CDNs, or third-party services. ### How integrations stay internal @@ -73,11 +72,13 @@ Deploying airgapped Plane via Kubernetes requires preparing all dependencies to **Supported versions:** Kubernetes 1.31 – 1.33 **Required components:** + - IngressClass configured - StorageClass available - cert-manager configured with an internal CA **Node requirements:** + - Ensure node OS dependencies and container runtime packages are available from mirrored package repositories like apt, yum, or offline bundles ### Scaling @@ -87,6 +88,7 @@ Horizontal scaling is handled via replica counts configurable in `values.yaml`. Plane avoids using StatefulSets where possible due to the complexity of scaling stateful workloads in Kubernetes. The `monitor` service uses a StatefulSet. **For airgapped clusters:** + - Ensure metrics-server images are mirrored if using HPA - If using node autoscaling, ensure node images are pre-loaded and registries accessible on bootstrap @@ -104,4 +106,4 @@ Plane supports using existing external secret stores, provided they are reachabl - Ensure all secret providers can function without external network access - cert-manager must use an internal certificate authority -- Keys and secret rotation policies should be part of the airgap operational procedures \ No newline at end of file +- Keys and secret rotation policies should be part of the airgap operational procedures diff --git a/docs/self-hosting/methods/clone-docker-images.md b/docs/self-hosting/methods/clone-docker-images.md index 73526ab..e3dc45c 100644 --- a/docs/self-hosting/methods/clone-docker-images.md +++ b/docs/self-hosting/methods/clone-docker-images.md @@ -4,7 +4,6 @@ description: Mirror Plane Docker images to your private container registry. Pull keywords: plane docker images, private registry, container mirroring, docker pull, image cloning, airgapped docker, self-hosting --- - # Clone Docker images to your private registry ::: info @@ -21,11 +20,13 @@ This guide shows you how to copy Docker images from the Plane artifact registry Crane is a tool for interacting with remote container images and registries. Install it on a machine with internet access. **macOS:** + ```bash brew install crane ``` **Linux:** + ```bash # Download the latest release VERSION=$(curl -s https://api.github.com/repos/google/go-containerregistry/releases/latest | grep '"tag_name"' | cut -d'"' -f4) @@ -37,6 +38,7 @@ crane version ``` **Windows (using WSL or Git Bash):** + ```bash # Download and extract curl -sL "https://github.com/google/go-containerregistry/releases/latest/download/go-containerregistry_Windows_x86_64.tar.gz" | tar xz crane.exe @@ -45,6 +47,7 @@ curl -sL "https://github.com/google/go-containerregistry/releases/latest/downloa ## Plane images to copy The following Plane Commercial images need to be transferred to your private registry: + ``` artifacts.plane.so/makeplane/admin-commercial:${APP_RELEASE_VERSION} artifacts.plane.so/makeplane/web-commercial:${APP_RELEASE_VERSION} @@ -65,11 +68,12 @@ artifacts.plane.so/makeplane/email-commercial:${APP_RELEASE_VERSION} - `rabbitmq:3.13.6-management-alpine` - `minio/minio:latest` - `minio/mc:latest` -::: + ::: ## Configure environment variables Set your version and destination registry before copying images. + ```bash # Set your Plane version export APP_RELEASE_VERSION="v2.1.0" # Replace with your desired version @@ -79,6 +83,7 @@ export DESTINATION_REGISTRY="your-registry.io/your-namespace" ``` **Example destination registry values:** + ```bash # Docker Hub export DESTINATION_REGISTRY="docker.io/yourcompany" @@ -101,26 +106,31 @@ export DESTINATION_REGISTRY="yourregistry.azurecr.io/plane" Before copying images, authenticate crane to your destination registry. **Docker Hub:** + ```bash crane auth login docker.io -u YOUR_USERNAME -p YOUR_PASSWORD ``` **Google Container Registry:** + ```bash gcloud auth configure-docker ``` **AWS ECR:** + ```bash aws ecr get-login-password --region REGION | crane auth login --username AWS --password-stdin AWS_ACCOUNT_ID.dkr.ecr.REGION.amazonaws.com ``` **Azure Container Registry:** + ```bash az acr login --name YOUR_REGISTRY_NAME ``` **Harbor or other private registries:** + ```bash crane auth login your-registry.com -u YOUR_USERNAME -p YOUR_PASSWORD ``` @@ -132,6 +142,7 @@ You can copy images individually or use the provided script to copy all images a ### Option 1: Copy individual images **Basic image copy:** + ```bash crane copy \ artifacts.plane.so/makeplane/backend-commercial:${APP_RELEASE_VERSION} \ @@ -139,6 +150,7 @@ crane copy \ ``` **Copy with specific platform (architecture):** + ```bash crane copy \ --platform linux/amd64 \ @@ -147,6 +159,7 @@ crane copy \ ``` **Verify source image before copying:** + ```bash # Check if source image exists crane manifest artifacts.plane.so/makeplane/backend-commercial:${APP_RELEASE_VERSION} @@ -156,6 +169,7 @@ crane ls artifacts.plane.so/makeplane/backend-commercial ``` **Verify image after copying:** + ```bash # Get image digest crane digest ${DESTINATION_REGISTRY}/backend-commercial:${APP_RELEASE_VERSION} @@ -167,6 +181,7 @@ crane manifest ${DESTINATION_REGISTRY}/backend-commercial:${APP_RELEASE_VERSION} ### Option 2: Copy all images with a script Create a file named `copy-plane-images.sh`: + ```bash #!/bin/bash @@ -208,10 +223,10 @@ echo "" for IMAGE in "${IMAGES[@]}"; do SOURCE="${SOURCE_REGISTRY}/${IMAGE}" DESTINATION="${DESTINATION_REGISTRY}/${IMAGE}" - + echo "Copying: ${SOURCE} -> ${DESTINATION}" crane copy "${SOURCE}" "${DESTINATION}" - + if [ $? -eq 0 ]; then echo "✓ Successfully copied ${IMAGE}" else @@ -225,6 +240,7 @@ echo "All images copied successfully!" ``` Make the script executable and run it: + ```bash chmod +x copy-plane-images.sh ./copy-plane-images.sh @@ -239,6 +255,7 @@ The script will copy all Plane images to your destination registry. Each image c **Error:** `unauthorized: authentication required` **Solution:** Re-authenticate to your destination registry: + ```bash crane auth login your-destination-registry.com ``` @@ -274,9 +291,11 @@ Verify your credentials are correct and that you have push permissions to the re **Solution:** - Verify the source image exists: + ```bash crane ls artifacts.plane.so/makeplane/backend-commercial ``` + - Check that you're using the correct version tag - Ensure `APP_RELEASE_VERSION` is set correctly - Verify the image name is spelled correctly @@ -295,4 +314,4 @@ Verify your credentials are correct and that you have push permissions to the re ## Additional resources - [Crane documentation](https://github.com/google/go-containerregistry/blob/main/cmd/crane/doc/crane.md) -- [Crane GitHub repository](https://github.com/google/go-containerregistry) \ No newline at end of file +- [Crane GitHub repository](https://github.com/google/go-containerregistry) diff --git a/docs/self-hosting/methods/coolify.md b/docs/self-hosting/methods/coolify.md index f22c989..19027cb 100644 --- a/docs/self-hosting/methods/coolify.md +++ b/docs/self-hosting/methods/coolify.md @@ -18,15 +18,16 @@ This guide shows you the steps to deploy a self-hosted instance of Plane using C ### Procedure 1. **Download the required deployment files** - - `coolify-compose.yml` – Defines Plane's services and dependencies. - ```bash - curl -fsSL https://prime.plane.so/releases//coolify-compose.yml -o coolify-compose.yml - ``` +`coolify-compose.yml` – Defines Plane's services and dependencies. - ::: warning - The `` value should be v1.8.2 or higher. - ::: +```bash +curl -fsSL https://prime.plane.so/releases//coolify-compose.yml -o coolify-compose.yml +``` + +::: warning +The `` value should be v1.8.2 or higher. +::: 2. Create a new project in Coolify. @@ -40,9 +41,10 @@ This guide shows you the steps to deploy a self-hosted instance of Plane using C ::: warning When self-hosting Plane for production use, it is strongly recommended to configure external database and storage. This ensures that your data remains secure and accessible even if the local machine crashes or encounters hardware issues. Relying solely on local storage for these components increases the risk of data loss and service disruption. ::: - - `DATABASE_URL` – Connection string for your external database. - - `REDIS_URL` – Connection string for your external Redis instance. - - `AMQP_URL` – Connection string for your external RabbitMQ server. + +- `DATABASE_URL` – Connection string for your external database. +- `REDIS_URL` – Connection string for your external Redis instance. +- `AMQP_URL` – Connection string for your external RabbitMQ server. 7. Deploy to launch your Plane instance. Once the deployment is complete, your Plane instance should be accessible on the configured domain. diff --git a/docs/self-hosting/methods/docker-aio.md b/docs/self-hosting/methods/docker-aio.md index 9257836..e515e76 100644 --- a/docs/self-hosting/methods/docker-aio.md +++ b/docs/self-hosting/methods/docker-aio.md @@ -4,17 +4,16 @@ description: Deploy Plane with Docker All-in-One (AIO) setup. Quick installation keywords: plane docker aio, all-in-one container, single container deployment, quick install, plane docker setup, self-hosting --- - # Docker AIO (All-in-One) -The Plane Commercial All-in-One (AIO) Docker image packages all Plane services into a single container, making it the fastest way to get Plane running. +The Plane Commercial All-in-One (AIO) Docker image packages all Plane services into a single container, making it the fastest way to get Plane running. ## What's included Your single AIO container includes all these services running together: - **Web App** - The main Plane web interface you'll use -- **Space** - Public project spaces for external collaboration +- **Space** - Public project spaces for external collaboration - **Admin** - Administrative interface - **API Server** - Backend API - **Live Server** - Real-time collaboration features @@ -27,6 +26,7 @@ Your single AIO container includes all these services running together: ### Port Mapping The following ports are exposed: + - `80`: Main web interface (HTTP) - `443`: HTTPS (if SSL configured) - `20025`: SMTP port 25 @@ -37,66 +37,67 @@ The following ports are exposed: - [Docker](https://docs.docker.com/engine/) - Set up these external services: - - *PostgreSQL* + - _PostgreSQL_ For data storage - - *Redis* + - _Redis_ For caching and session management - - *RabbitMQ* + - _RabbitMQ_ For message queuing - - *S3-compatible storage* + - _S3-compatible storage_ For file uploads (AWS S3 or MinIO) ## Install Plane 1. Download the image with: - ```bash - docker pull artifacts.plane.so/makeplane/plane-aio-commercial:stable - ``` + + ```bash + docker pull artifacts.plane.so/makeplane/plane-aio-commercial:stable + ``` 2. Run the following command to deploy the Plane AIO container. Make sure to replace all placeholder values (e.g., `your-domain.com`, `user:pass`) with your actual configuration. - ::: warning - All environment variables are required for the container to function correctly. - ::: - - ```bash - docker run --name plane-aio --rm -it \ - -p 80:80 \ - -p 20025:20025 \ - -p 20465:20465 \ - -p 20587:20587 \ - -e DOMAIN_NAME=your-domain.com \ - -e DATABASE_URL=postgresql://user:pass@host:port/database \ - -e REDIS_URL=redis://host:port \ - -e AMQP_URL=amqp://user:pass@host:port/vhost \ - -e AWS_REGION=us-east-1 \ - -e AWS_ACCESS_KEY_ID=your-access-key \ - -e AWS_SECRET_ACCESS_KEY=your-secret-key \ - -e AWS_S3_BUCKET_NAME=your-bucket \ - artifacts.plane.so/makeplane/plane-aio-commercial:stable - ``` - - If you're running on an IP address, use this example: - - ```bash - MYIP=192.168.68.169 - docker run --name myaio --rm -it \ - -p 80:80 \ - -p 20025:20025 \ - -p 20465:20465 \ - -p 20587:20587 \ - -e DOMAIN_NAME=${MYIP} \ - -e DATABASE_URL=postgresql://plane:plane@${MYIP}:15432/plane \ - -e REDIS_URL=redis://${MYIP}:16379 \ - -e AMQP_URL=amqp://plane:plane@${MYIP}:15673/plane \ - -e AWS_REGION=us-east-1 \ - -e AWS_ACCESS_KEY_ID= \ - -e AWS_SECRET_ACCESS_KEY= \ - -e AWS_S3_BUCKET_NAME=plane-app \ - -e AWS_S3_ENDPOINT_URL=http://${MYIP}:19000 \ - -e FILE_SIZE_LIMIT=10485760 \ - artifacts.plane.so/makeplane/plane-aio-commercial:stable - ``` + ::: warning + All environment variables are required for the container to function correctly. + ::: + + ```bash + docker run --name plane-aio --rm -it \ + -p 80:80 \ + -p 20025:20025 \ + -p 20465:20465 \ + -p 20587:20587 \ + -e DOMAIN_NAME=your-domain.com \ + -e DATABASE_URL=postgresql://user:pass@host:port/database \ + -e REDIS_URL=redis://host:port \ + -e AMQP_URL=amqp://user:pass@host:port/vhost \ + -e AWS_REGION=us-east-1 \ + -e AWS_ACCESS_KEY_ID=your-access-key \ + -e AWS_SECRET_ACCESS_KEY=your-secret-key \ + -e AWS_S3_BUCKET_NAME=your-bucket \ + artifacts.plane.so/makeplane/plane-aio-commercial:stable + ``` + + If you're running on an IP address, use this example: + + ```bash + MYIP=192.168.68.169 + docker run --name myaio --rm -it \ + -p 80:80 \ + -p 20025:20025 \ + -p 20465:20465 \ + -p 20587:20587 \ + -e DOMAIN_NAME=${MYIP} \ + -e DATABASE_URL=postgresql://plane:plane@${MYIP}:15432/plane \ + -e REDIS_URL=redis://${MYIP}:16379 \ + -e AMQP_URL=amqp://plane:plane@${MYIP}:15673/plane \ + -e AWS_REGION=us-east-1 \ + -e AWS_ACCESS_KEY_ID= \ + -e AWS_SECRET_ACCESS_KEY= \ + -e AWS_S3_BUCKET_NAME=plane-app \ + -e AWS_S3_ENDPOINT_URL=http://${MYIP}:19000 \ + -e FILE_SIZE_LIMIT=10485760 \ + artifacts.plane.so/makeplane/plane-aio-commercial:stable + ``` 3. Once it's running, you can access the Plane application on the domain you provided during the deployment. @@ -105,18 +106,22 @@ The following ports are exposed: ## Volume mounts ### Recommended persistent volumes + ```bash -v /path/to/logs:/app/logs \ --v /path/to/data:/app/data +-v /path/to/data:/app/data ``` ### Workspace license DB + ```bash -v /path/to/monitordb:/app/monitor ``` ### SSL certificate support + For HTTPS support, mount certificates: + ```bash -v /path/to/certs:/app/email/tls ``` @@ -124,19 +129,22 @@ For HTTPS support, mount certificates: ## Environment variables (optional) ### Network and Protocol + - `SITE_ADDRESS`: Server bind address (default: `:80`) - `APP_PROTOCOL`: Protocol to use (`http` or `https`, default: `http`) -### Email configuration +### Email configuration + - `INTAKE_EMAIL_DOMAIN`: Domain for intake emails (default: `intake.`) - `LISTEN_SMTP_PORT_25`: SMTP port 25 mapping (default: `20025`) -- `LISTEN_SMTP_PORT_465`: SMTP port 465 mapping (default: `20465`) +- `LISTEN_SMTP_PORT_465`: SMTP port 465 mapping (default: `20465`) - `LISTEN_SMTP_PORT_587`: SMTP port 587 mapping (default: `20587`) - `SMTP_DOMAIN`: SMTP server domain (default: `0.0.0.0`) - `TLS_CERT_PATH`: Path to TLS certificate file (optional) - `TLS_PRIV_KEY_PATH`: Path to TLS private key file (optional) ### Security and secrets + - `MACHINE_SIGNATURE`: Unique machine identifier (auto-generated if not provided) - `SECRET_KEY`: Django secret key (default provided) - `SILO_HMAC_SECRET_KEY`: Silo HMAC secret (default provided) @@ -144,18 +152,22 @@ For HTTPS support, mount certificates: - `LIVE_SERVER_SECRET_KEY`: Live server secret (default provided) ### File handling + - `FILE_SIZE_LIMIT`: Maximum file upload size in bytes (default: `5242880` = 5MB) ### Integration callbacks + - `INTEGRATION_CALLBACK_BASE_URL`: Base URL for OAuth callbacks ### API configuration + - `API_KEY_RATE_LIMIT`: API key rate limit (default: `60/minute`) ### Third-party integrations + - `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`: GitHub integration - `GITHUB_APP_NAME`, `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY`: GitHub App integration -- `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`: Slack integration +- `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`: Slack integration - `GITLAB_CLIENT_ID`, `GITLAB_CLIENT_SECRET`: GitLab integration ## Build the image @@ -164,23 +176,29 @@ To build the AIO image yourself: ```bash cd deploy/aio/commercial -./build.sh --release=v1.11.1 +./build.sh --release=v1.11.1 ``` Available build options: + - `--release`: Plane version to build (required) - `--image-name`: Custom image name (default: `plane-aio-commercial`) ## Troubleshoot + The container will validate required environment variables on startup and display helpful error messages if any are missing. ### Logs + All service logs are available in `/app/logs/`: + - Access logs: `/app/logs/access/` - Error logs: `/app/logs/error/` ### Health checks + The container runs multiple services managed by Supervisor. Check service status: + ```bash docker exec -it supervisorctl status ``` @@ -192,4 +210,4 @@ docker exec -it supervisorctl status - Monitor resource usage and scale accordingly - Use external load balancer for high availability - Regularly update to latest versions -- Secure your environment variables and secrets \ No newline at end of file +- Secure your environment variables and secrets diff --git a/docs/self-hosting/methods/docker-compose.md b/docs/self-hosting/methods/docker-compose.md index 0d87c7e..9e53a81 100644 --- a/docs/self-hosting/methods/docker-compose.md +++ b/docs/self-hosting/methods/docker-compose.md @@ -4,7 +4,6 @@ description: Install Plane using Docker Compose. Step-by-step guide for deployin keywords: plane docker compose, docker deployment, container setup, docker install plane, plane containers, self-hosting --- - # Docker Compose This guide shows you the steps to deploy a self-hosted instance of Plane using Docker. @@ -14,17 +13,18 @@ If you want to upgrade from Community to the Commercial edition, see [Upgrade to ::: ## Install Plane + Plane Pro and Plane Business are enabled on this edition, so the Free plan on this edition is easier to trial our paid plans from. ### Prerequisites - - A virtual or on-prem machine with at least 2 vCPUs and 4 GB RAM (8 GB RAM recommended) - - `x64` AKA `AMD 64` or `AArch 64` AKA `ARM 64` CPUs - - Supported operating systems: - - Ubuntu - - Debian - - CentOS - - Amazon Linux 2 or Linux 2023 +- A virtual or on-prem machine with at least 2 vCPUs and 4 GB RAM (8 GB RAM recommended) +- `x64` AKA `AMD 64` or `AArch 64` AKA `ARM 64` CPUs +- Supported operating systems: + - Ubuntu + - Debian + - CentOS + - Amazon Linux 2 or Linux 2023 ::: info Ensure you're using the **latest version of Docker Compose**. Check your Docker Compose version with `docker-compose --version` and update if needed. @@ -32,116 +32,116 @@ Ensure you're using the **latest version of Docker Compose**. Check your Docker ### Procedure - 1. `ssh` into your machine as the root user (or user with sudo access) per the norms of your hosting provider. - 2. Run the command below: - ``` - curl -fsSL https://prime.plane.so/install/ | sh - - ``` - 3. Follow the instructions on the terminal. Hit `Enter` or `Return` to continue. - 4. Enter the domain name where you will access the Plane app in the format `domain.tld` or `subdomain.domain.tld`. - 5. Choose one of the options below: - - **Express**: Plane installs with the default configurations. - - **Advanced**: You can customize the database, Redis, storage and other settings. +1. `ssh` into your machine as the root user (or user with sudo access) per the norms of your hosting provider. +2. Run the command below: + ```bash + curl -fsSL https://prime.plane.so/install/ | sh - + ``` +3. Follow the instructions on the terminal. Hit `Enter` or `Return` to continue. +4. Enter the domain name where you will access the Plane app in the format `domain.tld` or `subdomain.domain.tld`. +5. Choose one of the options below: + - **Express**: Plane installs with the default configurations. + - **Advanced**: You can customize the database, Redis, storage and other settings. ::: warning When self-hosting Plane for production use, it is strongly recommended to configure [external database and storage](/self-hosting/govern/database-and-storage). This ensures that your data remains secure and accessible even if the local machine crashes or encounters hardware issues. Relying solely on local storage for these components increases the risk of data loss and service disruption. ::: - 6. The installation will take a few minutes to complete and you will see the message **Plane has successfully installed**. You can access the Plane application on the domain you provided during the installation. - 7. If you've purchased a paid plan, [activate your license key](/self-hosting/manage/manage-licenses/activate-pro-and-business#activate-your-license) to unlock premium features. - - -::: details Install Community Edition - The Commercial edition comes with a free plan and the flexibility to upgrade to a paid plan at any point. If you still want to install the Community edition, follow the steps below: - - #### Prerequisites - - - Docker installed and running. Choose one of the following options: - - **Option 1** - Create an EC2 machine on AWS. It must of minimum **t3.medium/t3a.medium**. Run the below command to install docker engine. - ```bash - curl -fsSL https://get.docker.com | sh - - ``` - - **Option 2** - Install [Docker Desktop](https://www.docker.com/products/docker-desktop/). - - OS with bash scripting enabled (Ubuntu, Linux AMI, macos). Windows systems need to have [gitbash](https://git-scm.com/download/win). - - User context used must have access to docker services. In most cases, use `sudo su` to switch as root user. - - Use the terminal (or gitbash) window to run all the future steps. - - #### Installation - 1. Create a folder named `plane-selfhost` on your machine for deployment and data storage. - - ```bash - mkdir plane-selfhost - ``` - 2. Navigate to this folder using the cd command. - ```bash - cd plane-selfhost - ``` - 3. Download the latest stable release. - ```bash - curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh - ``` - 4. Make the file executable. - ```bash - chmod +x setup.sh - ``` - 5. Run the following command: - ```bash - ./setup.sh - ``` - This will prompt you with the below options. - ```list - Select a Action you want to perform: - 1) Install (arm64) - 2) Start - 3) Stop - 4) Restart - 5) Upgrade - 6) View Logs - 7) Backup Data - 8) Exit - Action [2]: 1 - ``` - 6. Enter `1` as input. - This will create a folder `plane-app` or `plane-app-preview` (in case of preview deployment) and will download the `docker-compose.yaml` and `plane.env` files. - 7. Enter `8` to exit. - 8. Set up the environment variables. You can use any text editor to edit this file. Below are the most importants keys you must refer to: - - `LISTEN_HTTP_PORT`: This is set to `80` by default. Make sure the port you choose to use is not preoccupied. For example, `LISTEN_HTTP_PORT=8080` - - `LISTEN_HTTPS_PORT`: This is set to `443` by default. Make sure the port you choose to use is not preoccupied. For example, `LISTEN_HTTPS_PORT=4430` - - `WEB_URL`: This is set to `http://localhost` by default. Change this to the FQDN you plan to use along with LISTEN_HTTP_PORT. For example, `https://plane.example.com:8080` or `http://[IP-ADDRESS]:8080`. - - `CORS_ALLOWED_ORIGINS`: This is set to `http://localhost` by default. Change this to the FQDN you plan to use along with LISTEN_HTTP_PORT. For example, `https://plane.example.com:8080` or `http://[IP-ADDRESS]:8080`. - 9. Run the following command to continue with the setup. - ```bash - ./setup.sh - ``` - 10. Enter `2` as input to start the services. - You will something like this: - ![Downloading docker images](/images/docker-compose/download-docker.png) - Be patient as it might take some time based on your download speed and system configuration. If all goes well, you must see something like this: - ![Downloading completed](/images/docker-compose/download-complete.png) - This is the confirmation that all images were downloaded and the services are up and running. - - You have successfully self-hosted the Plane instance. Access the application by going to IP or domain you have configured it on. For example, `https://plane.example.com:8080` or `http://[IP-ADDRESS]:8080`. - - ##### Stop server - - In case you want to make changes to the environment variables in the `plane.env` file, we recommend that you stop the services before doing that. - - Run the `./setup.sh` command. Enter `3` to stop the services. - - If all goes well, you will see something like this: - - ![Stop Services](/images/docker-compose/stopped-docker.png) - - ##### Restart server - - In case you want to make changes to `plane.env` variables without stopping the server or noticed some abnormalities in services, you can restart the services. - - Run the `./setup.sh` command. Enter `4` to restart the services. - - If all goes well, you will see something like this: - ![Restart Services](/images/docker-compose/restart-docker.png) +6. The installation will take a few minutes to complete and you will see the message **Plane has successfully installed**. You can access the Plane application on the domain you provided during the installation. +7. If you've purchased a paid plan, [activate your license key](/self-hosting/manage/manage-licenses/activate-pro-and-business#activate-your-license) to unlock premium features. + +::: details Install Community Edition +The Commercial edition comes with a free plan and the flexibility to upgrade to a paid plan at any point. If you still want to install the Community edition, follow the steps below: + +#### Prerequisites + +- Docker installed and running. Choose one of the following options: + - **Option 1** + Create an EC2 machine on AWS. It must of minimum **t3.medium/t3a.medium**. Run the below command to install docker engine. + ```bash + curl -fsSL https://get.docker.com | sh - + ``` + - **Option 2** + Install [Docker Desktop](https://www.docker.com/products/docker-desktop/). +- OS with bash scripting enabled (Ubuntu, Linux AMI, macOS). Windows systems need to have [gitbash](https://git-scm.com/download/win). +- User context used must have access to docker services. In most cases, use `sudo su` to switch as root user. +- Use the terminal (or gitbash) window to run all the future steps. + +#### Installation + +1. Create a folder named `plane-selfhost` on your machine for deployment and data storage. + ```bash + mkdir plane-selfhost + ``` +2. Navigate to this folder using the cd command. + ```bash + cd plane-selfhost + ``` +3. Download the latest stable release. + ```bash + curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh + ``` +4. Make the file executable. + ```bash + chmod +x setup.sh + ``` +5. Run the following command: + ```bash + ./setup.sh + ``` + This will prompt you with the below options. + ```bash + Select a Action you want to perform: + 1) Install (arm64) + 2) Start + 3) Stop + 4) Restart + 5) Upgrade + 6) View Logs + 7) Backup Data + 8) Exit + Action [2]: 1 + ``` +6. Enter `1` as input. + This will create a folder `plane-app` or `plane-app-preview` (in case of preview deployment) and will download the `docker-compose.yaml` and `plane.env` files. +7. Enter `8` to exit. +8. Set up the environment variables. You can use any text editor to edit this file. Below are the most importants keys you must refer to: + - `LISTEN_HTTP_PORT`: This is set to `80` by default. Make sure the port you choose to use is not preoccupied. For example, `LISTEN_HTTP_PORT=8080` + - `LISTEN_HTTPS_PORT`: This is set to `443` by default. Make sure the port you choose to use is not preoccupied. For example, `LISTEN_HTTPS_PORT=4430` + - `WEB_URL`: This is set to `http://localhost` by default. Change this to the FQDN you plan to use along with LISTEN_HTTP_PORT. For example, `https://plane.example.com:8080` or `http://[IP-ADDRESS]:8080`. + - `CORS_ALLOWED_ORIGINS`: This is set to `http://localhost` by default. Change this to the FQDN you plan to use along with LISTEN_HTTP_PORT. For example, `https://plane.example.com:8080` or `http://[IP-ADDRESS]:8080`. +9. Run the following command to continue with the setup. + ```bash + ./setup.sh + ``` +10. Enter `2` as input to start the services. + You will something like this: + ![Downloading docker images](/images/docker-compose/download-docker.png) + Be patient as it might take some time based on your download speed and system configuration. If all goes well, you must see something like this: + ![Downloading completed](/images/docker-compose/download-complete.png) + This is the confirmation that all images were downloaded and the services are up and running. + +You have successfully self-hosted the Plane instance. Access the application by going to IP or domain you have configured it on. For example, `https://plane.example.com:8080` or `http://[IP-ADDRESS]:8080`. + +##### Stop server + +In case you want to make changes to the environment variables in the `plane.env` file, we recommend that you stop the services before doing that. + +Run the `./setup.sh` command. Enter `3` to stop the services. + +If all goes well, you will see something like this: + +![Stop Services](/images/docker-compose/stopped-docker.png) + +##### Restart server + +In case you want to make changes to `plane.env` variables without stopping the server or noticed some abnormalities in services, you can restart the services. + +Run the `./setup.sh` command. Enter `4` to restart the services. + +If all goes well, you will see something like this: +![Restart Services](/images/docker-compose/restart-docker.png) ::: ## Troubleshoot + - [Error during Docker Compose execution](/self-hosting/troubleshoot/installation-errors#error-during-docker-compose-execution) -- [Migrator container exited](/self-hosting/troubleshoot/installation-errors#migrator-container-exited) \ No newline at end of file +- [Migrator container exited](/self-hosting/troubleshoot/installation-errors#migrator-container-exited) diff --git a/docs/self-hosting/methods/kubernetes.md b/docs/self-hosting/methods/kubernetes.md index 0f36b08..b9f62a4 100644 --- a/docs/self-hosting/methods/kubernetes.md +++ b/docs/self-hosting/methods/kubernetes.md @@ -49,7 +49,6 @@ helm repo add plane https://helm.plane.so/ ``` 4. Use one of the following ways to deploy Plane: - - **Quick setup**: This is the fastest way to deploy Plane with the default settings. This will create stateful deployments for Postgres, Redis/Valkey, and Minio with a persistent volume claim using the `longhorn` storage class. This also sets up the Ingress routes for you using `nginx` ingress class. To customize these settings, see the [Custom ingress routes](#custom-ingress-routes). @@ -636,287 +635,285 @@ The Commercial edition comes with a free plan and the flexibility to upgrade to helm repo update ``` -3. Use one of the following ways to deploy Plane: - **Quick setup** - - This is the fastest way to deploy Plane with default settings. This will create stateful deployments for Postgres, Redis, and Minio with a persistent volume claim using the `longhorn` storage class. This also sets up the ingress routes for you using `nginx` ingress class. - - ::: tip - To customize this, see `Custom ingress routes` below. - ::: - - Continue to be on the same Terminal window as you have so far, copy the code below, and paste it on your Terminal screen. - - ```bash - helm install plane-app makeplane/plane-ce \ - --create-namespace \ - --namespace plane-ce \ - --set planeVersion=stable \ - --set ingress.appHost="plane.example.com" \ - --set ingress.minioHost="plane-minio.example.com" \ - --set ingress.ingressClass=nginx \ - --set postgres.storageClass=longhorn \ - --set redis.storageClass=longhorn \ - --set minio.storageClass=longhorn \ - --timeout 10m \ - --wait \ - --wait-for-jobs - ``` - - ::: tip - This is the minimum required to set up Plane-CE. You can change the default namespace from `plane-ce`, the default app name from `plane-app`, the default storage class from `[postgres, redis, minio].storageClass`, and the default ingress class from `ingress.ingressClass` to whatever you would like to. - - You can also pass other settings referring to `Configuration Settings` section. - ::: - - - **Advanced setup** - For more control over your set-up, run the script below to download the `values.yaml` file and and edit using any editor like Vim or Nano. - - ```bash - helm show values makeplane/plane-ce > values.yaml - vi values.yaml - ``` - - ::: tip - See **Configuration settings** below for more details. - ::: - - After saving the `values.yaml` file, continue to be on the same Terminal window as on the previous steps, copy the code below, and paste it on your Terminal screen. - - ```bash - helm install plane-app makeplane/plane-ce \ - --create-namespace \ - --namespace plane-ce \ - -f values.yaml \ - --timeout 10m \ - --wait \ - --wait-for-jobs - ``` - - #### Configuration settings - - ##### Plane Version - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | planeVersion | v1.1.0 | Yes | | - - ##### Postgres DB Setup - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | postgres.local_setup | true | | Plane uses postgres as the primary database to store all the transactional data. This database can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws rds or similar services). Set this to true when you choose to setup stateful deployment of postgres. Mark it as false when using a remotely hosted database | - | postgres.image | postgres:15.7-alpine | | Using this key, user must provide the docker image name to setup the stateful deployment of postgres. (must be set when `postgres.local_setup=true`) | - | postgres.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of postgres. (must be set when `postgres.local_setup=true`) | - | postgres.servicePort | 5432 | | This key sets the default port number to be used while setting up stateful deployment of postgres. | - | postgres.volumeSize | 5Gi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | - | env.pgdb_username | plane | | Database credentials are requried to access the hosted stateful deployment of postgres. Use this key to set the username for the stateful deployment. | - | env.pgdb_password | plane | | Database credentials are requried to access the hosted stateful deployment of postgres. Use this key to set the password for the stateful deployment. | - | env.pgdb_name | plane | | Database name to be used while setting up stateful deployment of Postgres | - | env.pgdb_remote_url | | | Users can also decide to use the remote hosted database and link to Plane deployment. Ignoring all the above keys, set postgres.local_setup to false and set this key with remote connection url. | - | postgres.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | - | postgres.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | postgres.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of postgres. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | postgres.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of postgres. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | postgres.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of postgres. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | postgres.labels | {} | | This key allows you to set custom labels for the stateful deployment of postgres. This is useful for organizing and selecting resources in your Kubernetes cluster. | - | postgres.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of postgres. This is useful for adding metadata or configuration hints to your resources. | - - ##### Redis/Valkey Setup - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | redis.local_setup | true | | Plane uses redis to cache the session authentication and other static data. This database can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws rds or similar services). Set this to true when you choose to setup stateful deployment of redis. Mark it as false when using a remotely hosted database | - | redis.image | `valkey/valkey:7.2.5-alpine` | | Using this key, user must provide the docker image name to setup the stateful deployment of redis. (must be set when redis.local_setup=true) | - | redis.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of redis. (must be set when `redis.local_setup=true`) | - | redis.servicePort | 6379 | | This key sets the default port number to be used while setting up stateful deployment of redis. | - | redis.volumeSize | 1Gi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | - | env.remote_redis_url | | | Users can also decide to use the remote hosted database and link to Plane deployment. Ignoring all the above keys, set redis.local_setup to false and set this key with remote connection url. | - | redis.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | - | redis.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | redis.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of redis. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | redis.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of redis. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | redis.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of redis. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | redis.labels | {} | | This key allows you to set custom labels for the stateful deployment of redis. This is useful for organizing and selecting resources in your Kubernetes cluster. | - | redis.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of redis. This is useful for adding metadata or configuration hints to your resources. | - - ##### RabbitMQ Setup - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | rabbitmq.local_setup | true | | Plane uses rabbitmq as message queuing system. This can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws mq or similar services). Set this to true when you choose to setup stateful deployment of rabbitmq. Mark it as false when using a remotely hosted service | - | rabbitmq.image | rabbitmq:3.13.6-management-alpine | | Using this key, user must provide the docker image name to setup the stateful deployment of rabbitmq. (must be set when `rabbitmq.local_setup=true`) | - | rabbitmq.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of rabbitmq. (must be set when `rabbitmq.local_setup=true`) | - | rabbitmq.servicePort | 5672 | | This key sets the default port number to be used while setting up stateful deployment of rabbitmq. | - | rabbitmq.managementPort | 15672 | | This key sets the default management port number to be used while setting up stateful deployment of rabbitmq. | - | rabbitmq.volumeSize | 100Mi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | - | rabbitmq.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | - | rabbitmq.default_user | plane | | Credentials are requried to access the hosted stateful deployment of rabbitmq. Use this key to set the username for the stateful deployment. | - | rabbitmq.default_password | plane | | Credentials are requried to access the hosted stateful deployment of rabbitmq. Use this key to set the password for the stateful deployment. | - | rabbitmq.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | rabbitmq.external_rabbitmq_url | | | Users can also decide to use the remote hosted service and link to Plane deployment. Ignoring all the above keys, set rabbitmq.local_setup to false and set this key with remote connection url. | - | rabbitmq.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of rabbitmq. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | rabbitmq.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of rabbitmq. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | rabbitmq.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of rabbitmq. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | rabbitmq.labels | {} | | This key allows you to set custom labels for the stateful deployment of rabbitmq. This is useful for organizing and selecting resources in your Kubernetes cluster. | - | rabbitmq.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of rabbitmq. This is useful for adding metadata or configuration hints to your resources. | - - ##### Doc Store (Minio/S3) Setup - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | minio.local_setup | true | | Plane uses minio as the default file storage drive. This storage can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws S3 or similar services). Set this to true when you choose to setup stateful deployment of postgres. Mark it as false when using a remotely hosted database | - | minio.image | minio/minio:latest | | Using this key, user must provide the docker image name to setup the stateful deployment of minio. (must be set when `minio.local_setup=true`) | - | minio.image_mc | minio/mc:latest | | Using this key, user must provide the docker image name to setup the job deployment of minio client. (must be set when `minio.local_setup=true`) | - | minio.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of minio. (must be set when `minio.local_setup=true`) | - | minio.volumeSize | 5Gi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | - | minio.root_user | admin | | Storage credentials are requried to access the hosted stateful deployment of minio. Use this key to set the username for the stateful deployment. | - | minio.root_password | password | | Storage credentials are requried to access the hosted stateful deployment of minio. Use this key to set the password for the stateful deployment. | - | minio.env.minio_endpoint_ssl | false | | (Optional) Env to enforce HTTPS when connecting to minio uploads bucket | - | env.docstore_bucket | uploads | Yes | Storage bucket name is required as part of configuration. This is where files will be uploaded irrespective of if you are using Minio or external S3 (or compatible) storage service | - | env.doc_upload_size_limit | 5242880 | Yes | Document Upload Size Limit (default to 5Mb) | - | env.aws_access_key | | | External S3 (or compatible) storage service provides access key for the application to connect and do the necessary upload/download operations. To be provided when `minio.local_setup=false` | - | env.aws_secret_access_key | | | External S3 (or compatible) storage service provides secret access key for the application to connect and do the necessary upload/download operations. To be provided when `minio.local_setup=false` | - | env.aws_region | | | External S3 (or compatible) storage service providers creates any buckets in user selected region. This is also shared with the user as region for the application to connect and do the necessary upload/download operations. To be provided when `minio.local_setup=false` | - | env.aws_s3_endpoint_url | | | External S3 (or compatible) storage service providers shares a endpoint_url for the integration purpose for the application to connect and do the necessary upload/download operations. To be provided when minio.`local_setup=false` | - | minio.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | - | minio.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | minio.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of minio. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | minio.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of minio. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | minio.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of minio. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | minio.labels | {} | | This key allows you to set custom labels for the stateful deployment of minio. This is useful for organizing and selecting resources in your Kubernetes cluster. | - | minio.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of minio. This is useful for adding metadata or configuration hints to your resources. | - - ##### Web Deployment - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | web.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | - | web.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | - | web.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | - | web.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | - | web.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | - | web.image | artifacts.plane.so/makeplane/plane-frontend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | - | web.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of web. | - | web.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | web.nodeSelector | {} | | This key allows you to set the node selector for the deployment of web. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | web.tolerations | [] | | This key allows you to set the tolerations for the deployment of web. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | web.affinity | {} | | This key allows you to set the affinity rules for the deployment of web. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | web.labels | {} | | Custom labels to add to the web deployment | - | web.annotations | {} | | Custom annotations to add to the web deployment | - - ##### Space Deployment - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | space.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | - | space.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | - | space.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | - | space.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | - | space.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | - | space.image | artifacts.plane.so/makeplane/plane-space | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | - | space.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of space. | - | space.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | space.nodeSelector | {} | | This key allows you to set the node selector for the deployment of space. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | space.tolerations | [] | | This key allows you to set the tolerations for the deployment of space. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | space.affinity | {} | | This key allows you to set the affinity rules for the deployment of space. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | space.labels | {} | | Custom labels to add to the space deployment | - | space.annotations | {} | | Custom annotations to add to the space deployment | - - ##### Admin Deployment - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | admin.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | - | admin.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | - | admin.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | - | admin.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | - | admin.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | - | admin.image | artifacts.plane.so/makeplane/plane-admin | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | - | admin.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of admin. | - | admin.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | admin.nodeSelector | {} | | This key allows you to set the node selector for the deployment of admin. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | admin.tolerations | [] | | This key allows you to set the tolerations for the deployment of admin. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | admin.affinity | {} | | This key allows you to set the affinity rules for the deployment of admin. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | admin.labels | {} | | Custom labels to add to the admin deployment | - | admin.annotations | {} | | Custom annotations to add to the admin deployment | - - ##### Live Service Deployment - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | live.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | - | live.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | - | live.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | - | live.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | - | live.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | - | live.image | artifacts.plane.so/makeplane/plane-live | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | - | live.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of live. | - | live.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | live.nodeSelector | {} | | This key allows you to set the node selector for the deployment of live. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | live.tolerations | [] | | This key allows you to set the tolerations for the deployment of live. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | live.affinity | {} | | This key allows you to set the affinity rules for the deployment of live. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | live_server_secret_key | htbqvBJAgpm9bzvf3r4urJer0ENReatceh | Yes | This key sets the secret key for the live server. This is required for secure communication and authentication in the live server component. | - | live.labels | {} | | Custom labels to add to the live deployment | - | live.annotations | {} | | Custom annotations to add to the live deployment | - - ##### API Deployment - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | api.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | - | api.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | - | api.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | - | api.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | - | api.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | - | api.image | artifacts.plane.so/makeplane/plane-backend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | - | api.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of api. | - | env.sentry_dsn | | | (optional) API service deployment comes with some of the preconfigured integration. Sentry is one among those. Here user can set the Sentry provided DSN for this integration. | - | env.sentry_environment | | | (optional) API service deployment comes with some of the preconfigured integration. Sentry is one among those. Here user can set the Sentry environment name (as configured in Sentry) for this integration. | - | env.api_key_rate_limit | 60/minute | | (optional) User can set the maximum number of requests the API can handle in a given time frame. | - | api.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | - | api.nodeSelector | {} | | This key allows you to set the node selector for the deployment of api. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | api.tolerations | [] | | This key allows you to set the tolerations for the deployment of api. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | api.affinity | {} | | This key allows you to set the affinity rules for the deployment of api. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | api.labels | {} | | Custom labels to add to the API deployment | - | api.annotations | {} | | Custom annotations to add to the API deployment | - - ##### Worker Deployment - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | worker.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | - | worker.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | - | worker.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | - | worker.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | - | worker.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | - | worker.image | artifacts.plane.so/makeplane/plane-backend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | - | worker.nodeSelector | {} | | This key allows you to set the node selector for the deployment of worker. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | worker.tolerations | [] | | This key allows you to set the tolerations for the deployment of worker. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | worker.affinity | {} | | This key allows you to set the affinity rules for the deployment of worker. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | worker.labels | {} | | Custom labels to add to the worker deployment | - | worker.annotations | {} | | Custom annotations to add to the worker deployment | - - ##### Beat-Worker Deployment - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | beatworker.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | - | beatworker.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | - | beatworker.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | - | beatworker.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | - | beatworker.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | - | beatworker.image | artifacts.plane.so/makeplane/plane-backend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | - | beatworker.nodeSelector | {} | | This key allows you to set the node selector for the deployment of beatworker. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | - | beatworker.tolerations | [] | | This key allows you to set the tolerations for the deployment of beatworker. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | - | beatworker.affinity | {} | | This key allows you to set the affinity rules for the deployment of beatworker. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | - | beatworker.labels | {} | | Custom labels to add to the beat-worker deployment | - | beatworker.annotations | {} | | Custom annotations to add to the beat-worker deployment | - - ##### Common Environment Settings - - | Setting | Default | Required | Description | - |---------|---------|----------|-------------| - | env.secret_key | 60gp0byfz2dvffa45cxl20p1scy9xbpf6d8c5y0geejgkyp1b5 | Yes | This must a random string which is used for hashing/encrypting the sensitive data within the application. Once set, changing this might impact the already hashed/encrypted data | - | env.default_cluster_domain | cluster.local | Yes | Set this value as configured in your kubernetes cluster. cluster.local is usally the default in most cases. | +3. Use one of the following ways to deploy Plane: - + **Quick setup** + + This is the fastest way to deploy Plane with default settings. This will create stateful deployments for Postgres, Redis, and Minio with a persistent volume claim using the `longhorn` storage class. This also sets up the ingress routes for you using `nginx` ingress class. + + ::: tip + To customize this, see `Custom ingress routes` below. + ::: + + Continue to be on the same Terminal window as you have so far, copy the code below, and paste it on your Terminal screen. + + ```bash + helm install plane-app makeplane/plane-ce \ + --create-namespace \ + --namespace plane-ce \ + --set planeVersion=stable \ + --set ingress.appHost="plane.example.com" \ + --set ingress.minioHost="plane-minio.example.com" \ + --set ingress.ingressClass=nginx \ + --set postgres.storageClass=longhorn \ + --set redis.storageClass=longhorn \ + --set minio.storageClass=longhorn \ + --timeout 10m \ + --wait \ + --wait-for-jobs + ``` + + ::: tip + This is the minimum required to set up Plane-CE. You can change the default namespace from `plane-ce`, the default app name from `plane-app`, the default storage class from `[postgres, redis, minio].storageClass`, and the default ingress class from `ingress.ingressClass` to whatever you would like to. + You can also pass other settings referring to `Configuration Settings` section. ::: + - **Advanced setup** + For more control over your set-up, run the script below to download the `values.yaml` file and and edit using any editor like Vim or Nano. + + ```bash + helm show values makeplane/plane-ce > values.yaml + vi values.yaml + ``` + + ::: tip + See **Configuration settings** below for more details. + ::: + + After saving the `values.yaml` file, continue to be on the same Terminal window as on the previous steps, copy the code below, and paste it on your Terminal screen. + + ```bash + helm install plane-app makeplane/plane-ce \ + --create-namespace \ + --namespace plane-ce \ + -f values.yaml \ + --timeout 10m \ + --wait \ + --wait-for-jobs + ``` + + #### Configuration settings + + ##### Plane Version + + | Setting | Default | Required | Description | + | ------------ | ------- | -------- | ----------- | + | planeVersion | v1.1.0 | Yes | | + + ##### Postgres DB Setup + + | Setting | Default | Required | Description | + | -------------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | postgres.local_setup | true | | Plane uses postgres as the primary database to store all the transactional data. This database can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws rds or similar services). Set this to true when you choose to setup stateful deployment of postgres. Mark it as false when using a remotely hosted database | + | postgres.image | postgres:15.7-alpine | | Using this key, user must provide the docker image name to setup the stateful deployment of postgres. (must be set when `postgres.local_setup=true`) | + | postgres.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of postgres. (must be set when `postgres.local_setup=true`) | + | postgres.servicePort | 5432 | | This key sets the default port number to be used while setting up stateful deployment of postgres. | + | postgres.volumeSize | 5Gi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | + | env.pgdb_username | plane | | Database credentials are requried to access the hosted stateful deployment of postgres. Use this key to set the username for the stateful deployment. | + | env.pgdb_password | plane | | Database credentials are requried to access the hosted stateful deployment of postgres. Use this key to set the password for the stateful deployment. | + | env.pgdb_name | plane | | Database name to be used while setting up stateful deployment of Postgres | + | env.pgdb_remote_url | | | Users can also decide to use the remote hosted database and link to Plane deployment. Ignoring all the above keys, set postgres.local_setup to false and set this key with remote connection url. | + | postgres.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | + | postgres.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | postgres.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of postgres. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | postgres.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of postgres. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | postgres.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of postgres. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | postgres.labels | {} | | This key allows you to set custom labels for the stateful deployment of postgres. This is useful for organizing and selecting resources in your Kubernetes cluster. | + | postgres.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of postgres. This is useful for adding metadata or configuration hints to your resources. | + + ##### Redis/Valkey Setup + + | Setting | Default | Required | Description | + | ----------------------- | ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | redis.local_setup | true | | Plane uses redis to cache the session authentication and other static data. This database can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws rds or similar services). Set this to true when you choose to setup stateful deployment of redis. Mark it as false when using a remotely hosted database | + | redis.image | `valkey/valkey:7.2.5-alpine` | | Using this key, user must provide the docker image name to setup the stateful deployment of redis. (must be set when redis.local_setup=true) | + | redis.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of redis. (must be set when `redis.local_setup=true`) | + | redis.servicePort | 6379 | | This key sets the default port number to be used while setting up stateful deployment of redis. | + | redis.volumeSize | 1Gi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | + | env.remote_redis_url | | | Users can also decide to use the remote hosted database and link to Plane deployment. Ignoring all the above keys, set redis.local_setup to false and set this key with remote connection url. | + | redis.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | + | redis.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | redis.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of redis. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | redis.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of redis. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | redis.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of redis. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | redis.labels | {} | | This key allows you to set custom labels for the stateful deployment of redis. This is useful for organizing and selecting resources in your Kubernetes cluster. | + | redis.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of redis. This is useful for adding metadata or configuration hints to your resources. | + + ##### RabbitMQ Setup + + | Setting | Default | Required | Description | + | ------------------------------ | --------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | rabbitmq.local_setup | true | | Plane uses rabbitmq as message queuing system. This can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws mq or similar services). Set this to true when you choose to setup stateful deployment of rabbitmq. Mark it as false when using a remotely hosted service | + | rabbitmq.image | rabbitmq:3.13.6-management-alpine | | Using this key, user must provide the docker image name to setup the stateful deployment of rabbitmq. (must be set when `rabbitmq.local_setup=true`) | + | rabbitmq.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of rabbitmq. (must be set when `rabbitmq.local_setup=true`) | + | rabbitmq.servicePort | 5672 | | This key sets the default port number to be used while setting up stateful deployment of rabbitmq. | + | rabbitmq.managementPort | 15672 | | This key sets the default management port number to be used while setting up stateful deployment of rabbitmq. | + | rabbitmq.volumeSize | 100Mi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | + | rabbitmq.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | + | rabbitmq.default_user | plane | | Credentials are requried to access the hosted stateful deployment of rabbitmq. Use this key to set the username for the stateful deployment. | + | rabbitmq.default_password | plane | | Credentials are requried to access the hosted stateful deployment of rabbitmq. Use this key to set the password for the stateful deployment. | + | rabbitmq.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | rabbitmq.external_rabbitmq_url | | | Users can also decide to use the remote hosted service and link to Plane deployment. Ignoring all the above keys, set rabbitmq.local_setup to false and set this key with remote connection url. | + | rabbitmq.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of rabbitmq. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | rabbitmq.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of rabbitmq. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | rabbitmq.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of rabbitmq. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | rabbitmq.labels | {} | | This key allows you to set custom labels for the stateful deployment of rabbitmq. This is useful for organizing and selecting resources in your Kubernetes cluster. | + | rabbitmq.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of rabbitmq. This is useful for adding metadata or configuration hints to your resources. | + + ##### Doc Store (Minio/S3) Setup + + | Setting | Default | Required | Description | + | ---------------------------- | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | + | minio.local_setup | true | | Plane uses minio as the default file storage drive. This storage can be hosted within kubernetes as part of helm chart deployment or can be used as hosted service remotely (e.g. aws S3 or similar services). Set this to true when you choose to setup stateful deployment of postgres. Mark it as false when using a remotely hosted database | + | minio.image | minio/minio:latest | | Using this key, user must provide the docker image name to setup the stateful deployment of minio. (must be set when `minio.local_setup=true`) | + | minio.image_mc | minio/mc:latest | | Using this key, user must provide the docker image name to setup the job deployment of minio client. (must be set when `minio.local_setup=true`) | + | minio.pullPolicy | IfNotPresent | | Using this key, user can set the pull policy for the stateful deployment of minio. (must be set when `minio.local_setup=true`) | + | minio.volumeSize | 5Gi | | While setting up the stateful deployment, while creating the persistant volume, volume allocation size need to be provided. This key helps you set the volume allocation size. Unit of this value must be in Mi (megabyte) or Gi (gigabyte) | + | minio.root_user | admin | | Storage credentials are requried to access the hosted stateful deployment of minio. Use this key to set the username for the stateful deployment. | + | minio.root_password | password | | Storage credentials are requried to access the hosted stateful deployment of minio. Use this key to set the password for the stateful deployment. | + | minio.env.minio_endpoint_ssl | false | | (Optional) Env to enforce HTTPS when connecting to minio uploads bucket | + | env.docstore_bucket | uploads | Yes | Storage bucket name is required as part of configuration. This is where files will be uploaded irrespective of if you are using Minio or external S3 (or compatible) storage service | + | env.doc_upload_size_limit | 5242880 | Yes | Document Upload Size Limit (default to 5Mb) | + | env.aws_access_key | | | External S3 (or compatible) storage service provides access key for the application to connect and do the necessary upload/download operations. To be provided when `minio.local_setup=false` | + | env.aws_secret_access_key | | | External S3 (or compatible) storage service provides secret access key for the application to connect and do the necessary upload/download operations. To be provided when `minio.local_setup=false` | + | env.aws_region | | | External S3 (or compatible) storage service providers creates any buckets in user selected region. This is also shared with the user as region for the application to connect and do the necessary upload/download operations. To be provided when `minio.local_setup=false` | + | env.aws_s3_endpoint_url | | | External S3 (or compatible) storage service providers shares a endpoint_url for the integration purpose for the application to connect and do the necessary upload/download operations. To be provided when minio.`local_setup=false` | + | minio.storageClass | `` | | Creating the persitant volumes for the stateful deployments needs the storageClass name. Set the correct value as per your kubernetes cluster configuration. | + | minio.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | minio.nodeSelector | {} | | This key allows you to set the node selector for the stateful deployment of minio. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | minio.tolerations | [] | | This key allows you to set the tolerations for the stateful deployment of minio. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | minio.affinity | {} | | This key allows you to set the affinity rules for the stateful deployment of minio. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | minio.labels | {} | | This key allows you to set custom labels for the stateful deployment of minio. This is useful for organizing and selecting resources in your Kubernetes cluster. | + | minio.annotations | {} | | This key allows you to set custom annotations for the stateful deployment of minio. This is useful for adding metadata or configuration hints to your resources. | + + ##### Web Deployment + + | Setting | Default | Required | Description | + | --------------------- | ------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | web.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | + | web.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | + | web.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | + | web.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | + | web.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | + | web.image | artifacts.plane.so/makeplane/plane-frontend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | + | web.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of web. | + | web.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | web.nodeSelector | {} | | This key allows you to set the node selector for the deployment of web. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | web.tolerations | [] | | This key allows you to set the tolerations for the deployment of web. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | web.affinity | {} | | This key allows you to set the affinity rules for the deployment of web. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | web.labels | {} | | Custom labels to add to the web deployment | + | web.annotations | {} | | Custom annotations to add to the web deployment | + + ##### Space Deployment + + | Setting | Default | Required | Description | + | ----------------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | space.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | + | space.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | + | space.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | + | space.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | + | space.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | + | space.image | artifacts.plane.so/makeplane/plane-space | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | + | space.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of space. | + | space.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | space.nodeSelector | {} | | This key allows you to set the node selector for the deployment of space. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | space.tolerations | [] | | This key allows you to set the tolerations for the deployment of space. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | space.affinity | {} | | This key allows you to set the affinity rules for the deployment of space. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | space.labels | {} | | Custom labels to add to the space deployment | + | space.annotations | {} | | Custom annotations to add to the space deployment | + + ##### Admin Deployment + + | Setting | Default | Required | Description | + | ----------------------- | ---------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | admin.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | + | admin.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | + | admin.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | + | admin.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | + | admin.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | + | admin.image | artifacts.plane.so/makeplane/plane-admin | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | + | admin.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of admin. | + | admin.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | admin.nodeSelector | {} | | This key allows you to set the node selector for the deployment of admin. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | admin.tolerations | [] | | This key allows you to set the tolerations for the deployment of admin. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | admin.affinity | {} | | This key allows you to set the affinity rules for the deployment of admin. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | admin.labels | {} | | Custom labels to add to the admin deployment | + | admin.annotations | {} | | Custom annotations to add to the admin deployment | + + ##### Live Service Deployment + + | Setting | Default | Required | Description | + | ---------------------- | --------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | live.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | + | live.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | + | live.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | + | live.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | + | live.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | + | live.image | artifacts.plane.so/makeplane/plane-live | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | + | live.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of live. | + | live.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | live.nodeSelector | {} | | This key allows you to set the node selector for the deployment of live. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | live.tolerations | [] | | This key allows you to set the tolerations for the deployment of live. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | live.affinity | {} | | This key allows you to set the affinity rules for the deployment of live. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | live_server_secret_key | htbqvBJAgpm9bzvf3r4urJer0ENReatceh | Yes | This key sets the secret key for the live server. This is required for secure communication and authentication in the live server component. | + | live.labels | {} | | Custom labels to add to the live deployment | + | live.annotations | {} | | Custom annotations to add to the live deployment | + + ##### API Deployment + + | Setting | Default | Required | Description | + | ---------------------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | api.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | + | api.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | + | api.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | + | api.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | + | api.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | + | api.image | artifacts.plane.so/makeplane/plane-backend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | + | api.pullPolicy | Always | | Using this key, user can set the pull policy for the deployment of api. | + | env.sentry_dsn | | | (optional) API service deployment comes with some of the preconfigured integration. Sentry is one among those. Here user can set the Sentry provided DSN for this integration. | + | env.sentry_environment | | | (optional) API service deployment comes with some of the preconfigured integration. Sentry is one among those. Here user can set the Sentry environment name (as configured in Sentry) for this integration. | + | env.api_key_rate_limit | 60/minute | | (optional) User can set the maximum number of requests the API can handle in a given time frame. | + | api.assign_cluster_ip | false | | Set it to true if you want to assign ClusterIP to the service | + | api.nodeSelector | {} | | This key allows you to set the node selector for the deployment of api. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | api.tolerations | [] | | This key allows you to set the tolerations for the deployment of api. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | api.affinity | {} | | This key allows you to set the affinity rules for the deployment of api. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | api.labels | {} | | Custom labels to add to the API deployment | + | api.annotations | {} | | Custom annotations to add to the API deployment | + + ##### Worker Deployment + + | Setting | Default | Required | Description | + | -------------------- | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | worker.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | + | worker.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | + | worker.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | + | worker.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | + | worker.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | + | worker.image | artifacts.plane.so/makeplane/plane-backend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | + | worker.nodeSelector | {} | | This key allows you to set the node selector for the deployment of worker. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | worker.tolerations | [] | | This key allows you to set the tolerations for the deployment of worker. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | worker.affinity | {} | | This key allows you to set the affinity rules for the deployment of worker. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | worker.labels | {} | | Custom labels to add to the worker deployment | + | worker.annotations | {} | | Custom annotations to add to the worker deployment | + + ##### Beat-Worker Deployment + + | Setting | Default | Required | Description | + | ------------------------ | ------------------------------------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | beatworker.replicas | 1 | Yes | Kubernetes helps you with scaling up/down the deployments. You can run 1 or more pods for each deployment. This key helps you setting up number of replicas you want to run for this deployment. It must be `>=1` | + | beatworker.memoryLimit | 1000Mi | | Every deployment in kubernetes can be set to use maximum memory they are allowed to use. This key sets the memory limit for this deployment to use. | + | beatworker.cpuLimit | 500m | | Every deployment in kubernetes can be set to use maximum cpu they are allowed to use. This key sets the cpu limit for this deployment to use. | + | beatworker.memoryRequest | 50Mi | | Every deployment in kubernetes can be set to use minimum memory they are allowed to use. This key sets the memory request for this deployment to use. | + | beatworker.cpuRequest | 50m | | Every deployment in kubernetes can be set to use minimum cpu they are allowed to use. This key sets the cpu request for this deployment to use. | + | beatworker.image | artifacts.plane.so/makeplane/plane-backend | | This deployment needs a preconfigured docker image to function. Docker image name is provided by the owner and must not be changed for this deployment | + | beatworker.nodeSelector | {} | | This key allows you to set the node selector for the deployment of beatworker. This is useful when you want to run the deployment on specific nodes in your Kubernetes cluster. | + | beatworker.tolerations | [] | | This key allows you to set the tolerations for the deployment of beatworker. This is useful when you want to run the deployment on nodes with specific taints in your Kubernetes cluster. | + | beatworker.affinity | {} | | This key allows you to set the affinity rules for the deployment of beatworker. This is useful when you want to control how pods are scheduled on nodes in your Kubernetes cluster. | + | beatworker.labels | {} | | Custom labels to add to the beat-worker deployment | + | beatworker.annotations | {} | | Custom annotations to add to the beat-worker deployment | + + ##### Common Environment Settings + + | Setting | Default | Required | Description | + | -------------------------- | -------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | env.secret_key | 60gp0byfz2dvffa45cxl20p1scy9xbpf6d8c5y0geejgkyp1b5 | Yes | This must a random string which is used for hashing/encrypting the sensitive data within the application. Once set, changing this might impact the already hashed/encrypted data | + | env.default_cluster_domain | cluster.local | Yes | Set this value as configured in your kubernetes cluster. cluster.local is usally the default in most cases. | diff --git a/docs/self-hosting/methods/one-click.md b/docs/self-hosting/methods/one-click.md index d8806a0..da751dc 100644 --- a/docs/self-hosting/methods/one-click.md +++ b/docs/self-hosting/methods/one-click.md @@ -4,10 +4,10 @@ description: Deploy Plane instantly with one-click installers on popular cloud p keywords: plane one-click deploy, cloud deployment, aws plane, digitalocean plane, quick install, plane cloud hosting, self-hosting --- - # One-click deploy ::: infoThis feature is included in our paid plans, but for a limited time, our community users can access it for free.::: + ### Requirements - Operating systems: Debian, Ubuntu, CentOS @@ -45,7 +45,6 @@ Use `plane-app` [OPERATOR] to manage your Plane instance easily. Get a list of a ![Plane Help](/images/one-click-deploy/one-click-help.png) 1. Basic operators - 1. `plane-app start` starts the Plane server. 2. `plane-app restart` restarts the Plane server. 3. `plane-app stop` stops the Plane server. @@ -54,16 +53,15 @@ Use `plane-app` [OPERATOR] to manage your Plane instance easily. Get a list of a `plane-app --configure` will show advanced configurators. ![Advanced operators](/images/one-click-deploy/one-click-advanced.png) - - - Change your proxy or listening port + - Change your proxy or listening port
Default: 80
- - Change your domain name + - Change your domain name
Default: Deployed server's public IP address
- - File upload size -
Default: 5MB
- - Specify external database address when using an external database -
Default: `Empty`
-
Default folder: `/opt/plane/data/postgres`
+ - File upload size +
Default: 5MB
+ - Specify external database address when using an external database +
Default: `Empty`
+
Default folder: `/opt/plane/data/postgres`
- Specify external Redis URL when using external Redis
Default: `Empty`
Default folder: `/opt/plane/data/redis`
@@ -72,9 +70,8 @@ Use `plane-app` [OPERATOR] to manage your Plane instance easily. Get a list of a
Default folder: `/opt/plane/data/minio`
3. Version operators - 1. `plane-app --upgrade` gets the latest stable version of `docker-compose.yaml`, `.env`, and Docker images 2. `plane-app --update-installer` updates the installer and the `plane-app` utility. 3. `plane-app --uninstall` uninstalls the Plane application and all Docker containers from the server but leaves the data stored in Postgres, Redis, and Minio alone. - 4. `plane-app --install` installs the Plane app again. \ No newline at end of file + 4. `plane-app --install` installs the Plane app again. diff --git a/docs/self-hosting/methods/overview.md b/docs/self-hosting/methods/overview.md index ead94c0..b07c160 100644 --- a/docs/self-hosting/methods/overview.md +++ b/docs/self-hosting/methods/overview.md @@ -61,4 +61,4 @@ For environments without internet access or with strict security requirements: Deploy in airgapped Kubernetes clusters using Helm charts with offline images. - \ No newline at end of file + diff --git a/docs/self-hosting/methods/podman-quadlets.md b/docs/self-hosting/methods/podman-quadlets.md index 0e85aec..b9163e6 100644 --- a/docs/self-hosting/methods/podman-quadlets.md +++ b/docs/self-hosting/methods/podman-quadlets.md @@ -4,47 +4,54 @@ description: Install Plane using Podman Quadlets. Guide for deploying Plane with keywords: plane podman, podman quadlets, systemd containers, docker alternative, rootless containers, plane podman deployment, self-hosting --- - # Deploy Plane with Podman Quadlets + This guide shows you the steps to deploy a self-hosted instance of Plane using Podman Quadlets. ## Prerequisites + Before we start, make sure you've got these covered: - A non-root user account with `systemd --user support` (most modern Linux setups have this) - Podman version **4.4 or higher** ## Set up Podman + 1. Add the Podman repository. - ```bash - echo 'deb http://download.opensuse.org/repositories/home:/alvistack/Debian_12/ /' | sudo tee /etc/apt/sources.list.d/home:alvistack.list - ``` + + ```bash + echo 'deb http://download.opensuse.org/repositories/home:/alvistack/Debian_12/ /' | sudo tee /etc/apt/sources.list.d/home:alvistack.list + ``` 2. Add the GPG key. - ```bash - curl -fsSL https://download.opensuse.org/repositories/home:alvistack/Debian_12/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_alvistack.gpg > /dev/null - ``` + + ```bash + curl -fsSL https://download.opensuse.org/repositories/home:alvistack/Debian_12/Release.key | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/home_alvistack.gpg > /dev/null + ``` 3. Refresh your package lists. - ```bash - sudo apt update - ``` + + ```bash + sudo apt update + ``` 4. Install Podman and its dependencies. - ```bash - sudo apt install -y podman uidmap netavark passt - ``` - The `uidmap` package handles user namespace mapping, `netavark` takes care of networking, and `passt` helps with network connectivity. + ```bash + sudo apt install -y podman uidmap netavark passt + ``` + + The `uidmap` package handles user namespace mapping, `netavark` takes care of networking, and `passt` helps with network connectivity. + +5. Download and extract Podman Quadlets. -5. Download and extract Podman Quadlets. - ```bash - mkdir podman-quadlets - curl -fsSL https://prime.plane.so/releases/v2.3.1/podman-quadlets.tar.gz -o podman-quadlets.tar.gz - tar -xvzf podman-quadlets.tar.gz -C podman-quadlets - ``` + ```bash + mkdir podman-quadlets + curl -fsSL https://prime.plane.so/releases/v2.3.1/podman-quadlets.tar.gz -o podman-quadlets.tar.gz + tar -xvzf podman-quadlets.tar.gz -C podman-quadlets + ``` - The directory contains an `install.sh` script that will handle the installation and configuration. + The directory contains an `install.sh` script that will handle the installation and configuration. ## Install Plane @@ -55,12 +62,15 @@ The installation script sets up Plane and configures all required services. You ```bash ./install.sh --domain your-domain.com --base-dir /your/custom/path ``` + This installs Plane in your specified directory, which is useful if you want to maintain control over the installation location. ### With sudo access + ```bash ./install.sh --domain your-domain.com ``` + This installs Plane in `/opt/plane`, which is a standard system location. ::: info @@ -91,64 +101,74 @@ Note that you should run these commands without `sudo`. ::: 1. Reload systemd to recognize new configurations. - ```bash - systemctl --user daemon-reload - ``` + + ```bash + systemctl --user daemon-reload + ``` 2. Start the network service. - ```bash - systemctl --user start plane-nw-network.service - ``` + + ```bash + systemctl --user start plane-nw-network.service + ``` 3. Start core dependencies. - ```bash - systemctl --user start plane-{db,redis,mq,minio}.service - ``` + + ```bash + systemctl --user start plane-{db,redis,mq,minio}.service + ``` 4. Start backend services. - ```bash - systemctl --user start {api,worker,beat-worker,migrator,monitor}.service - ``` + + ```bash + systemctl --user start {api,worker,beat-worker,migrator,monitor}.service + ``` 5. Start frontend services. - ```bash - systemctl --user start {web,space,admin,live,proxy}.service - ``` - The startup sequence is important: network first, then dependencies, followed by backend services, and finally frontend services. + ```bash + systemctl --user start {web,space,admin,live,proxy}.service + ``` + + The startup sequence is important: network first, then dependencies, followed by backend services, and finally frontend services. 6. If you've purchased a paid plan, [activate your license key](/self-hosting/manage/manage-licenses/activate-pro-and-business#activate-your-license) to unlock premium features. ### Verify service status + Check that all services are running correctly: 1. Check network status. - ```bash - systemctl --user status plane-nw-network.service - ``` + + ```bash + systemctl --user status plane-nw-network.service + ``` 2. Check core dependencies. - ```bash - systemctl --user status plane-{db,redis,mq,minio}.service - ``` + + ```bash + systemctl --user status plane-{db,redis,mq,minio}.service + ``` 3. Check backend services. - ```bash - systemctl --user status {api,worker,beat-worker,migrator,monitor}.service - ``` + + ```bash + systemctl --user status {api,worker,beat-worker,migrator,monitor}.service + ``` 4. Check frontend services. - ```bash - systemctl --user status {web,space,admin,live,proxy}.service - ``` + ```bash + systemctl --user status {web,space,admin,live,proxy}.service + ``` Your Plane installation should now be running successfully with Podman Quadlets. This setup provides automatic service restart capabilities and standard systemd management commands for maintaining your installation. ## Troubleshoot To debug service issues, examine the logs using: + ```bash journalctl --user -u --no-pager ``` -The logs will provide detailed information about any configuration issues or errors that may occur. \ No newline at end of file +The logs will provide detailed information about any configuration issues or errors that may occur. diff --git a/docs/self-hosting/methods/portainer.md b/docs/self-hosting/methods/portainer.md index b546039..91ebe6d 100644 --- a/docs/self-hosting/methods/portainer.md +++ b/docs/self-hosting/methods/portainer.md @@ -18,17 +18,22 @@ This guide shows you the steps to deploy a self-hosted instance of Plane using P ### Procedure 1. **Download the required deployment files** - - `portainer-compose.yml` – Defines Plane's services and dependencies. - ```bash - curl -fsSL https://prime.plane.so/releases//portainer-compose.yml -o portainer-compose.yml - ``` - - `variables.env` – Stores environment variables for your deployment. - ```bash - curl -fsSL https://prime.plane.so/releases//variables.env -o plane.env - ``` - ::: warning - The `` value should be v1.8.2 or higher. - ::: + + `portainer-compose.yml` – Defines Plane's services and dependencies. + + ```bash + curl -fsSL https://prime.plane.so/releases//portainer-compose.yml -o portainer-compose.yml + ``` + + `variables.env` – Stores environment variables for your deployment. + + ```bash + curl -fsSL https://prime.plane.so/releases//variables.env -o plane.env + ``` + + ::: warning + The `` value should be v1.8.2 or higher. + ::: 2. Click **+ Add stack** on Portainer. diff --git a/docs/self-hosting/overview.md b/docs/self-hosting/overview.md index 769a1de..948aa29 100644 --- a/docs/self-hosting/overview.md +++ b/docs/self-hosting/overview.md @@ -4,7 +4,6 @@ description: Deploy Plane on your own infrastructure with Docker, Kubernetes, or keywords: self-host plane, plane docker, plane kubernetes, self-hosted project management, docker compose plane, kubernetes helm plane, on-premise deployment --- - # Deploy Plane on your infrastructure Take complete control of your project management infrastructure by deploying Plane on your own servers. Self-hosting Plane gives you full ownership of your data and the flexibility to deploy wherever you need - from a single Docker container to enterprise Kubernetes clusters. @@ -39,6 +38,7 @@ Choose the deployment method that best fits your infrastructure and team size: [Other deployment methods](/self-hosting/methods/overview) ## System requirements + - **CPU:** 2 cores - **RAM:** 4GB (8GB recommended for production) - **OS:** Linux (Ubuntu 20.04+, Debian 10+, CentOS 8+), macOS, or Windows with WSL2 @@ -64,7 +64,3 @@ Once deployed, configure your Plane instance to match your organization's needs: Connect to managed databases (PostgreSQL, Redis) and cloud storage (S3, MinIO, GCS) for scalable, production-ready deployments. - - - - diff --git a/docs/self-hosting/plane-architecture.md b/docs/self-hosting/plane-architecture.md index eb514de..93ac69f 100644 --- a/docs/self-hosting/plane-architecture.md +++ b/docs/self-hosting/plane-architecture.md @@ -4,7 +4,6 @@ description: Understand Plane self-hosted architecture including web server, API keywords: plane architecture, plane system design, plane components, plane services, postgresql, redis, minio, plane infrastructure --- - # Plane self-hosted architecture Plane consists of multiple services working together to provide project management capabilities. @@ -68,4 +67,4 @@ Message queue for asynchronous task processing. Workers pull jobs from queues fo Object storage for file uploads, attachments, and generated exports; can be replaced with any S3-compatible storage system. **OpenSearch** -Optional search indexing service for enhanced search capabilities. Not required for basic Plane functionality. \ No newline at end of file +Optional search indexing service for enhanced search capabilities. Not required for basic Plane functionality. diff --git a/docs/self-hosting/telemetry.md b/docs/self-hosting/telemetry.md index 54dabc8..5924d84 100644 --- a/docs/self-hosting/telemetry.md +++ b/docs/self-hosting/telemetry.md @@ -4,7 +4,6 @@ description: Understand what telemetry data Plane collects, how it is used, and keywords: plane telemetry, data collection, plane privacy, analytics opt-out, plane usage data, self-hosted privacy --- - # Data collection and usage Plane collects anonymized data to enhance your user experience, ensure product stability, and drive continuous improvements. This article talks about what we collect, what we don't, and how we use collected data. @@ -14,65 +13,73 @@ Plane collects anonymized data to enhance your user experience, ensure product s With the exception of the instance admin's email address on self-hosted Plane, we don't collect any personally identifiable information (PII). All usage data is anonymized and isn't connected to individual users. ### Instance admin details + Plane collects just the instance admin's name and email to communicate essential upgrade news, security alerts, and other critical notifications. ### Instance setup + When an instance is created, Plane collects just the instance ID so we can track upgrades and troubleshoot paid features. ### Usage for billing + Plane tracks the number of workspaces, members, and roles to bill you correctly and ensure accurate reporting in your workspace's **Billing and plans** screen and the Prime portal. ### Application data + Plane tracks anonymized workspace activity, including but not limited to the number of projects, issues, cycles, modules, comments, issue types, custom properties, timesheet downloads, active importers, and integrations. This data helps us understand product usage, adoption, and build new features. ### User interaction and behavior + Plane collects anonymized data for how you work with Plane when creating, updating, or deleting Plane entities, including but not restricted to projects, issues, cycles, modules, and others. This data helps us understand user journeys, pain points, and overall behavior. ### Performance data + Plane collects machine configurations, environment details, OS flavors, network throughput, and stack traces to help troubleshoot and prevent performance hiccups. ## Data sample + ```json - { - "Created At": "October 7, 2024, 1:50 PM", - "Page Count": "14", - "Is Telemetry Enabled": "true", - "Updated At": "October 7, 2024, 1:50 PM", - "User Count": "97", - "Cycle Count": "62", - "Cycle Issue Count": "710", - "Module Issue Count": "428", - "ID": "1234567890", - "Updated By ID": null, - "Current Version": "0.23.0", - "Issue Count": "2,000", - "Instance ID": "1234567890", - "Latest Version": "0.23.0", - "Module Count": "81", - "Name": "Test", - "Workspace Count": "11", - "Project Count": "20", - } +{ + "Created At": "October 7, 2024, 1:50 PM", + "Page Count": "14", + "Is Telemetry Enabled": "true", + "Updated At": "October 7, 2024, 1:50 PM", + "User Count": "97", + "Cycle Count": "62", + "Cycle Issue Count": "710", + "Module Issue Count": "428", + "ID": "1234567890", + "Updated By ID": null, + "Current Version": "0.23.0", + "Issue Count": "2,000", + "Instance ID": "1234567890", + "Latest Version": "0.23.0", + "Module Count": "81", + "Name": "Test", + "Workspace Count": "11", + "Project Count": "20" +} ``` ## How we use the data - **Improving your experience** -Analyzing real-world usage guides us in making Plane more intuitive and user-friendly. + Analyzing real-world usage guides us in making Plane more intuitive and user-friendly. - **Detecting and fixing bugs** -Identifying bugs and errors as they occur enables us to quickly investigate and fix issues, minimize downtime, and improve product performance. + Identifying bugs and errors as they occur enables us to quickly investigate and fix issues, minimize downtime, and improve product performance. -- **Enhancing security** -Monitoring for abnormal patterns helps us identify and mitigate potential security threats or vulnerabilities, ensuring data protection and platform integrity. +- **Enhancing security** + Monitoring for abnormal patterns helps us identify and mitigate potential security threats or vulnerabilities, ensuring data protection and platform integrity. - **Driving product decisions** -Understanding how you interact with Plane helps us prioritize future developments and focus on high-impact features and improvements that drive better outcomes. + Understanding how you interact with Plane helps us prioritize future developments and focus on high-impact features and improvements that drive better outcomes. ## Disable telemetry + As much as we'd love to understand your usage better, we agree that you should be in control of your data. If for any reason you don't want to send us that data, you can turn telemetry collection off in three clicks. 1. Go to your instance's God Mode by appending `/god-mode` to the domain you have hosted Plane on. 2. In the **General Settings** pane on the right, disable the **Telemetry** toggle button. - ![Disable telemetry](/images/disable-telemetry.webp) -3. Click **Save changes**. \ No newline at end of file + ![Disable telemetry](/images/disable-telemetry.webp) +3. Click **Save changes**. diff --git a/docs/self-hosting/troubleshoot/cli-errors.md b/docs/self-hosting/troubleshoot/cli-errors.md index 800903f..ebc44eb 100644 --- a/docs/self-hosting/troubleshoot/cli-errors.md +++ b/docs/self-hosting/troubleshoot/cli-errors.md @@ -4,7 +4,6 @@ description: Troubleshoot cli errors. Common issues, error messages, and solutio keywords: plane cli errors, prime cli troubleshooting, command line issues, plane cli fix, self-hosting troubleshooting --- - # CLI errors This page helps you troubleshoot common issues you might run into when using the Plane CLI tools. It covers potential causes of errors and provides straightforward steps to resolve them. @@ -19,10 +18,10 @@ This error typically happens if you're using an older version of the Prime CLI. 1. Start by taking a [data backup](/self-hosting/manage/backup-restore#backup-data) to be safe. 2. Run this command to remove the existing CLI: - ```bash - rm -rf /usr/bin/prime-cli - ``` + ```bash + rm -rf /usr/bin/prime-cli + ``` 3. Install the latest version of the CLI with: - ```bash - curl -fsSL https://prime.plane.so/install/ | sh - ``` \ No newline at end of file + ```bash + curl -fsSL https://prime.plane.so/install/ | sh + ``` diff --git a/docs/self-hosting/troubleshoot/installation-errors.md b/docs/self-hosting/troubleshoot/installation-errors.md index e9150db..25a15ea 100644 --- a/docs/self-hosting/troubleshoot/installation-errors.md +++ b/docs/self-hosting/troubleshoot/installation-errors.md @@ -4,7 +4,6 @@ description: Troubleshoot installation errors. Common issues, error messages, an keywords: plane installation errors, deployment issues, docker errors, kubernetes errors, plane setup troubleshooting, self-hosting --- - # Installation errors This guide is designed to help you resolve common issues encountered while installing Plane. Each section includes potential causes and step-by-step solutions for identified problems. @@ -27,4 +26,4 @@ This guide is designed to help you resolve common issues encountered while insta This error typically occurs if you have configured an external database that is running on localhost. Since the connection is being attempted from inside the container, localhost won’t work, as the database is not running within the container. -To resolve this issue, ensure that the database is hosted on a network-accessible server rather than localhost. Update the database URL to reflect the correct server address. See [how to configure external db](/self-hosting/govern/database-and-storage). \ No newline at end of file +To resolve this issue, ensure that the database is hosted on a network-accessible server rather than localhost. Update the database URL to reflect the correct server address. See [how to configure external db](/self-hosting/govern/database-and-storage). diff --git a/docs/self-hosting/troubleshoot/license-errors.md b/docs/self-hosting/troubleshoot/license-errors.md index 1b99137..4e8f3b1 100644 --- a/docs/self-hosting/troubleshoot/license-errors.md +++ b/docs/self-hosting/troubleshoot/license-errors.md @@ -4,7 +4,6 @@ description: Troubleshoot Plane license activation errors. Fix common issues wit keywords: plane license errors, license activation issues, license troubleshooting, plane license fix, commercial license, self-hosting --- - # Errors related to licenses This guide is designed to help you resolve common issues encountered while activating the license key for a workspace. Each section includes potential causes and step-by-step solutions for identified problems. @@ -21,7 +20,6 @@ If the issue persists after syncing or you see other errors, continue with the s Error: Your license is invalid or already in use. - - This issue usually occurs when your server has trouble connecting to ours to verify the license. Try running `prime-cli restart`, and it should resolve the problem. - If you migrated Plane to a new server without first [delinking the license key](/self-hosting/manage/manage-licenses/activate-pro-and-business#delink-license-key) from the old server, this error might happen. In that case, please reach out to the support team to have the license key delinked. For future reference, if you need to reinstall Plane or move to another server, follow [this guide](/self-hosting/manage/migrate-plane) to ensure a smooth transition. @@ -45,9 +43,9 @@ Updating typically resolves this issue. If the problem persists, double-check yo Error: Payment server is not configured -This usually occurs when the environment confiuration is incorrect. The Env variable `payment_server_url` is missing in the setup. In this case, follow the below steps. +This usually occurs when the environment confiuration is incorrect. The Env variable `payment_server_url` is missing in the setup. In this case, follow the below steps. 1. Backup the `plane.env` file. See [Backup plane.env](/self-hosting/manage/backup-restore#backup-plane-env). 2. Run `prime-cli repair` to allow Prime CLI to attempt automatic fixes to the `plane.env` file. 3. Try activating your workspace with the license key. -3. If needed, you can configure the instance in [God mode](/self-hosting/govern/instance-admin#settings) or adjust the environment variables directly in the new plane.env file. \ No newline at end of file +4. If needed, you can configure the instance in [God mode](/self-hosting/govern/instance-admin#settings) or adjust the environment variables directly in the new plane.env file. diff --git a/docs/self-hosting/troubleshoot/storage-errors.md b/docs/self-hosting/troubleshoot/storage-errors.md index 1a78574..bdefab0 100644 --- a/docs/self-hosting/troubleshoot/storage-errors.md +++ b/docs/self-hosting/troubleshoot/storage-errors.md @@ -4,7 +4,6 @@ description: Troubleshoot Plane storage and upload errors. Fix S3, MinIO, and fi keywords: plane storage errors, s3 errors, minio issues, file upload errors, storage troubleshooting, plane uploads, self-hosting --- - # Storage errors This guide is designed to help you resolve common issues encountered while configuring storage in Plane. Each section includes potential causes and step-by-step solutions for identified problems. @@ -19,50 +18,54 @@ This error occurs when the bucket policy exceeds the 20KB size limit allowed by To resolve this issue, you can define a streamlined bucket policy file and apply it correctly within the MinIO container. Follow these steps: -1. **Create a bucket policy JSON file** - - On your local machine, create a file named `bucket-policy.json` with the following content: - ```json - { - "Version": "2012-10-17", - "Statement": [ - { - "Effect": "Allow", - "Principal": { - "AWS": ["*"] - }, - "Action": ["s3:GetObject"], - "Resource": ["arn:aws:s3:::uploads/*"], - "Condition": { - "StringEquals": { - "s3:ExistingObjectTag/publicAccess": ["true"] - } - } - } - ] - } - ``` - - - Save this file in an accessible location. +1. **Create a bucket policy JSON file** + - On your local machine, create a file named `bucket-policy.json` with the following content: + + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Principal": { + "AWS": ["*"] + }, + "Action": ["s3:GetObject"], + "Resource": ["arn:aws:s3:::uploads/*"], + "Condition": { + "StringEquals": { + "s3:ExistingObjectTag/publicAccess": ["true"] + } + } + } + ] + } + ``` + + - Save this file in an accessible location. 2. **Set up and apply the policy** -::: warning -**IMPORTANT** -Make sure to execute all the `mc` commands **within the MinIO container** (either by attaching to it or using `docker exec`). -::: + ::: warning + **IMPORTANT** + Make sure to execute all the `mc` commands **within the MinIO container** (either by attaching to it or using `docker exec`). + ::: - Configure MinIO alias: + ```bash mc alias set myminio http://plane-plane-minio:9000 ``` - + Replace `plane-plane-minio:9000` with your MinIO server address. - Tag existing objects: + ```bash mc find myminio/uploads --exec "mc tag set {} publicAccess=true" ``` - + - Copy the policy file to the MinIO container: + ```bash docker cp bucket-policy.json :/tmp ``` @@ -70,23 +73,25 @@ docker cp bucket-policy.json :/tmp Replace `` with the actual ID of your MinIO container. You can find the container ID by running `docker ps`. - Apply the policy to the bucket: + ```bash mc anonymous set-json /tmp/bucket-policy.json myminio/uploads ``` -3. **Verification** +3. **Verification** + - Verify that objects are correctly tagged: - - Verify that objects are correctly tagged: - ```bash - mc tag list myminio/uploads/ - ``` + ```bash + mc tag list myminio/uploads/ + ``` - - Test public access using: - ```bash - curl http://:9000/uploads/ - ``` + - Test public access using: + ```bash + curl http://:9000/uploads/ + ``` ### Notes + - Verify that the `access-key` and `secret-key` used for setting up the alias have adequate permissions to manage the bucket. -- If your MinIO server is hosted on a different machine or address, replace `plane-plane-minio:9000` with the appropriate server URL. -- After applying the policy, test the setup to confirm it is working as expected. \ No newline at end of file +- If your MinIO server is hosted on a different machine or address, replace `plane-plane-minio:9000` with the appropriate server URL. +- After applying the policy, test the setup to confirm it is working as expected. diff --git a/docs/self-hosting/upgrade-from-community.md b/docs/self-hosting/upgrade-from-community.md index 450c573..7c23292 100644 --- a/docs/self-hosting/upgrade-from-community.md +++ b/docs/self-hosting/upgrade-from-community.md @@ -83,29 +83,31 @@ This upgrade path is for installations using external or managed database and ob 1. Open the `plane.env` file located at `/opt/plane/plane.env`. 2. Configure database connection. - 1. Find the `DATABASE_URL` environment variable. - 2. Verify it points to your external database: - - ```ini - DATABASE_URL=postgresql://user:password@your-db-host:5432/plane - ``` - - If you need to change it, update the value with your managed database connection string. - - 3. Configure object storage 1. Find the `#DATASTORE SETTINGS` section in `plane.env` 2. Update these environment variables for your external storage: - - ```env - USE_MINIO=0 - AWS_REGION=us-east-1 - AWS_ACCESS_KEY_ID= - AWS_SECRET_ACCESS_KEY= - AWS_S3_ENDPOINT_URL=https://s3.amazonaws.com - AWS_S3_BUCKET_NAME=plane-uploads - ``` - - :::info - Setting `USE_MINIO=0` disables the local MinIO service and enables external object storage (S3 or S3-compatible services). - ::: + 1. Find the `DATABASE_URL` environment variable. + 2. Verify it points to your external database: + + ```ini + DATABASE_URL=postgresql://user:password@your-db-host:5432/plane + ``` + + If you need to change it, update the value with your managed database connection string. + + 3. Configure object storage + 1. Find the `#DATASTORE SETTINGS` section in `plane.env` + 2. Update these environment variables for your external storage: + + ```ini + USE_MINIO=0 + AWS_REGION=us-east-1 + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_S3_ENDPOINT_URL=https://s3.amazonaws.com + AWS_S3_BUCKET_NAME=plane-uploads + ``` + + :::info + Setting `USE_MINIO=0` disables the local MinIO service and enables external object storage (S3 or S3-compatible services). + ::: 3. Restart Plane services to apply the configuration: ```bash diff --git a/package.json b/package.json index 8968156..985daed 100644 --- a/package.json +++ b/package.json @@ -32,5 +32,5 @@ "dependencies": { "lucide-vue-next": "^0.562.0" }, - "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264" + "packageManager": "pnpm@10.30.2+sha512.36cdc707e7b7940a988c9c1ecf88d084f8514b5c3f085f53a2e244c2921d3b2545bc20dd4ebe1fc245feec463bb298aecea7a63ed1f7680b877dc6379d8d0cb4" }