### Run Project Setup Script

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Execute the setup script to prepare the project environment.

```bash
./setup.sh
```

--------------------------------

### Start backing services for local development

Source: https://context7.com/makeplane/plane/llms.txt

Starts the necessary backing services (Postgres, Valkey, RabbitMQ, MinIO) using Docker Compose. Ensure Docker is installed and running.

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

--------------------------------

### Download Plane Setup Script for Docker Compose

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Downloads the setup script for a Docker Compose-based installation of Plane. Make the script executable after downloading.

```bash
curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/setup.sh

chmod +x setup.sh
```

--------------------------------

### Start Development Servers

Source: https://github.com/makeplane/plane/blob/preview/AGENTS.md

Use this command to start both the web and admin development servers simultaneously.

```bash
pnpm dev
```

--------------------------------

### Install Plane using Docker Compose

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Installs Plane using the downloaded setup script with Docker Compose. This option prompts for an action, select '1' for installation.

```bash
Select an Action you want to perform:
   1) Install (x86_64)
   2) Start
   3) Stop
   4) Restart
   5) Upgrade
   6) View Logs
   7) Backup Data
   8) Exit

Action [2]: 1
```

--------------------------------

### Start Docker Containers

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Start the necessary Docker containers for local development using the provided compose file.

```bash
docker compose -f docker-compose-local.yml up
```

--------------------------------

### Start Server with Docker Compose

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Use this option to start the Plane services using Docker Compose. Ensure you have completed the installation steps first.

```bash
Select a Action you want to perform:
   1) Install (x86_64)
   2) Start
   3) Stop
   4) Restart
   5) Upgrade
   6) View Logs
   7) Backup Data
   8) Exit

Action [2]: 2
```

--------------------------------

### Download Plane Setup Script for Docker Swarm

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Downloads the setup script for a Docker Swarm-based deployment of Plane. Make the script executable after downloading.

```bash
curl -fsSL -o setup.sh https://github.com/makeplane/plane/releases/latest/download/swarm.sh

chmod +x setup.sh
```

--------------------------------

### Verify Docker Installation

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Verifies the Docker installation by displaying the installed version. Run this in your terminal after Docker Desktop setup.

```bash
docker --version
```

--------------------------------

### Start Storybook for @plane/ui

Source: https://github.com/makeplane/plane/blob/preview/AGENTS.md

This command starts the Storybook instance for the @plane/ui package on port 6006.

```bash
pnpm --filter=@plane/ui storybook
```

--------------------------------

### Example Restore Output

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

This is an example of the output you can expect when the restore script successfully processes backup files for different data volumes.

```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/uploads.tar.gz
.....Restoring plane-app_uploads
.....Successfully restored volume plane-app_uploads from uploads.tar.gz


Restore completed successfully.
```

--------------------------------

### Install Docker Engine on Cloud Server

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Installs the Docker engine on a cloud server. Ensure the instance meets minimum requirements (2vCPU, 4GB RAM).

```bash
curl -fsSL https://get.docker.com | sh -
```

--------------------------------

### Clone Plane Repository

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Clone the Plane repository and make the setup script executable.

```bash
git clone https://github.com/makeplane/plane.git [folder-name]
cd [folder-name]
chmod +x setup.sh
```

--------------------------------

### Clone and prepare Plane repository

Source: https://context7.com/makeplane/plane/llms.txt

Clones the Plane repository, makes the setup script executable, and runs it to prepare the development environment. Requires git and chmod.

```bash
git clone https://github.com/makeplane/plane.git plane
cd plane
chmod +x setup.sh
./setup.sh
```

--------------------------------

### Translation File Structure Example

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Illustrates the directory structure for organizing translation files by language.

```tree
packages/i18n/src/locales/
    ├── en/
    │   ├── core.json       # Critical translations
    │   └── translations.json
    ├── fr/
    │   └── translations.json
    └── [language]/
        └── translations.json
```

--------------------------------

### Register instance admin

Source: https://context7.com/makeplane/plane/llms.txt

Opens the instance admin registration page in the default web browser. This is typically done after starting the development environment.

```bash
open http://localhost:3001/god-mode/
```

--------------------------------

### Using Factory Boy for Test Data Setup

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/tests/TESTING_GUIDE.md

Demonstrates how to use Factory Boy to create test data, including single instances and batches of objects. Import the necessary factories before use.

```python
from plane.tests.factories import UserFactory, WorkspaceFactory

# Create a user
user = UserFactory()

# Create a workspace with a specific owner
workspace = WorkspaceFactory(owner=user)

# Create multiple objects
users = UserFactory.create_batch(5)
```

--------------------------------

