Plane

https://github.com/makeplane/plane
Admin
Plane is an open-source project management tool for tracking issues, managing sprints, and...
Tokens:292,376
Snippets:2,104
Trust Score:9.1
License:AGPL-3.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Docker Compose setup menu - Install

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

Interactive menu for Docker Compose setup. For first-time setup, type '1' to install, which creates the plane-app folder with docker-compose.yaml and plane.env.

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

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

### Docker Compose start services menu

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

Interactive menu for Docker Compose. Select '2' to start the services after installation.

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

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

### Start Plane instance with setup.sh

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

Starts the Plane instance after restoring data. Run this after the restore completes successfully.

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

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

### Start web apps with pnpm dev

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

Starts the web applications in development mode. This is the fourth step in the local setup process.

```bash
pnpm dev
```

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

### Run setup.sh

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

Runs the setup script to configure the project environment. This is the second step in the local setup process.

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

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

### Start Docker containers with docker-compose-local.yml

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

Starts the required Docker containers using the local Docker Compose configuration. This is the third step in the local setup process.

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

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

### Clone the Plane repository and prepare setup script

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

Clones the Plane repository into a folder of your choice, changes into that directory, and makes the setup script executable. This is the first step in setting up the project locally.

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

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

### Download setup.sh for Docker Compose

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

Downloads the setup script for Docker Compose and makes it executable.

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

chmod +x setup.sh
```

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

### Backup Data output example

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

Example output after selecting Backup Data. Shows the backup process for the three volumes and the location of the backup files.

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

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

### Example output of restore.sh

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

Example output from running ./restore.sh with the backup folder /opt/plane-selfhost/plane-app/backup/20240722-0914. Shows the Plane banner and successful restoration of the pgdata, redisdata, and uploads 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.
```

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

### Docker Swarm setup menu - Deploy Stack

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

Interactive menu for Docker Swarm setup. For first-time setup, type '1' to deploy the stack, which creates the plane-app folder with docker-compose.yaml and plane.env.

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

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

### Docker run with IP address example

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

Starts the Plane AIO container using an IP address for the domain and external services. Includes optional AWS_S3_ENDPOINT_URL and FILE_SIZE_LIMIT environment variables.

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

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

### API service log output example

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

Example output when viewing logs for the API service. Shows startup sequence including database checks, environment variable loading, bucket creation, and gunicorn startup. Exit with CTRL+C to return to the main menu.

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

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

### Layer-to-surface association examples (bg-layer-1, bg-layer-2, bg-layer-3)

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

Shows correct and incorrect layer usage for surfaces. Correct examples pair bg-surface-1 with bg-layer-1 and bg-surface-2 with bg-layer-2. The wrong example uses bg-layer-2 on a bg-surface-1 content box. The final example demonstrates the rare exception where an input inside a modal (bg-surface-1) uses bg-layer-2 for visual separation.

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

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

### Restart services with setup.sh (Docker Compose)

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

Shows the setup.sh menu for Docker Compose and the selection of option 4 to restart services. The prompt displays the default action as 2 (Start) and the user enters 4.

```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]: 4
```

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

### GET /api/users

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

Example of a GET endpoint defined with the @Get decorator in a REST controller.

```APIDOC
## [GET] /api/users

### Description
Retrieves a list of users.

### Method
GET

### Endpoint
/api/users

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **users** (array) - List of users

#### Response Example
{
  "users": []
}
```

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

### Installation: Add @plane/decorators to dependencies

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

Adds the @plane/decorators package to your project's dependencies using a workspace protocol. This is the required setup to use the library.

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

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

### Verify Docker Installation

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

Run this command in a terminal to check the installed Docker version.

```bash
docker --version
```

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

### Download swarm.sh for Docker Swarm

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

Downloads the setup script for Docker Swarm and makes it executable.

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

