Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 25 additions & 3 deletions docs/self-hosting/manage/backup-restore.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,8 @@ keywords: plane backup, plane restore, database backup, postgresql backup, data

Backing up your data regularly helps prevent data loss and allows you to restore your system quickly if necessary. Follow these instructions to back up and restore your data using Plane’s command-line interface.

## Backup data
## For Docker Compose
### Backup data

::: warning
**Prime CLI is for Docker installations only.** These commands only work on Plane instances originally installed using `prime-cli`.
Expand All @@ -28,15 +29,15 @@ This command initiates a full backup of all critical data, storing it in the def

Each backup file will be timestamped to ensure you can easily identify the latest or a specific backup if needed.

## Backup plane.env
### Backup plane.env

If you need to back up only the `plane.env` file, you'll need to do it manually. Here’s how:

1. Navigate to the `/opt/plane` folder on your machine or server where Plane is installed..
2. Locate the `plane.env` file.
3. Copy this file to a different location as a backup, so you can restore it if needed.

## Restore data
### Restore data

You can restore your data from a previous backup with ↓:

Expand Down Expand Up @@ -150,3 +151,24 @@ Follow these steps to restore data from a backup:
That’s it! You’re back up and running with your restored data.

:::


## Other deployment methods

For Kubernetes, or other deployment methods, use your platform's native backup tools. Plane stores data in two places that need to be backed up:
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Line exceeds 120 character limit.

Line 158 contains 161 characters, exceeding the 120 character line width requirement.

📏 Proposed fix to wrap the line
-For Kubernetes, or other deployment methods, use your platform's native backup tools. Plane stores data in two places that need to be backed up:
+For Kubernetes, or other deployment methods, use your platform's native backup tools. Plane stores data in two
+places that need to be backed up:

As per coding guidelines, files should maintain a 120 character line width.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
For Kubernetes, or other deployment methods, use your platform's native backup tools. Plane stores data in two places that need to be backed up:
For Kubernetes, or other deployment methods, use your platform's native backup tools. Plane stores data in two
places that need to be backed up:
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/self-hosting/manage/backup-restore.md` at line 158, The line "For
Kubernetes, or other deployment methods, use your platform's native backup
tools. Plane stores data in two places that need to be backed up:" exceeds the
120-character limit; split or wrap this sentence in
docs/self-hosting/manage/backup-restore.md so no resulting line is longer than
120 characters (e.g., break into two sentences or wrap after "backup tools." or
"Plane stores data..."), keeping the original wording and punctuation intact and
ensuring each new line stays ≤120 chars.


| Component | What it contains |
|-----------|------------------|
| **PostgreSQL database** | All Plane data — workspaces, projects, work items, users, comments, settings |
| **Object storage** | Attachments, uploaded images, files (MinIO, S3, or S3-compatible storage) |

### Configuration files

Also back up your environment configuration — this includes database connection strings, storage credentials, and other settings.

- **Kubernetes:** Helm values file, ConfigMaps, and Secrets
- **Other platforms:** Environment variables or configuration files specific to your setup

:::tip
Store backups in a separate location from your Plane installation — ideally offsite or in a different cloud region.
:::
116 changes: 116 additions & 0 deletions docs/self-hosting/upgrade-from-community.md
Original file line number Diff line number Diff line change
Expand Up @@ -115,6 +115,122 @@ This upgrade path is for installations using external or managed database and ob
```

Your Commercial Edition instance is now connected to your existing external database and storage.
:::

:::details Manual backup and restore without CLI

Use this method if you prefer to back up data manually or if the setup.sh script isn't working for your environment.

### What gets migrated

- PostgreSQL database (all Plane data)
- MinIO uploads (attachments, images, files)

### Prerequisites

- Plane CE and Commercial versions should be compatible
- Shell access to both servers
- Docker installed on both servers

### Back up data on Community instance

1. Create backup folders:

```bash
mkdir -p ~/ce-backups/db
mkdir -p ~/ce-backups/minio/uploads
cd ~/ce-backups
```

2. Back up PostgreSQL data:

```bash
docker cp plane-app-plane-db-1:/var/lib/postgresql/data/. db/
```

3. Back up MinIO uploads:

```bash
docker cp plane-app-plane-minio-1:/export/uploads minio/uploads/
Comment on lines +148 to +154
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

# Find docker-compose files
fd -e yml -e yaml . | grep -i docker-compose

Repository: makeplane/developer-docs

Length of output: 50


🏁 Script executed:

# Check the markdown file frontmatter and content
head -50 docs/self-hosting/upgrade-from-community.md

Repository: makeplane/developer-docs

Length of output: 2080


🏁 Script executed:

# Search for container names in docker-compose files
rg "plane-app|services:" --type yaml -A 5 | head -100

Repository: makeplane/developer-docs

Length of output: 50


🏁 Script executed:

# Check if there's a docker-compose file in the repo root or docs
find . -maxdepth 3 -name "*docker-compose*" -type f

Repository: makeplane/developer-docs

Length of output: 50


🏁 Script executed:

# Get lines 148-154 of the markdown file
sed -n '148,154p' docs/self-hosting/upgrade-from-community.md

Repository: makeplane/developer-docs

Length of output: 248


🏁 Script executed:

# Get more context around those lines
sed -n '140,160p' docs/self-hosting/upgrade-from-community.md

Repository: makeplane/developer-docs

Length of output: 453


🏁 Script executed:

# Search for container name references in docs
rg "docker cp|plane-app-plane" docs/ -A 2 -B 2

Repository: makeplane/developer-docs

Length of output: 1294


🏁 Script executed:

# Search for docker ps or container discovery guidance in docs
rg "docker ps|container name|project.name|PROJECT_NAME" docs/ -i

Repository: makeplane/developer-docs

Length of output: 6818


🏁 Script executed:

# Check if there are other self-hosting docs that address container naming
fd -e md . docs/self-hosting/ | head -20

Repository: makeplane/developer-docs

Length of output: 952


🏁 Script executed:

# Check the documentation style - look for existing tip/warning boxes
rg ":::tip|:::warning|:::info|:::note" docs/self-hosting/ -A 2

Repository: makeplane/developer-docs

Length of output: 2143


🏁 Script executed:

# Check the reset-password.md file to see how it handles container discovery
cat docs/self-hosting/govern/reset-password.md | grep -A 10 -B 5 "docker ps"

Repository: makeplane/developer-docs

Length of output: 437


🏁 Script executed:

# Check storage-errors.md to see the container guidance
sed -n '1,50p' docs/self-hosting/troubleshoot/storage-errors.md

Repository: makeplane/developer-docs

Length of output: 1963


🏁 Script executed:

# Check the setup.sh approach mentioned in the upgrade doc
sed -n '1,200p' docs/self-hosting/upgrade-from-community.md | grep -A 20 "setup.sh backup"

Repository: makeplane/developer-docs

Length of output: 837


🏁 Script executed:

# Check if there's a methods doc that explains container naming
cat docs/self-hosting/methods/docker-compose.md 2>/dev/null | head -100

Repository: makeplane/developer-docs

Length of output: 4407


🏁 Script executed:

# Search for how other docs reference containers
rg "container.*name|<container" docs/self-hosting/ -B 2 -A 2

Repository: makeplane/developer-docs

Length of output: 1533


Add guidance for discovering actual database and MinIO container names

The hardcoded container names plane-app-plane-db-1 and plane-app-plane-minio-1 assume the installation was performed in a directory named "plane-app". Container names are generated from the parent directory name following the pattern {directory-name}-{service-name}-{replica}. Users who installed Plane in a differently named directory will have different container names and these commands will fail.

Add container discovery tips
 2. Back up PostgreSQL data:

+   :::tip
+   If the command below fails, run `docker ps --filter "name=db"` to find your actual database container name.
+   Replace `plane-app-plane-db-1` with your container name.
+   :::
+
    ```bash
    docker cp plane-app-plane-db-1:/var/lib/postgresql/data/. db/
    ```

 3. Back up MinIO uploads:

+   :::tip
+   If the command below fails, run `docker ps --filter "name=minio"` to find your actual MinIO container name.
+   Replace `plane-app-plane-minio-1` with your container name.
+   :::
+
    ```bash
    docker cp plane-app-plane-minio-1:/export/uploads minio/uploads/
    ```
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@docs/self-hosting/upgrade-from-community.md` around lines 148 - 154, The doc
uses hardcoded container names (plane-app-plane-db-1 and
plane-app-plane-minio-1) which can differ if the user’s parent directory isn’t
"plane-app"; add a short tip near both docker cp examples explaining the
container-name pattern ({directory-name}-{service-name}-{replica}) and instruct
users to discover their actual container names with docker ps --filter
"name=minio" for MinIO and docker ps --filter "name=db" or docker ps --filter
"name=postgres" for the database, then replace the example container names
accordingly so the docker cp commands succeed.

```

4. Verify backup sizes:

```bash
du -sh db minio/uploads
```

Make sure sizes look reasonable (not just a few KB).

5. Transfer backup to Commercial server:

```bash
scp -r ~/ce-backups user@commercial-server:/tmp/
```

### Restore data on Commercial instance

1. Stop Plane:

```bash
prime-cli stop
```

Verify all containers are down:

```bash
docker ps
```

2. Back up existing Commercial data (safety precaution):

```bash
mv /opt/plane/data/db /opt/plane/data/db.bak
mv /opt/plane/data/minio/uploads /opt/plane/data/minio/uploads.bak
```

3. Restore PostgreSQL:

```bash
mv /tmp/ce-backups/db /opt/plane/data/db
```

4. Restore MinIO uploads:

```bash
mv /tmp/ce-backups/minio/uploads /opt/plane/data/minio/uploads
```

5. Start Plane:

```bash
prime-cli restart
```

### Validate the migration

- Login works
- Projects are visible
- Attachments open correctly

### Rollback

If something fails, restore from the backup you created in step 2:

```bash
prime-cli stop

rm -rf /opt/plane/data/db
mv /opt/plane/data/db.bak /opt/plane/data/db

rm -rf /opt/plane/data/minio/uploads
mv /opt/plane/data/minio/uploads.bak /opt/plane/data/minio/uploads

prime-cli restart
```

:::


## What's next

Expand Down
Loading