### Create Plane Self-Host Directory

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Creates a directory for self-hosting Plane and navigates into it. This is the first step before downloading setup scripts.

```bash
mkdir plane-selfhost

cd plane-selfhost
```

--------------------------------

### Download and Prepare Air-Gapped Restore Script

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Use this command to download the restore script for air-gapped installations and make it executable.

```bash
curl -fsSL -o restore-airgapped.sh https://github.com/makeplane/plane/releases/latest/download/restore-airgapped.sh
chmod +x restore-airgapped.sh
```

--------------------------------

### Install @plane/decorators

Source: https://github.com/makeplane/plane/blob/preview/packages/decorators/README.md

Add the @plane/decorators package to your project's dependencies using npm or yarn.

```json
{
  "dependencies": {
    "@plane/decorators": "workspace:*"
  }
}
```

--------------------------------

### Run Plane AIO Docker Image (Basic)

Source: https://github.com/makeplane/plane/blob/preview/deployments/aio/community/README.md

Launches the Plane AIO Docker image with essential environment variables for basic setup. Ensure all required external services (PostgreSQL, Redis, RabbitMQ, S3) are accessible.

```bash
docker run --name plane-aio --rm -it \
    -p 80:80 \
    -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 \
    makeplane/plane-aio-community:latest
```

--------------------------------

### IntlMessageFormat Pluralization Example

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Demonstrates how to handle pluralization in translation strings using IntlMessageFormat.

```json
{
  "items": "{count, plural, one {Work item} other {Work items}}"
}
```

--------------------------------

### Run Plane AIO Docker Image (with IP and S3 Endpoint)

Source: https://github.com/makeplane/plane/blob/preview/deployments/aio/community/README.md

Launches the Plane AIO Docker image using a specific IP address and an S3 endpoint URL. This example demonstrates setting a custom file size limit and using local MinIO for S3 storage.

```bash
MYIP=192.168.68.169
docker run --name myaio --rm -it \
    -p 80:80 \
    -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=5MV45J9NF5TEFZWYCRAX \
    -e AWS_SECRET_ACCESS_KEY=7xMqAiAHsf2UUjMH+EwICXlyJL9TO30m8leEaDsL \
    -e AWS_S3_BUCKET_NAME=plane-app \
    -e AWS_S3_ENDPOINT_URL=http://${MYIP}:19000 \
    -e FILE_SIZE_LIMIT=10485760 \
    makeplane/plane-aio-community:latest
```

--------------------------------

### Create a Cycle (Sprint)

Source: https://context7.com/makeplane/plane/llms.txt

Creates a new cycle (sprint) for a project, optionally with start and end dates and a description. The response includes the new cycle's UUID.

```bash
curl -s -X POST \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sprint 12",
    "start_date": "2024-12-01",
    "end_date": "2024-12-14",
    "description": "Focus on authentication hardening"
  }' \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/cycles/"
```

--------------------------------

### Backup Data using Docker Compose

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Select action '7' from the setup script to backup data from docker volumes to external storage. Backup files are stored in a timestamped directory.

```bash
Select a Action you want to perform:
   1) Install (x86_64)
   2) Start
   3) Stop
   4) Restart
   5) Upgrade
   6) View Logs
   7) Backup Data
   8) Exit

Action [2]: 7
```

```bash
Backing Up plane-app_pgdata
Backing Up plane-app_redisdata
Backing Up plane-app_uploads

Backup completed successfully. Backup files are stored in /....../plane-app/backup/20240502-1120
```

--------------------------------

### Deploy Plane Stack using Docker Swarm

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Deploys the Plane stack using the downloaded setup script with Docker Swarm. This option prompts for an action, select '1' to deploy the stack.

```bash
Select an Action you want to perform:
   1) Deploy Stack
   2) Remove Stack
   3) View Stack Status
   4) Redeploy Stack
   5) Upgrade
   6) View Logs
   7) Exit

Action [3]: 1
```

--------------------------------

### Testing Exporter

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/utils/exporters/README.md

Example code demonstrating how to test the Exporter functionality, including exporting a queryset and filtering fields.

```APIDOC
```python
# Test exporting a queryset
queryset = MyModel.objects.all()
exporter = Exporter(format_type="json", schema_class=MySchema)
filename, content = exporter.export("test", queryset)
assert filename == "test.json"
assert isinstance(content, str)

# Test with field filtering
filename, content = exporter.export("test", queryset, fields=["id", "name"])
data = json.loads(content)
assert all(set(item.keys()) == {"id", "name"} for item in data)

# Test manual serialization
data = MySchema.serialize_queryset(queryset)
assert len(data) == queryset.count()
```
```

