From 49277297ca4fbb55f8835fc2ace490f9f7c2c61e Mon Sep 17 00:00:00 2001
From: Dancia <claradancia20@gmail.com>
Date: Tue, 29 Oct 2024 22:54:05 +0530
Subject: [PATCH] Review fixes on private bucket storage (#33)
---
self-hosting/govern/private-bucket.mdx | 68 ++++++++++++++------------
1 file changed, 37 insertions(+), 31 deletions(-)
diff --git a/self-hosting/govern/private-bucket.mdx b/self-hosting/govern/private-bucket.mdx
index ed78609..3a002c5 100644
--- a/self-hosting/govern/private-bucket.mdx
+++ b/self-hosting/govern/private-bucket.mdx
@@ -1,38 +1,41 @@
---
-title: Migrate from public to private bucket
-sidebarTitle: Migrate to private bucket
+title: Switch from public to private buckets
+sidebarTitle: Private storage buckets
---
<Warning>
Starting with v1.4.0 of the Commercial edition Plane will use private storage buckets for any file uploaded to your Plane instance.
</Warning>
-We highly recommend that you migrate to private bucket storage which ensures greater security and gives you more control over how files are accessed.
+<Note>
+New installations with default storage, which is MiniO, don't need to change anything. For S3 or S3-compatible storage, please see [this](https://developers.plane.so/self-hosting/govern/database-and-storage).
+</Note>
-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.
+While you can use the current public storage paradigm that Plane has followed so far, we highly recommend you migrate to private storage buckets which ensure greater security and give you more control over how files are accessed.
+
+<Note>
+To keep public storage on external S3 compatible services, you still have to update your CORS policy.
+</Note>
+
+See the instructions to switch to private storage by the provider you use below.
## For default MinIO storage
-If you prefer to keep using the public bucket, no configuration changes are needed.
+Simply run the command ↓.
-To migrate from public to private storage, simply run the migration script using this command:
```bash
docker exec -it <api_container> python manage.py update_bucket
```
-This process updates your bucket while keeping any public objects you already have accessible.
-
-## For external storage (S3 compatible)
+A successful run keeps any public files you already have accessible while moving you to private storage.
-Here’s how you can make the switch or adjust your current setup:
+## For external storage • S3 or S3 compatible
-- 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.
-
-- 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.
+There are two parts to this—updating your CORS policy and then switching to private storage.
### Update bucket's CORS policy
<Warning>
-This update is critical if you are using external storage to ensure continued functionality.
+This step is critical if you are using external storage to ensure continued functionality.
</Warning>
Here’s a sample CORS policy for your reference. Just replace `<YOUR_DOMAIN>` with your actual domain and apply the policy to your bucket.
@@ -64,37 +67,33 @@ Here’s a sample CORS policy for your reference. Just replace `<YOUR_DOMAIN>` w
```
### Switch to private storage
-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.
+
+<Warning>
+Don't start from here if you haven't updated your CORS policy.
+</Warning>
To migrate from public to private bucket storage, follow the instructions below:
-1. Ensure you have the following permissions on your S3 bucket before running the script.
+1. First, make sure you have the following permissions on your S3 bucket. If you don't, make changes to get those permissions on your bucket first.
- **s3:GetObject**
- To access existing objects publicly.
+ So you can access your public files so far To access existing objects publicly
- **s3:ListBucket**
- To list and create a policy for public access.
+ So you can apply policies to your bucket for public access
- **s3:PutObject**
- To create new objects.
+ So you can create new files
- **s3:PutBucketPolicy**
- To update the bucket policy
+ So you can update your buckets' policy
-2. Once permissions are provided, run this script to update the bucket:
+2. Now, run the command ↓.
```bash
docker exec -it <api_container> python manage.py update_bucket
```
- <Note>
- 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.
-
- To copy the `permissions.json` file to the local machine, run this command:
-
- ```bash
- docker cp <api_container>:/code/permissions.json .
- ```
+ <Tip>
+ 1. If the command finds the necessary permissions missing, it will generate a `permissions.json` file which you can use to update your bucket policy manually. Here’s how the `permissions.json` file should look.
- Here’s a sample `permission.json` file for reference:
```bash
{
"Version": "2012-10-17",
@@ -111,4 +110,11 @@ To migrate from public to private bucket storage, follow the instructions below:
]
}
```
- </Note>
\ No newline at end of file
+
+ 2. To copy the `permissions.json` file to the local machine, run the command ↓.
+
+ ```bash
+ docker cp <api_container>:/code/permissions.json .
+ ```
+
+ </Tip>
\ No newline at end of file