Skip to content

Commit 6cc4464

Browse files
danciaclaradanciaclara
authored
Merge pull request #38 from makeplane/cli-page
Added CLI page, updated custom domain and external db and storage
2 parents cc4a2eb + c1cb236 commit 6cc4464

File tree

13 files changed

+264
-105
lines changed

13 files changed

+264
-105
lines changed

‎images/update-plane/docker-volumes.png‎

76.7 KB
Loading

‎mint.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -96,7 +96,13 @@
9696
"pages": [
9797
"self-hosting/upgrade-from-community",
9898
"self-hosting/manage/backup-restore",
99-
"self-hosting/manage/upgrade-plane",
99+
{
100+
"group": "Update Plane",
101+
"pages": [
102+
"self-hosting/manage/upgrade-plane",
103+
"self-hosting/manage/upgrade-from-0.13.2-0.14.0"
104+
]
105+
},
100106
"self-hosting/manage/view-logs",
101107
"self-hosting/manage/migrate-plane",
102108
"self-hosting/manage/prime-cli"

‎self-hosting/govern/custom-domain.mdx‎

Lines changed: 13 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
---
22
title: Custom domain
3-
description: Host your Plane instance in your custom domain. Our steps differ slightly depending on whether you are hosting on a public IP or a private/internal IP. Follow the steps listed below.
3+
sidebarTitle: Custom domain
4+
description: Host your Plane instance in your custom domain.
45
---
5-
<Info>
6-
In the Commercial Edition, you can set up a custom domain right during installation.
7-
</Info>
6+
<Note>
7+
With the Commercial Edition, you can set up a custom domain right during installation. If you ever need to change the domain later, just contact our support team for assistance until we ship out a feature that lets you handle domain changes yourself.
8+
</Note>
9+
10+
<Accordion title="Community Edition">
11+
12+
Our steps differ slightly depending on whether you are hosting on a public IP or a private/internal IP. Follow the steps listed below.
813

914
## Update configuration in .env file
1015

11-
<Note>This step is mandatory for you to host Plane on a custom domain</Note>
16+
<Warning>This step is mandatory for you to host Plane on a custom domain.</Warning>
1217

1318
Open your project's `.env` file in a text editor. This file contains configuration settings for your application. Locate the following lines:
1419

@@ -48,4 +53,6 @@ If your server is behind a firewall or router and has an internal IP address, yo
4853

4954
- Once the reverse proxy is properly configured, ensure that your firewall/router allows incoming traffic on the necessary ports to reach your server.
5055

51-
By following these steps, you will be able to access your self-hosted instance of Plane using your custom domain name, whether your server has a public IP address or is behind a firewall with an internal IP address.
56+
By following these steps, you will be able to access your self-hosted instance of Plane using your custom domain name, whether your server has a public IP address or is behind a firewall with an internal IP address.
57+
58+
</Accordion>

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

Lines changed: 47 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
title: Configure external PostgreSQL, Redis and S3 storage
2+
title: Configure external PostgreSQL, Redis and S3 storage • Commercial Edition
33
sidebarTitle: External database and storage
44
---
55

@@ -72,3 +72,49 @@ The Prime CLI lets you easily configure your Commercial Edition instance, provid
7272

7373
3. After confirming your choices, your instance will automatically restart with the updated configuration.
7474

75+
<Accordion title="Community Edition">
76+
77+
To configure external Postgres, Redis, and S3 storage for the Plane Community Edition, you’ll need to adjust several environment variables in the plane.env file. Follow this guide to set up each component using the correct values for your external services.
78+
79+
1. Open the `plane.env` file on your server where Plane is installed.
80+
81+
2. In the **DB SETTINGS** section, update the variables to connect to your external Postgres instance:
82+
```bash
83+
# DB SETTINGS
84+
PGHOST=your-external-postgres-host # Replace with the hostname or IP address of your Postgres server.
85+
PGDATABASE= # Leave blank when using external database.
86+
POSTGRES_USER=your-postgres-username # The username to access Postgres.
87+
POSTGRES_PASSWORD=your-postgres-password # Password for the Postgres user.
88+
POSTGRES_DB=your-database-name # The name of the database Plane should connect to.
89+
POSTGRES_PORT=5432 # Port where Postgres is accessible (usually 5432).
90+
PGDATA=/var/lib/postgresql/data # No need to change this for external Postgres.
91+
DATABASE_URL= # Leave this empty if you're providing values for the variables above. If you choose to use the DATABASE_URL, you can leave all the other database-related variables empty.
92+
```
93+
94+
3. In the **REDIS SETTINGS** section, update the variables to connect to your external Redis instance:
95+
```bash
96+
# REDIS SETTINGS
97+
REDIS_HOST=your-external-redis-host # Hostname or IP of the Redis server.
98+
REDIS_PORT=6379 # Port where Redis is accessible (default is 6379).
99+
REDIS_URL= # Leave this empty if you're providing values for the variables above. If you choose to use the REDIS_URL, you can leave all the other redis-related variables empty.
100+
```
101+
102+
4. In the **DATA STORE SETTINGS** section, update the variables for any S3-compatible storage:
103+
```bash
104+
# DATA STORE SETTINGS
105+
USE_MINIO=0 # Set to 0 if using an external S3, 1 if using MinIO (default).
106+
AWS_REGION=your-s3-region # For AWS, set the region, e.g., "us-west-1".
107+
AWS_ACCESS_KEY_ID=your-s3-access-key # Access key for S3.
108+
AWS_SECRET_ACCESS_KEY=your-s3-secret-key # Secret key for S3.
109+
AWS_S3_ENDPOINT_URL=https://your-s3-endpoint # URL for S3 API endpoint (e.g., "https://s3.amazonaws.com" for AWS).
110+
AWS_S3_BUCKET_NAME=your-s3-bucket-name # Name of the S3 bucket for storing Plane data.
111+
MINIO_ROOT_USER= # Leave blank when using external S3.
112+
MINIO_ROOT_PASSWORD= # Leave blank when using external S3.
113+
BUCKET_NAME= # Leave blank when using external S3.
114+
FILE_SIZE_LIMIT=5242880 # Set maximum file upload size in bytes (5MB here).
115+
```
116+
5. Save your changes to the `plane.env` file.
117+
118+
6. Restart Plane services to apply the new settings using the `setup.sh` script.
119+
120+
</Accordion>

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
---
2-
title: Switch from public to private buckets
3-
sidebarTitle: Private storage buckets
2+
title: Switch from public to private buckets • Commercial Edition
3+
sidebarTitle: Private storage buckets
44
---
55

66
<Warning>

‎self-hosting/manage/backup-restore.mdx‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@ sudo prime-cli restore
2626

2727
This command prompts the restoration process, which will overwrite the current data with the data from the most recent backup file. Ensure you have selected the correct backup before running this command, as restoring will replace your current data.
2828

29-
<Accordion title="Backup and restore on Community Edition">
29+
<Accordion title="Community Edition">
3030

3131
## Backup data
3232

‎self-hosting/manage/migrate-plane.mdx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ Before we dive in, ensure:
1212
- You have a different machine with our standard config to migrate to.
1313
- You understand the same domain will be used to host the app as the current machine.
1414

15+
<Warning>
16+
If you need to change your domain during migration, contact our support team for assistance.
17+
</Warning>
18+
1519
## Steps
1620
1. **Delink licenses**
1721
Log in to Plane on your current server. Head to each paid workspace like One or Pro and [delink the licenses](https://docs.plane.so/workspaces-and-users/upgrade-plan#delink-license-key). This will free up the licenses for activation on your new server. Ideally, you have just one paid workspace.

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

Lines changed: 62 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,18 @@
11
---
2-
title: Prime CLI
3-
sidebarTitle: Prime CLI
2+
title: Command line tools
3+
sidebarTitle: CLIs
44
---
55

6-
> **Edition**: Commercial
6+
Our command-line tool is here to make managing your Plane instance simple. You can handle installs, upgrades, and general management without needing to be a Docker expert.
77

8-
<Warning>Update your CLI with the command `sudo prime-cli update-cli` before you download any Plane updates. The latest version of the CLI ensures your Plane upgrades happen smoothly.</Warning>
9-
10-
The Prime CLI is our own command-line interface to help you install, upgrade, and manage your Commercial edition instance without being a pro at Docker.
118

9+
## Prime CLI • Commercial Edition
1210
<Note>
13-
If you are on the Community edition and want to upgrade to the Commercial edition, see [Upgrade from Community](/self-hosting/upgrade-from-community).
11+
If you are on the Community edition and want to upgrade to the Commercial edition, see [Upgrade to Commercial Edition](/self-hosting/upgrade-from-community).
1412
</Note>
1513

14+
The Prime CLI provides commands for common tasks like configuring services, monitoring health, managing backups, and upgrading your Plane instance.
15+
1616
Bring up the Prime CLI with ```sudo prime-cli``` from any directory on your machine.
1717

1818
- The three operators you will use the most are:
@@ -39,7 +39,6 @@ Bring up the Prime CLI with ```sudo prime-cli``` from any directory on your mach
3939
It is highly recommend to run this first before you download any Plane updates. The latest version of the CLI ensures your Plane upgrades happen smoothly.
4040
</Tip>
4141

42-
4342
For more advanced admins that want greater control over their instance, the list of additional commands available on Prime CLI follow.
4443
- `configure`
4544

@@ -96,7 +95,62 @@ For more advanced admins that want greater control over their instance, the list
9695
2. Typing `NO` cancels the uninstall.
9796

9897

98+
<Accordion title="Setup.sh script • Community Edition">
99+
100+
The setup script `setup.sh` provides a menu-driven interface to help you install and manage your Plane instance.
101+
102+
## Usage
103+
To run the setup.sh script, use the following command in your terminal from the directory where the script is located:
104+
105+
```bash
106+
./setup.sh
107+
```
108+
This will launch an interactive menu with options to manage various aspects of your Plane instance.
109+
110+
```bash
111+
Select a Action you want to perform:
112+
1) Install
113+
2) Start
114+
3) Stop
115+
4) Restart
116+
5) Upgrade
117+
6) View Logs
118+
7) Backup Data
119+
8) Exit
120+
```
121+
122+
## Actions
123+
124+
- **Install**
125+
Installs the Plane Community Edition on your machine. Choose this option if you are setting up Plane for the first time.
126+
127+
- **Start**
128+
Starts the Plane server and all related services.
129+
130+
- **Stop**
131+
Stops the Plane server and all services currently running on the machine.
132+
133+
- **Restart**
134+
Restarts the Plane server and all associated services.
135+
136+
- **Upgrade**
137+
Upgrades Plane to the latest available version. This will stop all services, update the necessary files, and then restart Plane with the latest configuration. See [Update Plane](/self-hosting/manage/upgrade-plane#update-plane-version-community-edition) for more info.
138+
139+
<Warning>
140+
It’s recommended to create a backup before upgrading your instance. See [Backup and restore](/self-hosting/manage/backup-restore#backup-and-restore-data-community-edition).
141+
</Warning>
142+
143+
- **View Logs**
144+
Displays real-time logs of specific Plane services. See [View logs](/self-hosting/manage/view-logs#view-container-logs-community-edition) for more info.
99145

146+
<Tip>
147+
Use **View Logs** to monitor service performance or troubleshoot issues. Press `CTRL+C` to exit the log view and return to the main menu.
148+
</Tip>
100149

150+
- **Backup Data**
151+
Creates a backup of your current Plane installation, including all data. See [Backup and restore data](/self-hosting/manage/backup-restore#backup-and-restore-data-community-edition) for more info.
101152

153+
- **Exit**
154+
Closes the setup script and returns you to the command line.
102155

156+
</Accordion>

‎self-hosting/manage/upgrade-from-0.13.2-0.14.0.mdx‎

Lines changed: 112 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
title: Mandatory checkpoint at v0.14.0 • Community Edition
3+
sidebarTitle: For versions before v0.14.0
4+
---
5+
6+
If you’re upgrading from `v0.13.2` or below, there are some additional migration steps due to significant changes in the self-hosting setup. Follow these instructions to migrate your data to the new volume structure in `v0.14.0`.
7+
8+
1. First, stop the running `v0.13-2` (or older) instance of Plane. If it's still running, you might hit a "ports not available" error, which will prevent the `v0.14-0` containers from starting up correctly.
9+
```bash
10+
docker compose down
11+
```
12+
13+
2. Create a new folder for `v0.14-0` to ensure a clean installation.
14+
15+
```bash
16+
mkdir plane-selfhost
17+
cd plane-selfhost
18+
```
19+
20+
3. Set up the environment variable for the `RELEASE` variable, then download and prepare the installation script:
21+
```bash
22+
export RELEASE=v0.14-dev
23+
curl -fsSL https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/install.sh | sed -e 's@BRANCH=${BRANCH:-master}@BRANCH='"$RELEASE"'@' -e 's@APP_RELEASE="stable"@APP_RELEASE='"$RELEASE"'@' > setup.sh
24+
chmod +x setup.sh
25+
```
26+
27+
4. Execute the script to install Plane:
28+
```bash
29+
./setup.sh install
30+
```
31+
32+
5. Start up your new v0.14-0 Plane instance:
33+
```bash
34+
./setup.sh start
35+
```
36+
37+
6. Now stop the instance to initialize the new Docker volumes:
38+
```bash
39+
./setup.sh stop
40+
```
41+
42+
7. Download the migration script:
43+
```bash
44+
curl -fsSL -o migrate.sh https://raw.githubusercontent.com/makeplane/plane/master/deploy/selfhost/migration-0.13-0.14.sh
45+
chmod +x migrate.sh
46+
```
47+
48+
8. Run the migration script:
49+
```bash
50+
./migrate.sh
51+
```
52+
53+
You’ll see the following instructions:
54+
55+
```
56+
******************************************************************
57+
58+
This script is solely for the migration purpose only.
59+
This is a 1 time migration of volume data from v0.13.2 => v0.14.x
60+
61+
Assumption:
62+
1. Postgres data volume name ends with _pgdata
63+
2. Minio data volume name ends with _uploads
64+
3. Redis data volume name ends with _redisdata
65+
66+
Any changes to this script can break the migration.
67+
68+
Before you proceed, make sure you run the below command
69+
to know the docker volumes
70+
71+
docker volume ls -q | grep -i "_pgdata"
72+
docker volume ls -q | grep -i "_uploads"
73+
docker volume ls -q | grep -i "_redisdata"
74+
75+
*******************************************************
76+
77+
Given below list of REDIS volumes, identify the prefix of source and destination volumes leaving "_redisdata"
78+
---------------------
79+
plane-app_redisdata
80+
v0132_redisdata
81+
82+
Provide the Source Volume Prefix :
83+
```
84+
85+
9. Open a second terminal and run the commands shown above to identify your source and destination volume prefixes. For example, if you run `docker volume ls -q | grep -i "_pgdata"`, you might see something like:
86+
87+
<Frame>![](/images/update-plane/docker-volumes.png)</Frame>
88+
89+
In this example, `plane-013-dev` is the prefix for `v0.13.2`, and `plane-app` is the prefix for `v0.14.0`.
90+
91+
10. Return to the original terminal, enter the source volume prefix `v0132` and destination volume prefix `plane-app`, and press ENTER:
92+
```bash
93+
Provide the Source Volume Prefix : plane-013-dev
94+
Provide the Destination Volume Prefix : plane-app
95+
```
96+
97+
If there are any issues, an error will appear. For a successful migration, there will be no error, and the process will exit quietly.
98+
99+
![Migrate Error](/images/docker-compose/migrate-error.png)
100+
101+
11. Restart the upgraded v0.14.0 instance with:
102+
```bash
103+
./setup.sh restart
104+
```
105+
106+
12. Login as instance admin by appending `/god-mode` to your domain.
107+
108+
13. Once logged in, just click **Save Changes** to finalize your setup.
109+
110+
14. You’re all set! Log in to your updated `v0.14-0` instance to check if all of your data has migrated successfully.
111+
112+
15. Now, [update to the latest version](/self-hosting/manage/upgrade-plane#community-edition).

0 commit comments

Comments
 (0)