--------------------------------

### Running Pytest Commands

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/tests/TESTING_GUIDE.md

Provides examples of common pytest commands for running tests. Use the `-m` flag to filter tests by marker and `--cov` for coverage reports.

```bash
# Run all tests
python -m pytest

# Run only unit tests with coverage
python -m pytest -m unit --cov=plane
```

--------------------------------

### Missing Hover Prefix

Source: https://github.com/makeplane/plane/blob/preview/packages/tailwind-config/AGENTS.md

Shows an example where the hover state is incorrectly applied without the necessary 'hover:' prefix.

```tsx
// ❌ Wrong
<div className="bg-layer-1-hover">
  Content
</div>

// ✅ Correct
<div className="bg-layer-1 hover:bg-layer-1-hover">
  Content
</div>
```

--------------------------------

### Proper Layer Stacking Example

Source: https://github.com/makeplane/plane/blob/preview/packages/tailwind-config/AGENTS.md

Illustrates the correct hierarchy for stacking layers, ensuring elements appear in the intended order from surface outwards. Layers stack as surface → layer-1 → layer-2 → layer-3.

```tsx
// ✅ Correct: Proper layer stacking
<div className="bg-surface-1 p-4">
  {/* Layer 1: Card */}
  <div className="bg-layer-1 hover:bg-layer-1-hover rounded-md p-4">
    <h3>Card Title</h3>

    {/* Layer 2: Nested section */}
    <div className="bg-layer-2 hover:bg-layer-2-hover rounded p-2 mt-2">
      Nested content
      {/* Layer 3: Deeply nested */}
      <div className="bg-layer-3 hover:bg-layer-3-hover rounded p-1 mt-1">Deep content</div>
    </div>
  </div>
</div>
```

--------------------------------

### Manage Projects within a Workspace

Source: https://context7.com/makeplane/plane/llms.txt

Provides examples for performing CRUD operations on projects within a Plane workspace. Projects can be created, retrieved, updated, archived, unarchived, and permanently deleted.

```bash
# List all projects in a workspace (paginated)
curl -s -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/"
```

```bash
# Create a new project
curl -s -X POST \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Revamp",
    "identifier": "BKE",
    "description": "Rewrite the API layer",
    "network": 2
  }' \
  "$BASE_URL/workspaces/$WORKSPACE/projects/"
# Returns HTTP 201 with full project object including auto-generated UUID
```

```bash
# Retrieve a specific project
PROJECT_ID="550e8400-e29b-41d4-a716-446655440000"
curl -s -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/"
```

```bash
# Partially update a project (PATCH)
curl -s -X PATCH \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Backend Revamp v2", "emoji": "🚀"}' \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/"
```

```bash
# Archive a project
curl -s -X POST \
  -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/archive/"
```

```bash
# Unarchive a project
curl -s -X DELETE \
  -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/archive/"
```

```bash
# Delete a project permanently
curl -s -X DELETE \
  -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/"
# Returns HTTP 204 No Content
```

--------------------------------

### IntlMessageFormat Simple Variable Example

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Shows how to use simple variables within translation strings using IntlMessageFormat.

```json
{
  "greeting": "Hello, {name}!"
}
```

--------------------------------

### Basic Exporter Usage

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/utils/exporters/README.md

Define a schema and use the Exporter to export a queryset to CSV format. This example demonstrates setting up a custom schema for user data and performing the export.

```python
from plane.utils.exporters import Exporter, ExportSchema, StringField, NumberField

# Define a schema
class UserExportSchema(ExportSchema):
    name = StringField(source="username", label="User Name")
    email = StringField(source="email", label="Email Address")
    posts_count = NumberField(label="Total Posts")

    def prepare_posts_count(self, obj):
        return obj.posts.count()

# Export data - just pass the queryset!
users = User.objects.all()
exporter = Exporter(format_type="csv", schema_class=UserExportSchema)
filename, content = exporter.export("users_export", users)
```

--------------------------------

### Example Smoke Test for Login Flow

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/tests/TESTING_GUIDE.md

Shows a smoke test for a critical flow, such as user login, using the `plane_server` fixture to interact with a running HTTP server. Requires `create_user` and `user_data` fixtures.

```python
import pytest
import requests

@pytest.mark.smoke
class TestCriticalFlow:
    @pytest.mark.django_db
    def test_login_flow(self, plane_server, create_user, user_data):
        # Get login URL
        url = f"{plane_server.url}/api/auth/signin/"
        
        # Test login
        response = requests.post(
            url, 
            json={
                "email": user_data["email"],
                "password": user_data["password"]
            }
        )
        
        # Verify
        assert response.status_code == 200
        data = response.json()
        assert "access_token" in data
```