chmod +x setup.sh
```

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

### Install Docker Engine on Cloud Server

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

Run this command on an AWS EC2 instance with at least 2 vCPU and 4GB RAM to install Docker Engine.

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

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

### Upgrade Plane version with setup.sh (Docker Compose)

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

Shows the setup.sh menu for Docker Compose and the selection of option 5 to upgrade the release. The prompt displays the default action as 2 (Start) and the user enters 5. Choosing this stops services and downloads the latest docker-compose.yaml and plane.env.

```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]: 5
```

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

### Install test requirements in fresh environment

Source: https://github.com/makeplane/plane/blob/preview/apps/api/docs/django-5.2-migration-plan.md

Performs a clean install of test requirements, pulling base and test dependencies, to resolve pip conflicts.

```bash
pip install -r requirements/test.txt
```

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

### Contract Test Example for MyEndpoint

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

Example contract test for an API endpoint. Uses the @pytest.mark.contract marker and the auth_client fixture to verify a GET request returns 200 OK.

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

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

### Provide source and destination volume prefixes

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

Example of providing the source and destination volume prefixes when prompted by the migration script.

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

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

### Proper layer stacking example

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

Demonstrates proper layer stacking using bg-surface-1, bg-layer-1, bg-layer-2, and bg-layer-3 with matching hover variants.

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

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

### Hover state examples (correct and incorrect)

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

Shows correct hover states where the hover variant matches the base layer, and an incorrect example where they mismatch.

```tsx
// ✅ Correct: Matching hover
<div className="bg-layer-1 hover:bg-layer-1-hover">
  Hoverable element
</div>

<div className="bg-layer-2 hover:bg-layer-2-hover">
  Hoverable element
</div>

// ❌ Wrong: Mismatched hover
<div className="bg-layer-1 hover:bg-layer-2-hover">
  {/* Never do this */}
</div>
```

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

### Docker Compose: Select View Logs option

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

Shows the main menu options for the Docker Compose setup script. Select option 6 to view logs.

```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]: 6
```

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

### Docker Swarm: Select View Logs option

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

Shows the main menu options for the Docker Swarm setup script. Select option 6 to view logs.

```bash
   1) Deploy Stack
   2) Remove Stack
   3) View Stack Status
   4) Redeploy Stack
   5) Upgrade
   6) View Logs
   7) Exit

Action [3]: 6
```

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

### Basic Docker run command for Plane AIO

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

Starts the Plane AIO container with required environment variables for domain, database, Redis, RabbitMQ, and S3 storage. Maps port 80 to the host.

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

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

### Unit Test Example for MySerializer

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

Example unit test for a serializer. Uses the @pytest.mark.unit marker and validates input data with MySerializer.

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

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

### Smoke Test Example for Login Flow

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

Example smoke test for a critical login flow. Uses the plane_server fixture to hit a real HTTP server and verifies the response contains an access token.

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

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

### Docker Compose: Select Backup Data option

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

Shows the main menu options for the Docker Compose setup script. Select option 7 to backup data.

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

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

### Best Practice: Use preparers for complex logic

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

Keep field definitions simple and use preparers for complex transformations. Example shows a prepare_assignees method.

```python
def prepare_assignees(self, obj):
    return [f"{u.first_name} {u.last_name}" for u in obj.assignee_details]
```

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

### Custom preparer example

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

Defines a custom preparer method `prepare_assignees` for complex logic. Preparers take precedence over field definitions.

```python
class MySchema(ExportSchema):
    assignees = ListField(label="Assignees")

    def prepare_assignees(self, obj):
        return [f"{u.first_name} {u.last_name}" for u in obj.assignee_details]
```

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

### POST /api/users

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

Example of a POST endpoint defined with the @Post decorator in a REST controller.

```APIDOC
## [POST] /api/users

### Description
Creates a new user.

### Method
POST

### Endpoint
/api/users

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the operation was successful

#### Response Example
{
  "success": true
}
```

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

### Run restore.sh with backup folder path

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

Executes the restore script with the path to the backup folder containing the *.tar.gz files. For example, use /opt/plane-selfhost/plane-app/backup/20240722-0914.

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

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

### WebSocket /ws/chat

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

Example of a WebSocket endpoint defined with the @WebSocket decorator in a WebSocket controller.

```APIDOC
## [WebSocket] /ws/chat

### Description
Handles WebSocket connections for chat functionality.

### Method
WebSocket

### Endpoint
/ws/chat

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - Received message echoed back

