Skip to content

Commit b25ccc4

Browse files
danciaclaradanciaclara
authored
Merge pull request #83 from makeplane/env-var-reference
Environment variables reference guide
2 parents 909a455 + 3805a83 commit b25ccc4

File tree

4 files changed

+246
-3
lines changed

4 files changed

+246
-3
lines changed

‎api-reference/issue/list-issues.mdx‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,5 @@ api: GET /api/v1/workspaces/{workspace-slug}/projects/{project_id}/issues/
88

99
<ParamField path="workspace-slug" type="string" required></ParamField>
1010
<ParamField path="project_id" type="string" required></ParamField>
11-
<ParamField query="fields" type="string" required></ParamField>
12-
<ParamField query="expand" type="string" required></ParamField>
11+
<ParamField query="fields" type="string"></ParamField>
12+
<ParamField query="expand" type="string"></ParamField>

‎mint.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -103,6 +103,7 @@
103103
},
104104
"self-hosting/govern/external-secrets",
105105
"self-hosting/govern/reverse-proxy",
106+
"self-hosting/govern/environment-variables",
106107
"self-hosting/telemetry"
107108
]
108109
},

‎self-hosting/govern/environment-variables.mdx‎

Lines changed: 242 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,242 @@
1+
---
2+
title: Environment variables reference guide
3+
sidebarTitle: Environment variables
4+
---
5+
6+
This guide provides a comprehensive overview of all environment variables used in the Commercial Edition. These variables allow you to customize your Plane instance to best fit your organization's needs.
7+
8+
## Where to find the .env file
9+
10+
The environment file for Plane Commercial Edition is located at:
11+
```bash
12+
/opt/plane/plane.env
13+
```
14+
15+
This is where you'll make all configuration changes. Remember to restart the instance after making changes to ensure they take effect.
16+
17+
## Environment variables
18+
19+
### General settings
20+
21+
| Variable | Description | Default Value |
22+
|----------|-------------|---------------|
23+
| **INSTALL_DIR** | Directory where Plane is installed. | `/opt/plane` |
24+
| **DOMAIN_NAME** | Primary domain name for your Plane instance. This determines how users will access your installation. | `localhost` |
25+
| **APP_RELEASE_VERSION** | The version of Plane Commercial Edition you're running. This helps with troubleshooting and ensures compatibility. | *Current release version* |
26+
| **WEB_URL** | The complete base URL for the web application including protocol (e.g., `https://plane.example.com`).|`http://localhost`|
27+
| **CORS_ALLOWED_ORIGINS** | Comma-separated list of origins allowed to make cross-origin requests to your API. Usually, this should include your WEB_URL. |`http://localhost`|
28+
| **DEBUG** | Toggles debug mode for more verbose logging and debugging information.| `0` (disabled) |
29+
30+
### Scaling and performance
31+
32+
| Variable | Description | Default Value |
33+
|----------|-------------|---------------|
34+
| **WEB_REPLICAS** | Number of web server replicas for load balancing. | `1` |
35+
| **SPACE_REPLICAS** | Number of space service replicas for workspaces. | `1` |
36+
| **ADMIN_REPLICAS** | Number of admin service replicas. | `1` |
37+
| **API_REPLICAS** | Number of API service replicas. | `1` |
38+
| **WORKER_REPLICAS** | Number of worker service replicas for background tasks. | `1` |
39+
| **BEAT_WORKER_REPLICAS** | Number of beat worker replicas for scheduled tasks. | `1` |
40+
| **LIVE_REPLICAS** | Number of live service replicas for real-time updates. | `1` |
41+
| **GUNICORN_WORKERS** | Number of Gunicorn workers for handling web requests. Increase for better performance on high-traffic instances. | `2` |
42+
43+
### Networking and security
44+
45+
| Variable | Description | Default Value |
46+
|----------|-------------|---------------|
47+
| **LISTEN_HTTP_PORT** | Port for HTTP traffic. | `80` |
48+
| **LISTEN_HTTPS_PORT** | Port for HTTPS traffic. | `443` |
49+
| **APP_PROTOCOL** | Protocol to be used, either `http` or `https`. | `http` |
50+
| **TRUSTED_PROXIES** | CIDR notation of trusted proxies for request forwarding. Important when behind load balancers or reverse proxies. | `0.0.0.0/0` |
51+
| **SSL_VERIFY** | Whether to verify SSL certificates for outgoing connections. Set to `0` only in development environments. | `1` |
52+
53+
### SSL and certificates
54+
55+
| Variable | Description | Default Value |
56+
|----------|-------------|---------------|
57+
| **CERT_EMAIL** | Email used for SSL certificate registration with Let's Encrypt or other ACME providers. |`[email protected]`|
58+
| **CERT_ACME_CA** | ACME Certificate Authority URL for SSL certificate issuance. | `https://acme-v02.api.letsencrypt.org/directory` |
59+
| **CERT_ACME_DNS** | DNS provider configuration for SSL certificate domain validation. Format varies by provider. | |
60+
| **SITE_ADDRES** | The domain name and port required by Caddy for serving your Plane instance. This determines how Caddy will handle incoming requests. | `localhost:80` |
61+
62+
### Database settings
63+
64+
| Variable | Description | Default Value |
65+
|----------|-------------|---------------|
66+
| **PGHOST** | Hostname or IP address of your PostgreSQL server. | `plane-db` |
67+
| **PGDATABASE** | Name of the PostgreSQL database Plane will use. | `plane` |
68+
| **POSTGRES_USER** | Username for PostgreSQL authentication. | `plane` |
69+
| **POSTGRES_PASSWORD** | Password for PostgreSQL authentication. **Critical:** Use a strong, unique password here. |`plane`|
70+
| **POSTGRES_DB** | Same as PGDATABASE - the name of the PostgreSQL database. | `plane` |
71+
| **POSTGRES_PORT** | TCP port your PostgreSQL server is listening on. | `5432` |
72+
| **PGDATA** | Directory path where PostgreSQL data is stored. Only relevant if you're managing PostgreSQL within the same container/system. | `/var/lib/postgresql/data` |
73+
| **DATABASE_URL** | Full connection string for PostgreSQL. If provided, this takes precedence over individual connection parameters. Format: `postgresql://username:password@host:port/dbname` | |
74+
75+
### Redis settings
76+
77+
| Variable | Description | Default Value |
78+
|----------|-------------|---------------|
79+
| **REDIS_HOST** | Hostname or IP address of your Redis server. | `plane-redis` |
80+
| **REDIS_PORT** | TCP port your Redis server is listening on. | `6379` |
81+
| **REDIS_URL** | Full connection string for Redis.| |
82+
83+
### RabbitMQ settings
84+
85+
| Variable | Description | Default Value |
86+
|----------|-------------|---------------|
87+
| **RABBITMQ_HOST** | Hostname or IP address of your RabbitMQ server. | `plane-mq` |
88+
| **RABBITMQ_PORT** | TCP port your RabbitMQ server is listening on. | `5672` |
89+
| **RABBITMQ_DEFAULT_USER** | Username for RabbitMQ authentication. | `plane` |
90+
| **RABBITMQ_DEFAULT_PASS** | Password for RabbitMQ authentication. | `plane` |
91+
| **RABBITMQ_DEFAULT_VHOST** | Virtual host for RabbitMQ, providing logical separation of resources. | `plane` |
92+
| **AMQP_URL** | Full connection string for RabbitMQ. Format: `amqp://username:password@host:port/vhost` | |
93+
94+
### Authentication and security
95+
| Variable | Description | Default Value |
96+
|----------|-------------|---------------|
97+
| **SECRET_KEY** | Secret key used for various cryptographic operations, including JWT token signing. | |
98+
| **MACHINE_SIGNATURE** | Unique identifier for your instance, used for licensing and authentication.| |
99+
100+
### File Storage (MinIO / S3)
101+
102+
| Variable | Description | Default Value |
103+
|----------|-------------|---------------|
104+
| **USE_MINIO** | Determines whether to use MinIO for object storage. Set to `1` to enable MinIO, `0` to use configured S3 or local storage. | `1` |
105+
| **AWS_REGION** | AWS region for S3 storage services. | |
106+
| **AWS_ACCESS_KEY_ID** | Access key for MinIO or AWS S3 authentication. | |
107+
| **AWS_SECRET_ACCESS_KEY** | Secret key for MinIO or AWS S3 authentication. | |
108+
| **AWS_S3_ENDPOINT_URL** | Custom endpoint URL for MinIO or S3-compatible storage. | `http://plane-minio:9000`|
109+
| **AWS_S3_BUCKET_NAME** | S3 bucket name for file storage. | `uploads` |
110+
| **MINIO_ROOT_USER** | Username for MinIO authentication. This is effectively your MinIO admin account. | `access-key` |
111+
| **MINIO_ROOT_PASSWORD** | Password for MinIO root user authentication. Keep this secure as it provides full access to your storage. | `secret-key` |
112+
| **BUCKET_NAME** | S3 bucket name where all file uploads will be stored. This bucket will be automatically created if it doesn't exist. | `uploads` |
113+
| **FILE_SIZE_LIMIT** | Maximum file upload size in bytes. | `5242880` (5MB) |
114+
| **MINIO_ENDPOINT_SSL** | Force HTTPS for MinIO when dealing with SSL termination. Set to `1` to enable. | `0` |
115+
116+
### GitHub integration
117+
118+
| Variable | Description | Default Value |
119+
|----------|-------------|---------------|
120+
| **GITHUB_CLIENT_ID** | OAuth client ID for GitHub integration. | |
121+
| **GITHUB_CLIENT_SECRET** | OAuth client secret for GitHub integration. | |
122+
| **GITHUB_APP_NAME** | GitHub App name for enhanced GitHub integration. | |
123+
| **GITHUB_APP_ID** | GitHub App ID for enhanced GitHub integration. | |
124+
| **GITHUB_PRIVATE_KEY** | Private key for GitHub App authentication. | |
125+
126+
### Slack integration
127+
128+
| Variable | Description | Default Value |
129+
|----------|-------------|---------------|
130+
| **SLACK_CLIENT_ID** | OAuth client ID for Slack integration. | |
131+
| **SLACK_CLIENT_SECRET** | OAuth client secret for Slack integration. | |
132+
133+
### GitLab integration
134+
135+
| Variable | Description | Default Value |
136+
|----------|-------------|---------------|
137+
| **GITLAB_CLIENT_ID** | OAuth client ID for GitLab integration. | |
138+
| **GITLAB_CLIENT_SECRET** | OAuth client secret for GitLab integration. | |
139+
140+
### API settings
141+
142+
| Variable | Description | Default Value |
143+
|----------|-------------|---------------|
144+
| **API_KEY_RATE_LIMIT** | Rate limit for API requests to prevent abuse. Format: `number/timeunit` | `60/minute` |
145+
146+
147+
<Accordion title="Community Edition">
148+
149+
This guide provides a comprehensive overview of all environment variables available for configuring your self-hosted Plane Community Edition. Use these variables to customize your instance to fit your deployment needs.
150+
151+
## Where to find the environment file
152+
153+
The environment configuration file is located at:
154+
```bash
155+
plane-selfhost/plane-app/plane.env
156+
```
157+
158+
## Environment Variables
159+
160+
### General settings
161+
162+
| Variable | Description | Default Value |
163+
|----------|-------------|---------------|
164+
| **APP_DOMAIN** | Domain name for your Plane instance. This determines how users will access your installation. | `localhost` |
165+
| **APP_RELEASE** | Release version of Plane. Helps with compatibility and troubleshooting. | `stable` |
166+
| **WEB_URL** | The complete base URL for the web application including protocol. Essential for email links and integrations. | `http://${APP_DOMAIN}` |
167+
| **CORS_ALLOWED_ORIGINS** | Comma-separated list of origins allowed to make cross-origin requests to your API. | `http://${APP_DOMAIN}` |
168+
| **DEBUG** | Toggles debug mode for verbose logging. Set to `1` to enable, `0` to disable. Not recommended in production as it may expose sensitive information. | `0` |
169+
| **NGINX_PORT** | Port for HTTP traffic. The primary port your users will connect to. | `80` |
170+
171+
### Scaling and performance
172+
173+
| Variable | Description | Default Value |
174+
|----------|-------------|---------------|
175+
| **WEB_REPLICAS** | Number of web server replicas for serving the frontend UI. Increase for better load distribution. | `1` |
176+
| **SPACE_REPLICAS** | Number of space service replicas handling workspace-related operations. | `1` |
177+
| **ADMIN_REPLICAS** | Number of admin service replicas for administrative functions. | `1` |
178+
| **API_REPLICAS** | Number of API service replicas processing API requests. | `1` |
179+
| **WORKER_REPLICAS** | Number of worker service replicas handling background tasks. | `1` |
180+
| **BEAT_WORKER_REPLICAS** | Number of beat worker replicas for scheduled/periodic tasks. | `1` |
181+
| **LIVE_REPLICAS** | Number of live service replicas for real-time updates and WebSocket connections. | `1` |
182+
| **GUNICORN_WORKERS** | Number of Gunicorn workers per API instance. Increase for better request handling capacity. | `1` |
183+
184+
### API settings
185+
186+
| Variable | Description | Default Value |
187+
|----------|-------------|---------------|
188+
| **API_KEY_RATE_LIMIT** | Rate limit for API requests to prevent abuse. Format: `number/timeunit` | `60/minute` |
189+
190+
### Database settings
191+
192+
| Variable | Description | Default Value |
193+
|----------|-------------|---------------|
194+
| **PGHOST** | Hostname or IP address of your PostgreSQL server. | `plane-db` |
195+
| **PGDATABASE** | Name of the PostgreSQL database Plane will use. | `plane` |
196+
| **POSTGRES_USER** | Username for PostgreSQL authentication. | `plane` |
197+
| **POSTGRES_PASSWORD** | Password for PostgreSQL authentication. Use a strong, unique password. | `plane` |
198+
| **POSTGRES_DB** | Same as PGDATABASE - the name of the PostgreSQL database. | `plane` |
199+
| **POSTGRES_PORT** | TCP port your PostgreSQL server is listening on. | `5432` |
200+
| **PGDATA** | Directory path where PostgreSQL data is stored. Only relevant if you're managing PostgreSQL directly. | `/var/lib/postgresql/data` |
201+
| **DATABASE_URL** | Full connection string for PostgreSQL. If provided, overrides individual settings. Format: `postgresql://username:password@host:port/dbname` | |
202+
203+
### Redis settings
204+
205+
| Variable | Description | Default Value |
206+
|----------|-------------|---------------|
207+
| **REDIS_HOST** | Hostname or IP address of your Redis server. | `plane-redis` |
208+
| **REDIS_PORT** | TCP port your Redis server is listening on. | `6379` |
209+
| **REDIS_URL** | Full connection string for Redis. Format: `redis://username:password@host:port` | |
210+
211+
### RabbitMQ settings
212+
213+
| Variable | Description | Default Value |
214+
|----------|-------------|---------------|
215+
| **RABBITMQ_HOST** | Hostname or IP address of your RabbitMQ server. | `plane-mq` |
216+
| **RABBITMQ_PORT** | TCP port your RabbitMQ server is listening on. | `5672` |
217+
| **RABBITMQ_USER** | Username for RabbitMQ authentication. | `plane` |
218+
| **RABBITMQ_PASSWORD** | Password for RabbitMQ authentication. Use a strong, unique password. | `plane` |
219+
| **RABBITMQ_VHOST** | Virtual host for RabbitMQ, providing logical separation of resources. | `plane` |
220+
| **AMQP_URL** | Full connection string for RabbitMQ. If not provided, it's constructed from individual settings. | `amqp://plane:plane@plane-mq:5672/plane` |
221+
222+
### File Storage (MinIO / S3)
223+
224+
| Variable | Description | Default Value |
225+
|----------|-------------|---------------|
226+
| **USE_MINIO** | Whether to use MinIO for object storage. Set to `1` to enable, `0` to use other configured storage. | `1` |
227+
| **MINIO_ENDPOINT_SSL** | Force HTTPS for MinIO when handling SSL termination. Set to `1` to enable. | `0` |
228+
| **AWS_REGION** | AWS region for S3 storage services. Applies when using S3 or MinIO. | |
229+
| **AWS_ACCESS_KEY_ID** | Access key for MinIO or AWS S3 authentication. | `access-key` |
230+
| **AWS_SECRET_ACCESS_KEY** | Secret key for MinIO or AWS S3 authentication. | `secret-key` |
231+
| **AWS_S3_ENDPOINT_URL** | Endpoint URL for MinIO or S3-compatible storage. | |
232+
| **AWS_S3_BUCKET_NAME** | S3 bucket name for file storage. All uploads will be stored in this bucket. | `uploads` |
233+
| **FILE_SIZE_LIMIT** | Maximum file upload size in bytes. | `5242880` (5MB) |
234+
235+
236+
### Security settings
237+
238+
| Variable | Description | Default Value |
239+
|----------|-------------|---------------|
240+
| **SECRET_KEY** | Secret key used for cryptographic operations like session handling and token generation. Should be a long, random string. | |
241+
242+
</Accordion>

‎self-hosting/govern/external-secrets.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ This guide explains how to integrate Plane with external secret management solut
99

1010
1. Create a dedicated IAM user (e.g., `external-secret-access-user`). You can uncheck **Console Access Required**.
1111
2. Generate `ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` and keep them handy.
12-
3. Note the user's ARN for later use (format: `arn:aws:iam::&lt;account-id&gt;:user/&lt;user-name&gt;`).
12+
3. Note the user's ARN for later use (format: `arn:aws:iam::<account-id>:user/<user-name>`).
1313

1414
4. Create IAM policy (e.g., `external-secret-access-policy`) with the following JSON:
1515

0 commit comments

Comments
 (0)