--------------------------------

### Example Unit Test for Serializer

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/tests/TESTING_GUIDE.md

Demonstrates how to write a unit test for a Django REST Framework serializer. Ensure the serializer is imported and use pytest markers for categorization.

```python
import pytest
from plane.api.serializers import MySerializer

@pytest.mark.unit
class TestMySerializer:
    def test_serializer_valid_data(self):
        # Create input data
        data = {"field1": "value1", "field2": 42}
        
        # Initialize the serializer
        serializer = MySerializer(data=data)
        
        # Validate
        assert serializer.is_valid()
        
        # Check validated data
        assert serializer.validated_data["field1"] == "value1"
        assert serializer.validated_data["field2"] == 42
```

--------------------------------

### Basic REST Controller with @plane/decorators

Source: https://github.com/makeplane/plane/blob/preview/packages/decorators/README.md

Define a REST controller using @Controller, @Get, and @Post decorators. Ensure to import necessary classes from '@plane/decorators' and Express.

```typescript
import { Controller, Get, Post, BaseController } from "@plane/decorators";
import { Router, Request, Response } from "express";

@Controller("/api/users")
class UserController extends BaseController {
  @Get("/")
  async getUsers(req: Request, res: Response) {
    return res.json({ users: [] });
  }

  @Post("/")
  async createUser(req: Request, res: Response) {
    return res.json({ success: true });
  }
}

// Register routes
const router = Router();
const userController = new UserController();
userController.registerRoutes(router);
```

--------------------------------

### Correct Layer-to-Surface Association Examples

Source: https://github.com/makeplane/plane/blob/preview/packages/tailwind-config/AGENTS.md

Demonstrates correct and incorrect usage of layer classes with surface classes. Use layers that match the surface level for content boxes, but exceptions exist for visual separation of interactive elements.

```tsx
// ✅ Correct: Surface-1 with layer-1
<div className="bg-surface-1 p-4">
  <div className="bg-layer-1 hover:bg-layer-1-hover rounded-md p-3">
    Card content
  </div>
</div>

// ✅ Correct: Surface-2 with layer-2
<div className="bg-surface-2 p-4">
  <div className="bg-layer-2 hover:bg-layer-2-hover rounded-md p-3">
    Card content
  </div>
</div>

// ❌ Wrong: Surface-1 with layer-2 (for content boxes)
<div className="bg-surface-1 p-4">
  <div className="bg-layer-2">
    {/* Wrong layer for this surface - use layer-1 for content boxes */}
  </div>
</div>

// ✅ Correct: Rare exception - Input in modal for visual separation
<div className="bg-surface-1 rounded-lg p-6">
  <form>
    <input className="bg-layer-2 border border-subtle rounded-md px-3 py-2" />
    {/* Input uses layer-2 for visual separation from modal surface */}
  </form>
</div>
```

--------------------------------

### Example Contract Test for API Endpoint

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/tests/TESTING_GUIDE.md

Illustrates writing a contract test for an API endpoint using Django's reverse URL lookup and DRF's status codes. Requires the `auth_client` fixture for authenticated requests.

```python
import pytest
from django.urls import reverse
from rest_framework import status

@pytest.mark.contract
class TestMyEndpoint:
    @pytest.mark.django_db
    def test_my_endpoint_get(self, auth_client):
        # Get the URL
        url = reverse("my-endpoint")
        
        # Make request
        response = auth_client.get(url)
        
        # Check response
        assert response.status_code == status.HTTP_200_OK
        assert "data" in response.data
```

--------------------------------

### Build All Packages and Apps

Source: https://github.com/makeplane/plane/blob/preview/AGENTS.md

Execute this command to build all packages and applications within the project.

```bash
pnpm build
```

--------------------------------

### Download and Prepare Restore Script

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Download the restore script using curl and make it executable. It's recommended to save it in the same directory as setup.sh.

```bash
curl -fsSL -o restore.sh https://github.com/makeplane/plane/releases/latest/download/restore.sh
chmod +x restore.sh
```

--------------------------------

### Authenticate and List Projects using API Key

Source: https://context7.com/makeplane/plane/llms.txt

Demonstrates how to authenticate with the Plane API using an X-Api-Key header and list projects in a workspace. Ensure your API token and base URL are correctly set as environment variables.

```bash
# Generate an API token in the Plane UI, then use it in every request:
export PLANE_API_KEY="your-api-token-here"
export BASE_URL="https://app.plane.so/api/v1"
export WORKSPACE="my-workspace"

# Test authentication by listing projects
curl -s \
  -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/" | python3 -m json.tool

# Expected response on success:
# {
#   "results": [...],
#   "count": 3,
#   "next_cursor": "...",
#   "prev_cursor": null
# }

# On invalid key:
# {"detail": "Authentication credentials were not provided."}  HTTP 401
```