#### Response Example
Received: {message}
```

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

### StringField example

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

Defines a string field that converts values to strings. Supports source, label, and default parameters.

```python
name = StringField(source="name", label="Name", default="N/A")
```

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

### IssueExportSchema complete example

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

Shows how to use the Exporter with IssueExportSchema to export issues in CSV format. Includes simple export, exporting specific fields, and exporting multiple projects to separate files.

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

# Simple export - just pass the queryset!
issues = Issue.objects.filter(project_id=project_id)
exporter = Exporter(format_type="csv", schema_class=IssueExportSchema)
filename, content = exporter.export("issues", issues)

# Export specific fields only
filename, content = exporter.export(
    "issues_filtered",
    issues,
    fields=["id", "name", "state_name", "assignees", "labels"]
)

# Export multiple projects to separate files
for project_id in project_ids:
    project_issues = issues.filter(project_id=project_id)
    filename, content = exporter.export(f"issues-{project_id}", project_issues)
    # Save or upload each file
```

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

### DateTimeField example

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

Defines a datetime field that formats datetime objects as %a, %d %b %Y %I:%M:%S %Z%z.

```python
created_at = DateTimeField(source="created_at", label="Created At")
```

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

### Nested translation key structure

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

Example of the nested key structure used for translations, demonstrating how to organize keys by feature and sub-key.

```json
{
  "issue": {
    "label": "Work item",
    "title": {
      "label": "Work item title"
    }
  }
}
```

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

### NumberField example

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

Defines a numeric field that handles int and float values. Supports source, label, and default parameters.

```python
count = NumberField(source="items_count", label="Count", default=0)
```

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

### Checking Available Formats

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

Retrieves the list of registered export formats using Exporter.get_available_formats(). The example shows the default formats: ['csv', 'json', 'xlsx'].

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

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

### Form with Inputs

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

Shows form structures with inputs. The first example uses bg-surface-1 for inputs, while the second shows a rare exception in a modal where inputs use bg-layer-2 for visual separation.

```tsx
// ✅ Correct: Form structure
<div className="bg-surface-1 p-6">
  <form className="bg-layer-1 rounded-md p-4 space-y-4">
    <div>
      <label className="text-primary font-medium">Name</label>
      {/* Input can use bg-surface-1 or bg-layer-2 for visual separation (rare exception) */}
      <input className="bg-surface-1 border border-subtle rounded-md px-3 py-2 text-primary" type="text" />
    </div>

    <button className="bg-layer-2 hover:bg-layer-2-hover rounded-md px-4 py-2 text-primary">Submit</button>
  </form>
</div>

// ✅ Correct: Input in modal (rare exception for visual separation)
<div className="bg-surface-1 rounded-lg p-6">
  <form>
    <label className="text-primary font-medium">Name</label>
    {/* Input uses layer-2 for visual separation from modal surface - rare exception */}
    <input className="bg-layer-2 border border-subtle rounded-md px-3 py-2 text-primary" type="text" />
  </form>
</div>
```

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

### Upgrade Plane version with setup.sh (Docker Swarm)

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

Shows the setup.sh menu for Docker Swarm and the selection of option 5 to upgrade the release. The prompt displays the default action as 3 (View Stack Status) and the user enters 5. Choosing this stops services and downloads the latest docker-compose.yaml and plane.env.

```bash
   1) Deploy Stack
   2) Remove Stack
   3) View Stack Status
   4) Redeploy Stack
   5) Upgrade
   6) View Logs
   7) Exit

Action [3]: 5
```

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

### Redeploy stack with setup.sh (Docker Swarm)

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

Shows the setup.sh menu for Docker Swarm and the selection of option 4 to redeploy the stack. The prompt displays the default action as 3 (View Stack Status) and the user enters 4.

```bash
   1) Deploy Stack
   2) Remove Stack
   3) View Stack Status
   4) Redeploy Stack
   5) Upgrade
   6) View Logs
   7) Exit

Action [3]: 4
```

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

### Border colors usage example

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

Example showing semantic border color tokens (border-subtle, border-subtle-1) applied to a container with bg-layer-1.

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

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

### Create and enter plane-selfhost directory

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

Creates and enters the directory where Plane will be downloaded and set up.

```bash
mkdir plane-selfhost

cd plane-selfhost
```

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

### Text colors usage example

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

Example showing semantic text color tokens (text-primary, text-secondary, text-tertiary, text-placeholder) applied to a container with bg-layer-1.

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

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

