Skip to content

Commit a4e8a87

Browse files
danciaclaradanciaclara
committed
Minor updates
2 parents 7e4947b + 39efa50 commit a4e8a87

File tree

8 files changed

+336
-30
lines changed

8 files changed

+336
-30
lines changed

‎api-reference/inbox-issue/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: Overview
88
We are deprecating all `/api/v1/.../inbox-issues/` endpoints in favor of `/api/v1/.../intake-issues/`.
99

1010
**End of support**
11-
28th February 2025
11+
31st March 2025
1212

1313
**What you need to do**
1414
To ensure uninterrupted service, replace all `/inbox-issues/` references with `/intake-issues/` in your codebase before the support end date.

‎api-reference/intake-issue/overview.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ title: Overview
88
We are deprecating all `/api/v1/.../inbox-issues/` endpoints in favor of `/api/v1/.../intake-issues/`.
99

1010
**End of support**
11-
28th February 2025
11+
31st March 2025
1212

1313
**What you need to do**
1414
To ensure uninterrupted service, replace all `/inbox-issues/` references with `/intake-issues/` in your codebase before the support end date.

‎mint.json‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -69,6 +69,7 @@
6969
"pages": [
7070
"self-hosting/methods/docker-compose",
7171
"self-hosting/methods/kubernetes",
72+
"self-hosting/methods/docker-swarm",
7273
"self-hosting/methods/portainer"
7374
]
7475
},
@@ -99,6 +100,7 @@
99100
"self-hosting/govern/integrations/gitlab"
100101
]
101102
},
103+
"self-hosting/govern/external-secrets",
102104
"self-hosting/govern/reverse-proxy",
103105
"self-hosting/telemetry"
104106
]

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