--------------------------------

### Get Collection Length

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Provides the number of elements in the collection, similar to `.size()`. Returns a number.

```javascript
const varCount = root.find(j.VariableDeclarator).length;
```

--------------------------------

### Update Language Type Definition

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Example of adding a new language code to the TLanguage type definition.

```typescript
// packages/i18n/src/types/language.ts
export type TLanguage = "en" | "fr" | "your-lang";
```

--------------------------------

### Request Logger Middleware Setup

Source: https://github.com/makeplane/plane/blob/preview/packages/logger/README.md

Integrate the requestLogger middleware into your Express application to log incoming HTTP requests.

```typescript
const app = express();
app.use(requestLogger);
```

--------------------------------

### Semantic Border Colors Example

Source: https://github.com/makeplane/plane/blob/preview/packages/tailwind-config/AGENTS.md

Illustrates the application of semantic border colors for subtle dividers and stronger borders.

```tsx
<div className="bg-layer-1 border border-subtle rounded-md p-4">
  <div className="border-b border-subtle-1 pb-2 mb-2">Section with divider</div>
</div>
```

--------------------------------

### Download and Prepare Migration Script (v0.13.2 to v0.14.x)

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Download the migration script for upgrading from Plane v0.13.2 to v0.14.x and make it executable. This is a one-time activity.

```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
```

--------------------------------

### Get First Node in Collection

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Retrieves the first node from the current collection. Useful when only the initial match is relevant.

```javascript
const firstVariableDeclaration = j.find(j.VariableDeclaration).get();
```

--------------------------------

### Get Paths from Collection

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Retrieves the path objects for each node in the collection. Paths provide context and traversal capabilities.

```javascript
const paths = j.find(j.VariableDeclaration).paths();
```

--------------------------------

### View Service Logs

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Select a service from the menu to view its logs. Use CTRL+C to exit and return to the main menu.

```bash
Select a Service you want to view the logs for:
   1) Web
   2) Space
   3) API
   4) Worker
   5) Beat-Worker
   6) Migrator
   7) Proxy
   8) Redis
   9) Postgres
   10) Minio
   11) RabbitMQ
   0) Back to Main Menu

Service: 3
```

```bash
api-1  | Waiting for database...
api-1  | Database available!
api-1  | Waiting for database migrations to complete...
api-1  | Waiting for database migrations to complete...
api-1  | Waiting for database migrations to complete...
api-1  | Waiting for database migrations to complete...
api-1  | Waiting for database migrations to complete...
api-1  | Waiting for database migrations to complete...
api-1  | Waiting for database migrations to complete...
api-1  | No migrations Pending. Starting processes ...
api-1  | Instance registered
api-1  | ENABLE_SIGNUP loaded with value from environment variable.
api-1  | ENABLE_EMAIL_PASSWORD loaded with value from environment variable.
api-1  | ENABLE_MAGIC_LINK_LOGIN loaded with value from environment variable.
api-1  | GOOGLE_CLIENT_ID loaded with value from environment variable.
api-1  | GITHUB_CLIENT_ID loaded with value from environment variable.
api-1  | GITHUB_CLIENT_SECRET loaded with value from environment variable.
api-1  | EMAIL_HOST loaded with value from environment variable.
api-1  | EMAIL_HOST_USER loaded with value from environment variable.
api-1  | EMAIL_HOST_PASSWORD loaded with value from environment variable.
api-1  | EMAIL_PORT loaded with value from environment variable.
api-1  | EMAIL_FROM loaded with value from environment variable.
api-1  | EMAIL_USE_TLS loaded with value from environment variable.
api-1  | EMAIL_USE_SSL loaded with value from environment variable.
api-1  | OPENAI_API_KEY loaded with value from environment variable.
api-1  | GPT_ENGINE loaded with value from environment variable.
api-1  | UNSPLASH_ACCESS_KEY loaded with value from environment variable.
api-1  | Checking bucket...
api-1  | Bucket 'uploads' does not exist. Creating bucket...
api-1  | Bucket 'uploads' created successfully.
api-1  | Public read access policy set for bucket 'uploads'.
api-1  | Cache Cleared
api-1  | [2024-05-02 03:56:01 +0000] [1] [INFO] Starting gunicorn 21.2.0
api-1  | [2024-05-02 03:56:01 +0000] [1] [INFO] Listening at: http://0.0.0.0:8000 (1)
api-1  | [2024-05-02 03:56:01 +0000] [1] [INFO] Using worker: uvicorn.workers.UvicornWorker
api-1  | [2024-05-02 03:56:01 +0000] [25] [INFO] Booting worker with pid: 25
api-1  | [2024-05-02 03:56:03 +0000] [25] [INFO] Started server process [25]
api-1  | [2024-05-02 03:56:03 +0000] [25] [INFO] Waiting for application startup.
api-1  | [2024-05-02 03:56:03 +0000] [25] [INFO] ASGI 'lifespan' protocol appears unsupported.
api-1  | [2024-05-02 03:56:03 +0000] [25] [INFO] Application startup complete.
```