### Download and make restore.sh executable

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

Downloads the restore script from the latest Plane release and makes it executable. Run this in the same folder as setup.sh.

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

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

### pnpm build - Build all packages and apps

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

Builds all packages and applications in the monorepo.

```bash
pnpm build
```

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

### Basic REST Controller with @Controller, @Get, @Post

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

Defines a REST controller for /api/users with GET and POST endpoints. The controller extends BaseController and registers routes on an Express router.

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

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

### JSONField examples

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

Defines JSON fields for complex JSON-serializable objects. In CSV/XLSX, they are serialized as JSON strings; in JSON, they remain as objects. The second example shows a field without a source.

```python
metadata = JSONField(source="metadata", label="Metadata")
comments = JSONField(label="Comments")
```

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

### ListField examples

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

Defines list fields. In CSV/XLSX, lists are joined with a separator (default: ", "). In JSON, they remain as arrays. The second example shows a field without a source, to be populated by a custom preparer.

```python
tags = ListField(source="tags", label="Tags")
assignees = ListField(label="Assignees")  # Custom preparer can populate this
```

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

### Service Menu: Select API service for logs

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

Sub-menu listing services for log viewing. Selecting 3 shows logs for the API service.

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

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

### Migration script output and instructions

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

Output from running ./migrate.sh, showing assumptions about volume names and prompting for source volume prefix. It also includes commands to list docker volumes.

```bash
******************************************************************

This script is solely for the migration purpose only.
This is a 1 time migration of volume data from v0.13.2 => v0.14.x

Assumption:
1. Postgres data volume name ends with _pgdata
2. Minio data volume name ends with _uploads
3. Redis data volume name ends with _redisdata

Any changes to this script can break the migration.

Before you proceed, make sure you run the below command
to know the docker volumes

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

*******************************************************

Given below list of REDIS volumes, identify the prefix of source and destination volumes leaving "_redisdata"
---------------------
plane-app_redisdata
v0132_redisdata

Provide the Source Volume Prefix :
```

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

### Download and make restore script executable

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

Downloads the restore-airgapped.sh script from the latest release and makes it executable. Run this on the Commercial Air-Gapped server.

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

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

### Download and make migration script executable

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

Downloads the migration script for upgrading from v0.13.2 to v0.14.x and makes 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
```

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

### remove: Remove nodes from the AST

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

Removes the current node(s) from the AST. The example removes all variable declarations.

```javascript
j.find(j.VariableDeclaration).remove();
```

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

### Exporter.__init__(format_type, schema_class, options=None)

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

Initializes an Exporter instance with the specified format type, schema class, and optional format-specific options.

```APIDOC
## Exporter.__init__(format_type, schema_class, options=None)

### Description
Initializes an Exporter instance with the specified format type, schema class, and optional format-specific options.

### Parameters
- **format_type** (string) - Required - Export format ('csv', 'json', 'xlsx')
- **schema_class** (class) - Required - Schema class defining fields
- **options** (dict) - Optional - Optional dict of format-specific options

### Returns
None
```

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

### Build the AIO image

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

Builds the Plane AIO image from the community directory. Requires --release flag; optional --platform flag.

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

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

### Dotted path notation examples

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

Accesses nested attributes using dotted path notation in the source parameter.

```python
project_name = StringField(source="project.name", label="Project")
owner_email = StringField(source="created_by.email", label="Owner Email")
```

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

### Using Factory Boy Factories

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

Shows how to use Factory Boy factories to create test data: a single user, a workspace with an owner, and a batch of users.

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

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

### BooleanField example

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

Defines a boolean field that converts values to boolean. Supports source, label, and default parameters.

```python
is_active = BooleanField(source="is_active", label="Active", default=False)
```

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

### Run tests using helper script run_tests.py

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

Convenience script commands for running tests with options: all, unit (-u), contract with coverage (-c -o), and parallel (-p).

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

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

### Import Everything (Recommended for backwards compatibility)

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

Use this import style to maintain backwards compatibility with existing code that expects all OpenAPI utilities to be available from the package root. It imports asset_docs, ASSET_ID_PARAMETER, UNAUTHORIZED_RESPONSE, and other components.

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

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

### Run full test suite from apps/api

Source: https://github.com/makeplane/plane/blob/preview/apps/api/docs/django-5.2-migration-plan.md

Runs the full test suite using the project's run_tests.sh script.

```bash
cd apps/api && ./run_tests.sh
```

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

### renameTo: Rename nodes to a new name

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

Renames all nodes in the collection to a new name. The example renames identifiers named 'a' to 'x'.

```javascript
root.find(j.Identifier, { name: "a" }).renameTo("x");
```

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

### insertAfter: Insert a node after the current node

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

Inserts a node after the current node. The example inserts an expression statement after each function declaration.

```javascript
j.find(j.FunctionDeclaration).insertAfter(
  j.expressionStatement(j.stringLiteral("Inserted after"))
);
```

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

### insertBefore: Insert a node before the current node

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

Inserts a node before the current node. The example inserts an expression statement before each function declaration.

```javascript
j.find(j.FunctionDeclaration).insertBefore(
  j.expressionStatement(j.stringLiteral("Inserted before"))
);
```

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

### ExportSchema.__init__(context=None)

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

Initializes an ExportSchema instance with an optional context dict accessible in preparer methods.

```APIDOC
## ExportSchema.__init__(context=None)

