Skip to content

Commit 83e3baf

Browse files
danciaclaradanciaclara
authored
Private bucket storage (#26)
* Migrate to private bucket * minor edits * changed version no
1 parent 5977486 commit 83e3baf

File tree

3 files changed

+157
-6
lines changed

3 files changed

+157
-6
lines changed

‎mint.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,7 @@
8787
"self-hosting/govern/communication",
8888
"self-hosting/govern/custom-domain",
8989
"self-hosting/govern/reset-password",
90+
"self-hosting/govern/private-bucket",
9091
"self-hosting/telemetry"
9192
]
9293
},

‎self-hosting/govern/database-and-storage.mdx‎

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -32,12 +32,48 @@ The Prime CLI enables you to configure the Commercial edition instance, allowing
3232
Specify the URL of your external Redis instance to override the default Redis configuration.
3333
*Default*: `Redis 7.2.4`
3434

35-
- `External storage`
36-
Switch to your own storage by entering your AWS S3 credentials. Use the following format:
37-
- AWS Access Key ID
38-
- AWS Secret Access Key
39-
- AWS S3 Bucket Name
35+
- `External storage`
36+
Plane currently supports only S3 compatible storages.
37+
*Default*: `MinIO`
38+
39+
1. Ensure your IAM user has the following permissions on your S3 bucket.
40+
- **s3:GetObject**
41+
To access the objects.
42+
- **s3:PutObject**
43+
To upload new assets using the presigned url.
44+
2. Configure the CORS policy on your bucket to enable presigned uploads. Use the example policy below, making sure to replace `<YOUR_DOMAIN>` with your actual domain.
45+
```
46+
[
47+
{
48+
"AllowedHeaders": [
49+
"*"
50+
],
51+
"AllowedMethods": [
52+
"GET",
53+
"POST",
54+
"PUT",
55+
"DELETE",
56+
"HEAD"
57+
],
58+
"AllowedOrigins": [
59+
"<YOUR_DOMAIN>",
60+
],
61+
"ExposeHeaders": [
62+
"ETag",
63+
"x-amz-server-side-encryption",
64+
"x-amz-request-id",
65+
"x-amz-id-2"
66+
],
67+
"MaxAgeSeconds": 3000
68+
}
69+
]
70+
```
71+
3. Switch to your external storage by providing the following values:
72+
- S3 access key ID 
73+
- S3 secret access key
74+
- S3 bucket name
75+
- S3 region 
76+
- S3 endpoint URL
4077

41-
*Default*: `MinIO`
4278
3. After confirming your choices, your instance will automatically restart with the updated configuration.
4379

‎self-hosting/govern/private-bucket.mdx‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
---
2+
title: Migrate from public to private bucket
3+
sidebarTitle: Migrate to private bucket
4+
---
5+
6+
<Warning>
7+
Starting with v1.4.0 of the Commercial edition Plane will use private storage buckets for any file uploaded to your Plane instance.
8+
</Warning>
9+
10+
We highly recommend that you migrate to private bucket storage which ensures greater security and gives you more control over how files are accessed.
11+
12+
You can continue using the public bucket or switch to private bucket storage. Follow the instructions below based on whether you're using the default MinIO or an external S3-compatible storage.
13+
14+
## For default MinIO storage
15+
16+
If you prefer to keep using the public bucket, no configuration changes are needed.
17+
18+
To migrate from public to private storage, simply run the migration script using this command:
19+
```bash
20+
docker exec -it <api_container> python manage.py update_bucket
21+
```
22+
This process updates your bucket while keeping any public objects you already have accessible.
23+
24+
## For external storage (S3 compatible)
25+
26+
Here’s how you can make the switch or adjust your current setup:
27+
28+
- If you'd prefer to continue using the public bucket, that's fine—but you'll need to update your bucket’s CORS policy to include your hosted origin. This ensures that the new pre-signed uploads work correctly. See the [Update bucket's CORS policy](#update-buckets-cors-policy) section below.
29+
30+
- To migrate from public to private bucket storage, you must update your bucket's CORS policy and follow the instructions in the [Switch to private storage](#switch-to-private-storage) section below.
31+
32+
### Update bucket's CORS policy
33+
34+
<Warning>
35+
This update is critical if you are using external storage to ensure continued functionality.
36+
</Warning>
37+
38+
Here’s a sample CORS policy for your reference. Just replace `<YOUR_DOMAIN>` with your actual domain and apply the policy to your bucket.
39+
```bash
40+
[
41+
{
42+
"AllowedHeaders": [
43+
"*"
44+
],
45+
"AllowedMethods": [
46+
"GET",
47+
"POST",
48+
"PUT",
49+
"DELETE",
50+
"HEAD"
51+
],
52+
"AllowedOrigins": [
53+
"<YOUR_DOMAIN>",
54+
],
55+
"ExposeHeaders": [
56+
"ETag",
57+
"x-amz-server-side-encryption",
58+
"x-amz-request-id",
59+
"x-amz-id-2"
60+
],
61+
"MaxAgeSeconds": 3000
62+
}
63+
]
64+
```
65+
66+
### Switch to private storage
67+
Before migrating to a private bucket, make sure your CORS policy is up to date. If you haven’t done so already, see the [Update bucket's CORS policy](#update-buckets-cors-policy) section above.
68+
69+
To migrate from public to private bucket storage, follow the instructions below:
70+
71+
1. Ensure you have the following permissions on your S3 bucket before running the script.
72+
- **s3:GetObject**
73+
To access existing objects publicly.
74+
75+
- **s3:ListBucket**
76+
To list and create a policy for public access.
77+
78+
- **s3:PutObject**
79+
To create new objects.
80+
81+
- **s3:PutBucketPolicy**
82+
To update the bucket policy
83+
84+
2. Once permissions are provided, run this script to update the bucket:
85+
```bash
86+
docker exec -it <api_container> python manage.py update_bucket
87+
```
88+
<Note>
89+
If the required permissions are missing, the script will generate a `permissions.json` file, which you can copy and use to update your bucket policy manually.
90+
91+
To copy the `permissions.json` file to the local machine, run this command:
92+
93+
```bash
94+
docker cp <api_container>:/code/permissions.json .
95+
```
96+
97+
Here’s a sample `permission.json` file for reference:
98+
```bash
99+
{
100+
"Version": "2012-10-17",
101+
"Statement": [
102+
{
103+
"Effect": "Allow",
104+
"Principal": "*",
105+
"Action": "s3:GetObject",
106+
"Resource": [
107+
"arn:aws:s3:::<bucket_name>/<object_1>",
108+
"arn:aws:s3:::<bucket_name>/<object_2>"
109+
]
110+
}
111+
]
112+
}
113+
```
114+
</Note>

0 commit comments

Comments
 (0)