--------------------------------

### Get Collection Size

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Returns the total number of nodes currently in the collection. A simple count of matched elements.

```javascript
const numberOfNodes = j.find(j.VariableDeclaration).size();
```

--------------------------------

### Create a Module

Source: https://context7.com/makeplane/plane/llms.txt

Creates a new module within a project. You can specify its name, description, and status. The response includes the new module's UUID.

```bash
curl -s -X POST \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Authentication",
    "description": "All OAuth and session management work",
    "status": "in-progress"
  }' \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/modules/"
```

--------------------------------

### Create a label

Source: https://context7.com/makeplane/plane/llms.txt

Adds a new label to a project. Requires a name and color. A `409 Conflict` is returned if a label with the same name already exists.

```bash
curl -s -X POST \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "bug", "color": "#ef4444", "description": "Something is broken"}' \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/labels/"
```

--------------------------------

### Semantic Text Colors Example

Source: https://github.com/makeplane/plane/blob/preview/packages/tailwind-config/AGENTS.md

Demonstrates the usage of semantic text colors for different text elements based on their importance.

```tsx
<div className="bg-layer-1 p-4">
  <h2 className="text-primary font-semibold">Title</h2>
  <p className="text-secondary">Description text</p>
  <span className="text-tertiary text-13">Metadata</span>
  <input className="placeholder-(--text-color-placeholder)" placeholder="Enter text..." />
</div>
```

--------------------------------

### Get Available Export Formats

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/utils/exporters/README.md

Retrieve a list of all currently supported export format types by calling the `get_available_formats()` class method on the `Exporter`.

```python
formats = Exporter.get_available_formats()
# Returns: ['csv', 'json', 'xlsx']
```

--------------------------------

### List all labels in a project

Source: https://context7.com/makeplane/plane/llms.txt

Retrieves all categorisation labels defined within a specific project.

```bash
curl -s -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/labels/"
```

--------------------------------

### Get Root AST Node

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Retrieves the root Abstract Syntax Tree node of the entire source code. Typically used once at the beginning.

```javascript
const ast = root.getAST();
```

--------------------------------

### Get AST Nodes from Collection

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Extracts the raw AST nodes from the current collection. Useful when direct manipulation of node objects is needed.

```javascript
const nodes = j.find(j.VariableDeclaration).nodes();
```

--------------------------------

### Get Variable Declarators with Callback

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Retrieves variable declarators from a collection, applying a callback function to each. The callback can be used to process or filter declarators.

```javascript
const variableDeclarators = j
  .find(j.Identifier)
  .getVariableDeclarators((path) => path.value.name);
```

--------------------------------

### Execute Air-Gapped Data Restore

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Run the downloaded script to restore your Plane data on an air-gapped server. Ensure the backup folder contains *.tar.gz files.

```bash
./restore-airgapped.sh <path to backup folder containing *.tar.gz files>
```

--------------------------------

### Get Unique Node Types in Collection

Source: https://github.com/makeplane/plane/blob/preview/packages/codemods/instructions.md

Returns a set containing all unique AST node types present in the current collection. Useful for analysis.

```javascript
const types = root.find(j.VariableDeclarator).getTypes();
```

--------------------------------

### Run Tests with Helper Script

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/tests/README.md

Utilize a helper script for convenient test execution, including options for parallel runs and coverage reports.

```bash
# Run all tests
./run_tests.py

# Run only unit tests
./run_tests.py -u

# Run contract tests with coverage report
./run_tests.py -c -o

# Run tests in parallel
./run_tests.py -p
```

--------------------------------

### Exporting Issues to XLSX

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/utils/exporters/README.md

Export issue data to XLSX format, including prefetched relations. This example shows how to prepare the queryset with necessary relations and then export it.

```python
from plane.utils.exporters import Exporter, IssueExportSchema

# Get issues with prefetched relations
issues = Issue.objects.filter(project_id=project_id).prefetch_related(
    'assignee_details',
    'label_details',
    'issue_module',
    # ... other relations
)

# Export as XLSX - pass the queryset directly!
exporter = Exporter(format_type="xlsx", schema_class=IssueExportSchema)
filename, content = exporter.export("issues", issues)
```