### Description
Initializes an ExportSchema instance with an optional context dict accessible in preparer methods via self.context for pre-fetched data.

### Parameters
- **context** (dict) - Optional - Optional dict accessible in preparer methods via self.context for pre-fetched data

### Returns
None
```

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

### Selected state examples

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

Shows two correct ways to apply the -selected variant: conditionally with cn() and using a data attribute selector.

```tsx
// ✅ Correct: Selected state with logic
<div className={cn(
  "bg-layer-1 hover:bg-layer-1-hover",
  {
    "bg-layer-1-selected": isSelected
  }
)}>
  Selectable item
</div>

// ✅ Correct: With data attribute
<div className="bg-layer-1 hover:bg-layer-1-hover data-[selected]:bg-layer-1-selected">
  Selectable item
</div>
```

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

### Run Django deployment checks

Source: https://github.com/makeplane/plane/blob/preview/apps/api/docs/django-5.2-migration-plan.md

Runs Django's check --deploy to confirm deployment configuration is clean.

```bash
python manage.py check --deploy
```

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

### Best Practice: Set defaults for None values

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

Set appropriate defaults for fields that might be None. Example shows a NumberField with default=0.

```python
count = NumberField(source="count", default=0)
```

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

### Apply third-party migrations on scratch DB

Source: https://github.com/makeplane/plane/blob/preview/apps/api/docs/django-5.2-migration-plan.md

Applies migrations for django_celery_results and django_celery_beat on a scratch database.

```bash
python manage.py migrate
```

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

### Filtering Fields

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

Pass a fields parameter to the export() method to export only specific fields. The example exports only 'id', 'name', and 'email' fields.

```python
# Export only specific fields
exporter = Exporter(format_type="csv", schema_class=MySchema)
filename, content = exporter.export(
    "filtered_data",
    queryset,
    fields=["id", "name", "email"]
)
```

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

### DateField example

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

Defines a date field that formats date objects as %a, %d %b %Y (e.g., "Mon, 01 Jan 2024").

```python
start_date = DateField(source="start_date", label="Start Date")
```

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

### ExportSchema.get_context_data() and prepare_* methods

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

Allows schemas to pre-fetch context data to avoid N+1 queries. Override get_context_data() to provide context, and use prepare_* methods to access it during serialization.

```APIDOC
## ExportSchema.get_context_data() and prepare_* methods

### Description
Allows schemas to pre-fetch context data to avoid N+1 queries. Override get_context_data() to provide context, and use prepare_* methods to access it during serialization.

### Method
ExportSchema.get_context_data()

### Endpoint
class MySchema(ExportSchema):
    attachment_count = NumberField(label="Attachments")

    def prepare_attachment_count(self, obj):
        attachments_dict = self.context.get("attachments_dict", {})
        return len(attachments_dict.get(obj.id, []))

    @classmethod
    def get_context_data(cls, queryset):
        """Pre-fetch all attachments in one query."""
        attachments_dict = get_attachments_dict(queryset)
        return {"attachments_dict": attachments_dict}