Lines changed: 193 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,193 @@
1+
---
2+
title: Configure external secrets for Kubernetes deployments
3+
sidebarTitle: External secrets
4+
---
5+
6+
This guide explains how to integrate Plane with external secret management solutions, enabling secure and centralized management of sensitive configuration data. The examples provided cover AWS Secrets Manager and HashiCorp Vault integrations, but you can adapt these patterns to your preferred secret management solution.
7+
8+
## AWS Secrets Manager
9+
10+
1. Create a dedicated IAM user (e.g., `external-secret-access-user`). You can uncheck **Console Access Required**.
11+
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::<account-id>:user/<user-name>`).
13+
14+
4. Create IAM policy (e.g., `external-secret-access-policy`) with the following JSON:
15+
16+
```json
17+
{
18+
"Version": "2012-10-17",
19+
"Statement": [
20+
{
21+
"Effect": "Allow",
22+
"Action": [
23+
"secretsmanager:GetResourcePolicy",
24+
"secretsmanager:GetSecretValue",
25+
"secretsmanager:DescribeSecret",
26+
"secretsmanager:ListSecretVersionIds"
27+
],
28+
"Resource": [
29+
"arn:aws:secretsmanager:<REGION>:<ACCOUNT-ID>:secret:*"
30+
]
31+
}
32+
]
33+
}
34+
```
35+
Replace `<REGION>` and `<ACCOUNT-ID>` with your AWS region and account ID.
36+
37+
5. Create IAM role (e.g., external-secret-access-role) with the following trust relationship:
38+
39+
```json
40+
{
41+
"Version": "2012-10-17",
42+
"Statement": [
43+
{
44+
"Effect": "Allow",
45+
"Principal": {
46+
"AWS": "<IAM-USER-ARN>"
47+
},
48+
"Action": "sts:AssumeRole"
49+
}
50+
]
51+
}
52+
```
53+
54+
Replace `<IAM-USER-ARN>` with the ARN of the user created in step 1.
55+
56+
6. Attach the AWS IAM policy created in step 4 to the IAM role.
57+
58+
7. Create secrets in AWS Secrets Manager with your Plane configuration values. For example, store RabbitMQ credentials with a name like `prod/secrets/rabbitmq`.
59+
60+
|Key|Value|
61+
|-------|--------|
62+
|RABBITMQ_DEFAULT_USER|plane|
63+
|RABBITMQ_DEFAULT_PASS|plane123|
64+
65+
Follow this pattern to manage all the [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in AWS Secrets Manager.
66+
67+
8. Create a Kubernetes secret containing AWS credentials in your application namespace:
68+
```sh
69+
kubectl create secret generic aws-creds-secret \
70+
--from-literal=access-key=<AWS_ACCESS_KEY_ID> \
71+
--from-literal=secret-access-key=<AWS_SECRET_ACCESS_KEY> \
72+
-n <application_namespace>
73+
```
74+
75+
9. Apply the following YAML to create a ClusterSecretStore resource:
76+
```yaml
77+
apiVersion: external-secrets.io/v1beta1
78+
kind: ClusterSecretStore
79+
metadata:
80+
name: cluster-aws-secretsmanager
81+
spec:
82+
provider:
83+
aws:
84+
service: SecretsManager
85+
role: arn:aws:iam::<ACCOUNT-ID>:role/<IAM ROLE>
86+
region: eu-west-1
87+
auth:
88+
secretRef:
89+
accessKeyIDSecretRef:
90+
name: aws-creds-secret
91+
key: access-key
92+
secretAccessKeySecretRef:
93+
name: aws-creds-secret
94+
key: secret-access-key
95+
```
96+
Replace `<ACCOUNT-ID>` and `<IAM ROLE>` with your AWS account ID and the role name created in Step 5.
97+
98+
10. Create an ExternalSecret resource to fetch secrets from AWS and create a corresponding Kubernetes secret:
99+
```yaml
100+
apiVersion: external-secrets.io/v1beta1
101+
kind: ExternalSecret
102+
metadata:
103+
name: secret
104+
namespace: <application_namespace>
105+
spec:
106+
refreshInterval: 1m
107+
secretStoreRef:
108+
name: cluster-aws-secretsmanager # ClusterSecretStore name
109+
kind: ClusterSecretStore
110+
target:
111+
name: rabbitmq-secret # Target Kubernetes secret name
112+
creationPolicy: Owner
113+
data:
114+
- secretKey: RABBITMQ_DEFAULT_USER # Specifies the key name for the secret value in the Kubernetes secret.
115+
remoteRef:
116+
key: prod/secrets/rabbitmq # Specifies the name to the secret in the AWS Secrets Manager
117+
property: RABBITMQ_DEFAULT_USER # Specifies the name of the secret property to retrieve from the AWS Secrets Manager
118+
- secretKey: RABBITMQ_DEFAULT_PASS
119+
remoteRef:
120+
key: prod/secrets/rabbitmq
121+
property: RABBITMQ_DEFAULT_PASS
122+
```
123+
124+
Make sure to set all [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in the AWS Secrets Manager, and then access them via ExternalSecret resources in your Kubernetes cluster.
125+
126+
## HashiCorp Vault
127+
128+
1. Access the Vault UI at `https://<vault-domain>/`.
129+
130+
2. Set up a KV secrets engine if not already configured.
131+
132+
3. Create a secret with your Plane configuration values (e.g., `secrets/rabbitmq_secrets`). For this example, we're setting up RabbitMQ credentials:
133+
134+
|Key|Value|
135+
|-------|--------|
136+
|RABBITMQ_DEFAULT_USER|plane|
137+
|RABBITMQ_DEFAULT_PASS|plane123|
138+
139+
Follow this pattern to manage all the other [environment variables](/self-hosting/methods/kubernetes#external-secrets-config) in the Vault.
140+
141+
4. Create a Kubernetes secret containing your Vault token in your application namespace:
142+
```sh
143+
kubectl create secret generic vault-token -n <application_namespace> --from-literal=token=<VAULT-TOKEN>
144+
```
145+
146+
5. Apply the following YAML to create a ClusterSecretStore resource:
147+
```yaml
148+
# cluster-store.yaml
149+
apiVersion: external-secrets.io/v1beta1
150+
kind: ClusterSecretStore
151+
metadata:
152+
name: vault-backend
153+
spec:
154+
provider:
155+
vault:
156+
server: "https://<vault-domain>" #the address of your vault instance
157+
path: "secrets" #path for accessing the secrets
158+
version: "v2" #Vault API version
159+
auth:
160+
tokenSecretRef:
161+
name: "vault-token" #Use a k8s secret called vault-token
162+
key: "token" #Use this key to access the vault token
163+
```
164+
165+
Replace `<vault-domain>` with your Vault server address.
166+
167+
6. Create an ExternalSecret resource to fetch secrets from Vault and create a corresponding Kubernetes secret:
168+
```yaml
169+
apiVersion: external-secrets.io/v1beta1
170+
kind: ExternalSecret
171+
metadata:
172+
name: rabbitmq-external-secrets
173+
namespace: <application_namespace> # application-namespace
174+
spec:
175+
refreshInterval: "1m"
176+
secretStoreRef:
177+
name: vault-backend # ClusterSecretStore name
178+
kind: ClusterSecretStore
179+
target:
180+
name: rabbitmq-secret # Target Kubernetes secret name
181+
creationPolicy: Owner
182+
data:
183+
- secretKey: RABBITMQ_DEFAULT_USER # Specifies the key name for the secret value stored in the Kubernetes secret.
184+
remoteRef:
185+
key: secrets/data/rabbitmq_secrets # Specifies the name to the secret in the Vault secret store.
186+
property: RABBITMQ_DEFAULT_USER # Specifies the name of the secret property to retrieve from the Vault secret store.
187+
- secretKey: RABBITMQ_DEFAULT_PASS
188+
remoteRef:
189+
key: secrets/data/rabbitmq_secrets
190+
property: RABBITMQ_DEFAULT_PASS
191+
```
192+
193+
Follow this pattern to manage all the environment variables in the Vault, then access them via ExternalSecret resources in your Kubernetes cluster.

‎self-hosting/manage/prime-cli.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ Bring up the Prime CLI with ```sudo prime-cli``` from any directory on your mach
3232

3333
- `healthcheck` is another useful utility that lets you see the status and errors, if any, of all running services
3434

35-
- `repair` fixes your Plane install for common errors automatically.
35+
- `repair` automatically diagnoses and fixes common errors in your Plane instance. This command also resets all configuration values in the plane.env file to their defaults.
3636

3737
- `update-cli` downloads and installs the latest version of Prime CLI.
3838
<Tip>

‎self-hosting/methods/docker-swarm.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
title: Docker Swarm
3+
---
4+
5+
This guide shows you the steps to deploy a self-hosted instance of the Plane Commercial Edition using Docker Swarm.
6+
7+
## Install Plane
8+
9+
### Prerequisites
10+
- Before you get started, make sure you have a Docker Swarm environment set up and ready to go.
11+
- Your setup should support either amd64 or arm64 architectures.
12+
13+
### Procedure
14+
15+
1. **Download the required depoyment files**
16+
- `docker-compose.yml` – Defines Plane's services and dependencies.
17+
```bash
18+
curl -fsSL https://prime.plane.so/releases/<plane-version>/docker-compose.yml -o docker-compose.yml
19+
```
20+
- `variables.env` – Stores environment variables for your deployment.
21+
```bash
22+
curl -fsSL https://prime.plane.so/releases/<plane-version>/variables.env -o plane.env
23+
```
24+
<Warning>
25+
The `<plane-version>` value should be v1.8.2 or higher.
26+
</Warning>
27+
28+
2. **Configure environment variables**
29+
Before deploying, edit the `variables.env` file in your preferred text editor and update the following values:
30+
31+
- `DOMAIN_NAME` – (required) Your application's domain name.
32+
- `SITE_ADDRESS` – (required) The full domain name (FQDN) of your instance.
33+
- `MACHINE_SIGNATURE` – (required) A unique identifier for your machine. You can generate this by running below code in terminal:
34+
```sh
35+
sed -i 's/MACHINE_SIGNATURE=.*/MACHINE_SIGNATURE='$(openssl rand -hex 16)'/' plane.env
36+
```
37+
- `CERT_EMAIL` – (optional) Email address for SSL certificate generation (only needed if you're setting up HTTPS).
38+
39+
3. **Configure external DB, Redis, and RabbitMQ**
40+
<Warning>
41+
When self-hosting Plane for production use, it is strongly recommended to configure external database and storage. This ensures that your data remains secure and accessible even if the local machine crashes or encounters hardware issues. Relying solely on local storage for these components increases the risk of data loss and service disruption.
42+
</Warning>
43+
- `DATABASE_URL` – Connection string for your external database.
44+
- `REDIS_URL` – Connection string for your external Redis instance.
45+
- `AMQP_URL` – Connection string for your external RabbitMQ server.
46+
47+
48+
3. **Load the environment variables**
49+
```bash
50+
set -o allexport; source <path-to variables.env>; set +o allexport;
51+
```
52+
53+
4. **Deploy the stack**
54+
```bash
55+
docker stack deploy -c <path-to docker-compose.yml> plane
56+
```
57+
58+
That's it! This will deploy Plane as a Swarm stack, and your instance should be accessible on your configured domain.

0 commit comments

Comments
 (0)