--------------------------------

### Import Everything from OpenAPI Utilities

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/utils/openapi/README.md

Recommended for maintaining backwards compatibility with existing code. Imports common OpenAPI utilities.

```python
from plane.utils.openapi import (
    asset_docs,
    ASSET_ID_PARAMETER,
    UNAUTHORIZED_RESPONSE,
    # ... other imports
)
```

--------------------------------

### Provide Migration Volume Prefixes

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

After identifying the correct volume names, provide the source and destination volume prefixes to the migration script when prompted. The script assumes volume names end with specific suffixes like '_pgdata', '_uploads', or '_redisdata'.

```bash
Provide the Source Volume Prefix : v0132
Provide the Destination Volume Prefix : plane-app
```

--------------------------------

### Identify Docker Volumes for Migration

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Before running the migration script, use these commands to list and identify your PostgreSQL, Minio, and Redis data volumes. This helps in determining the correct prefixes for the migration.

```bash
docker volume ls -q | grep -i "_pgdata"
docker volume ls -q | grep -i "_uploads"
docker volume ls -q | grep -i "_redisdata"
```

--------------------------------

### Create a label

Source: https://context7.com/makeplane/plane/llms.txt

Creates a new label within a project. Requires a name, color, and optionally a description. Returns HTTP 201 on success or HTTP 409 if a label with the same name already exists.

```APIDOC
## POST /workspaces/$WORKSPACE/projects/$PROJECT_ID/labels/

### Description
Creates a new label within a project.

### Method
POST

### Endpoint
`/workspaces/$WORKSPACE/projects/$PROJECT_ID/labels/`

### Request Body
- **name** (string) - Required - The name of the label.
- **color** (string) - Required - The hex color code for the label (e.g., `#ef4444`).
- **description** (string) - Optional - A description for the label.

### Response
#### Success Response (201)
Label created successfully.

#### Error Response (409 Conflict)
- **error** (string) - Description of the conflict, e.g., "Label with the same name already exists in the project".
- **id** (string) - The ID of the existing label.
```

--------------------------------

### Log in to the main Plane app

Source: https://context7.com/makeplane/plane/llms.txt

Opens the main Plane application UI in the default web browser for login. Assumes the web app is running on http://localhost:3000.

```bash
open http://localhost:3000
```

--------------------------------

### Build Plane AIO Docker Image

Source: https://github.com/makeplane/plane/blob/preview/deployments/aio/community/README.md

Builds the Plane AIO Docker image from source using a provided script. Requires specifying the Plane release version and optionally a custom image name and platform.

```bash
cd deployments/aio/community
IMAGE_NAME=myplane-aio ./build.sh --release=v0.27.1 [--platform=linux/amd64]
```

--------------------------------

### Create a Work Item

Source: https://context7.com/makeplane/plane/llms.txt

Use this endpoint to create a new work item. Requires 'name', 'description_html', 'priority', and 'state'. Optional fields include 'assignees', 'labels', and 'due_date'.

```bash
curl -s -X POST \
  -H "X-Api-Key: $PLANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fix login page crash on Safari",
    "description_html": "<p>Safari 17 users see a blank page after OAuth redirect.</p>",
    "priority": "urgent",
    "state": "550e8400-0000-0000-0000-000000000001",
    "assignees": ["user-uuid-1"],
    "labels": ["label-uuid-1"],
    "due_date": "2024-12-31"
  }' \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/work-items/"
```

--------------------------------

### Get Custom Editor Class Names

Source: https://github.com/makeplane/plane/blob/preview/packages/editor/Readme.md

Use this function to generate class names for custom editor styling. It accepts options to control border behavior and apply custom class names.

```typescript
const customEditorClassNames = getEditorClassNames({
  noBorder,
  borderOnFocus,
  customClassName,
});
```

--------------------------------

### Configure Persistent Volumes for Plane AIO

Source: https://github.com/makeplane/plane/blob/preview/deployments/aio/community/README.md

Mounts local directories for logs and data to ensure persistence when using the Plane AIO Docker image. This is recommended for production environments.

```bash
-v /path/to/logs:/app/logs \
-v /path/to/data:/app/data
```

--------------------------------

### Extending with Custom Styles

Source: https://github.com/makeplane/plane/blob/preview/packages/editor/Readme.md

Demonstrates how to generate custom class names for styling the editor.

```APIDOC
## Extending with Custom Styles

### `getEditorClassNames` function

This function allows you to generate custom class names for the editor based on various styling options.