### Parameters
#### get_context_data() Parameters
- **queryset** (QuerySet) - Required - The queryset to pre-fetch data for.

#### prepare_* Methods
- **obj** (object) - Required - The object being serialized.

### Request Example
```python
queryset = MyModel.objects.all()
exporter = Exporter(format_type="csv", schema_class=MySchema)
filename, content = exporter.export("data", queryset)
```

### Response
#### Success Response
- **context** (dict) - The context data to be used during serialization.

#### Response Example
```python
{"attachments_dict": {1: [attachment1, attachment2], ...}}
```
```

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

### Execute restore script with backup folder path

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

Runs the restore script, passing the path to the backup folder containing *.tar.gz files. Ensure Plane Commercial (Airgapped) is stopped before running.

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

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

### Best Practice: Pass QuerySets directly to Exporter

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

Let the Exporter handle serialization by passing querysets directly. Shows the recommended approach and the avoidable manual serialization.

```python
# Good - Exporter handles serialization
exporter.export("data", queryset)

# Avoid - Manual serialization unless needed
data = MySchema.serialize_queryset(queryset)
exporter.export("data", data)
```

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

### Backend tests - Subset (Docker)

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

Runs a subset of tests, e.g., unit tests, using the api-tests service.

```bash
docker compose -f docker-compose-test.yml run --rm api-tests pytest -m unit
```

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

### Backend tests - Full suite (Docker)

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

Runs the full Django/pytest suite in an isolated Docker stack defined by docker-compose-test.yml. Requires setup.sh to have been run once to generate apps/api/.env.

```bash
docker compose -f docker-compose-test.yml up --build --abort-on-container-exit --exit-code-from api-tests
```

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

### Check copyright headers in Python files

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

Runs addlicense in check-only mode to verify that all tracked Python files contain the correct copyright header for Plane Software Inc. for the year 2023. Fails if any file is missing or has an incorrect header.

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

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

### Create feature branch for Django 5.2 upgrade

Source: https://github.com/makeplane/plane/blob/preview/apps/api/docs/django-5.2-migration-plan.md

Creates a new branch off 'preview' for the Django 5.2 upgrade work item.

```bash
git checkout -b chore/<work-item-id>-django-5.2-upgrade
```

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

### Recommended persistent volume mounts

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

Mounts host directories for logs and data to persist them across container restarts.

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

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

### Initialize jscodeshift with source code

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

Creates a jscodeshift instance from source code, the entry point for all transformations.

```javascript
const j = jscodeshift(sourceCode);
```

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

### Canvas Usage: Correct and Incorrect Examples

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

Shows correct and incorrect usage of the `bg-canvas` class. Use `bg-canvas` only once at the application root (e.g., App.tsx or root layout). Pages should use `bg-surface-1` instead. Avoid using `bg-canvas` for page-level backgrounds, cards, or any nested containers.

```tsx
// ✅ Correct: Canvas at application root (only place it should be)
// App.tsx or root layout
<div className="bg-canvas min-h-screen">
  {/* All application content goes here */}
  <Routes>
    <Route path="/" element={<Page />} />
  </Routes>
</div>;

// ✅ Correct: Pages use surfaces, not canvas
function Page() {
  return <div className="bg-surface-1">{/* Page content */}</div>;
}

// ❌ Wrong: Canvas used for a page
function Page() {
  return <div className="bg-canvas">{/* Don't use canvas here */}</div>;
}

// ❌ Wrong: Canvas used for a card
<div className="bg-canvas p-4 rounded-md">{/* Card content */}</div>;
```

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

### Extending Schemas

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

Shows how to create an extended schema by inheriting from an existing schema and overriding get_context_data() to add custom pre-fetched data. The parent context is obtained via super().get_context_data().

```python
class ExtendedIssueExportSchema(IssueExportSchema):
    custom_field = JSONField(label="Custom Data")

    def prepare_custom_field(self, obj):
        # Use pre-fetched data from context
        return self.context.get("custom_data", {}).get(obj.id, {})

    @classmethod
    def get_context_data(cls, queryset):
        # Get parent context (attachments, etc.)
        context = super().get_context_data(queryset)

        # Add your custom pre-fetched data
        context["custom_data"] = fetch_custom_data(queryset)

        return context
```
Tokens:
Raw