```ts
const customEditorClassNames = getEditorClassNames({
  noBorder,
  borderOnFocus,
  customClassName,
});
```

- **`noBorder`** (boolean): If true, removes the default border.
- **`borderOnFocus`** (boolean): If true, applies a border when the editor is focused.
- **`customClassName`** (string): Additional custom class names to apply.
```

--------------------------------

### Instantiate XLSX Exporter

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/utils/exporters/README.md

Initialize an `Exporter` for XLSX format. The `export` method returns binary content (bytes) suitable for Excel files.

```python
exporter = Exporter(format_type="xlsx", schema_class=MySchema)
filename, content = exporter.export("data", records)
# content is bytes
```

--------------------------------

### List Modules in a Project

Source: https://context7.com/makeplane/plane/llms.txt

Retrieves all modules defined for a specific project. Modules are used to group related work items.

```bash
curl -s -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/modules/"
```

--------------------------------

### Import New Language File

Source: https://github.com/makeplane/plane/blob/preview/CONTRIBUTING.md

Illustrates how to modify the language import logic to include a new language file.

```typescript
      private importLanguageFile(language: TLanguage): Promise<any> {
      switch (language) {
          case "your-lang":
          return import("../locales/your-lang/translations.json");
          // ...
      }
      }
```

--------------------------------

### Execute Restore Script

Source: https://github.com/makeplane/plane/blob/preview/deployments/cli/community/README.md

Run the restore script, providing the path to your backup folder containing .tar.gz files. This command restores the Plane data volumes.

```bash
./restore.sh <path to backup folder containing *.tar.gz files>
```

--------------------------------

### List intake issues for a project

Source: https://context7.com/makeplane/plane/llms.txt

Retrieve a list of intake issues for a given project. Requires WORKSPACE and PROJECT_ID variables.

```bash
curl -s -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/intake-issues/"
```

--------------------------------

### Instantiate JSON Exporter

Source: https://github.com/makeplane/plane/blob/preview/apps/api/plane/utils/exporters/README.md

Create an `Exporter` instance for JSON format, specifying the desired schema class. The `export` method will return a filename and a JSON string content.

```python
exporter = Exporter(format_type="json", schema_class=MySchema)
filename, content = exporter.export("data", records)
# content is a JSON string: '[{"field": "value"}, ...]'
```

--------------------------------

### List Cycles in a Project

Source: https://context7.com/makeplane/plane/llms.txt

Retrieves all cycles (sprints/iterations) defined for a specific project. Cycles are time-boxed periods for work.

```bash
curl -s -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/cycles/"
```

--------------------------------

### Check Python Copyright Headers

Source: https://github.com/makeplane/plane/blob/preview/COPYRIGHT_CHECK.md

Run this command from the repository root to verify that all tracked Python files contain the correct copyright header. It checks without applying changes.

```bash
addlicense --check -f COPYRIGHT.txt -ignore "**/migrations/**" $(git ls-files '*.py')
```

--------------------------------

### List all members of a project

Source: https://context7.com/makeplane/plane/llms.txt

Retrieve a list of all members within a specific project. Requires WORKSPACE and PROJECT_ID variables.

```bash
curl -s -H "X-Api-Key: $PLANE_API_KEY" \
  "$BASE_URL/workspaces/$WORKSPACE/projects/$PROJECT_ID/members/"
```

--------------------------------

### WebSocket Controller with @plane/decorators

Source: https://github.com/makeplane/plane/blob/preview/packages/decorators/README.md

Create a WebSocket controller using @Controller and @WebSocket decorators. Import necessary classes from '@plane/decorators', Express, and 'ws'.

```typescript
import { Controller, WebSocket, BaseWebSocketController } from "@plane/decorators";
import { Request } from "express";
import { WebSocket as WS } from "ws";

@Controller("/ws/chat")
class ChatController extends BaseWebSocketController {
  @WebSocket("/")
  handleConnection(ws: WS, req: Request) {
    ws.on("message", (message) => {
      ws.send(`Received: ${message}`);
    });
  }
}

// Register WebSocket routes
const router = require("express-ws")(app).router;
const chatController = new ChatController();
chatController.registerWebSocketRoutes(router);
```

--------------------------------

### Run All Checks

Source: https://github.com/makeplane/plane/blob/preview/AGENTS.md

This command runs all checks, including formatting, linting, and type checking, across the project.

```bash
pnpm check
```

--------------------------------

### Target Specific Package/App with Turbo

Source: https://github.com/makeplane/plane/blob/preview/AGENTS.md

Use this command to run a specific command on a targeted package or application using Turbo.

```bash
pnpm turbo run <command> --filter=<package>
```