Merge pull request #105 from makeplane/air-gapped-edition

Airgapped Commercial Edition

Author: danciaclara

images/activate-license/upload-license-file.webp

@@ -71,7 +71,8 @@
         "self-hosting/methods/docker-swarm",
         "self-hosting/methods/kubernetes",
         "self-hosting/methods/coolify",
-        "self-hosting/methods/portainer"
+        "self-hosting/methods/portainer",
+        "self-hosting/methods/airgapped-edition"
       ]
     },
     {
@@ -112,6 +113,7 @@
       "group": "Manage",
       "pages": [
         "self-hosting/upgrade-from-community",
+        "self-hosting/manage/community-to-airgapped",
         "self-hosting/manage/backup-restore",
         {
           "group": "Update Plane",

mint.json

@@ -0,0 +1,66 @@
+---
+title: Upgrade from Community to Airgapped Edition
+sidebarTitle: Upgrade to Airgapped Edition
+---
+
+This guide walks you through migrating your existing Plane Community Edition data to an air-gapped environment. You'll backup your current installation, transfer the data, and restore it in your air-gapped setup.
+
+<Warning>
+**Important**  
+Make sure you already have Commercial Airgapped Edition installed on a fresh machine before starting this migration. If you haven't installed it yet, follow our [airgapped installation guide](/self-hosting/methods/airgapped-edition) first.
+</Warning>
+
+## Prerequisites
+
+- Install the [Commercial Airgapped Edition](/self-hosting/methods/airgapped-edition) on a fresh machine, not the one running the Community Edition.
+- Be sure to log in as the root user or as a user with sudo access. The `/opt` folder requires sudo or root privileges.
+
+## Backup data on Community instance
+
+1. Download the latest version of `setup.sh`.
+    ```bash
+    curl -fsSL https://github.com/makeplane/plane/releases/latest/download/setup.sh -o setup.sh
+    ```
+
+2. Run the setup.sh backup script to take the backup of the Community Edition instance.
+    ```bash 
+    ./setup.sh backup
+    ```
+    This will create a backup of the plane community instance in the `backup/` folder with the timestamp as the folder name.
+        ```bash
+        backup/
+        └── 20250605-0938
+            ├── pgdata.tar.gz
+            ├── rabbitmq_data.tar.gz
+            ├── redisdata.tar.gz
+            └── uploads.tar.gz
+        ```
+
+## Restore data on Airgapped instance
+
+1. Download the latest version of `restore-airgapped.sh`
+    ```bash
+    curl -fsSL https://github.com/makeplane/plane/releases/latest/download/restore-airgapped.sh -o restore-airgapped.sh
+    chmod +x restore-airgapped.sh
+    ```
+    This allows you to restore the Community Edition data to the Commercial Airgapped instance.
+
+2. Copy the `restore-airgapped.sh` script into your backup folder.
+
+3. Move your entire backup folder to the server running the Commercial Airgapped Edition.
+
+4. Open terminal, and execute the following command:
+    ```bash
+    sudo bash restore-airgapped.sh ./20250605-0938
+    ```
+    This will prompt you to enter the Commercial Airgapped Edition installation folder using whatever secure method works in your environment.
+
+5. After the data restore is finished, start the instance.
+    ```bash
+    cd <airgapped-instance-folder>
+    sudo docker compose -f docker-compose.yml --env-file plane.env up -d
+    ```
+
+    You can now access the Commercial Airgapped instance at `http://<ip-address|domain-name>`
+
+Once your migration is complete, verify that all your projects, issues, and team data have been successfully transferred to your air-gapped environment.

self-hosting/manage/community-to-airgapped.mdx

@@ -0,0 +1,180 @@
+---
+title: Deploy Plane Commercial Airgapped Edition
+sidebarTitle: Airgapped Edition
+---
+
+This guide walks you through setting up the Commercial Airgapped Edition in an offline environment using our pre-packaged installation bundle.
+
+<Warning>
+**IMPORTANT**  
+These instructions are for new installations only. If you're migrating from an existing Community Edition to an air-gapped setup, follow [this guide](/self-hosting/manage/community-to-airgapped).
+</Warning>
+
+## Prerequisites
+Before we get started, make sure your air-gapped machine has:
+
+- Docker (version 24 or later) up and running
+- Docker Compose Plugin installed (you should be able to run `docker compose` or `docker-compose`)
+- The Plane air-gapped package we provide includes:
+    - Docker image files (`.tar` format)
+    - Configuration files (`docker-compose.yml` and `plane.env`)
+    - Installation script (`install.sh`)
+
+### Required files
+
+- `docker-compose.yml` - Docker Compose configuration for service orchestration
+- `plane.env` - Default configuration file containing environment variables
+- `admin-commercial-<version>.tar` - Docker image for admin service
+- `backend-commercial-<version>.tar` - Docker image for api/worker/beat-worker/migrator service
+- `email-commercial-<version>.tar` - Docker image for email service
+- `live-commercial-<version>.tar` - Docker image for live service
+- `monitor-commercial-<version>.tar` - Docker image for monitor service
+- `proxy-commercial-<version>.tar` - Docker image for plane-proxy service
+- `silo-commercial-<version>.tar` - Docker image for silo service
+- `space-commercial-<version>.tar` - Docker image for space service
+- `web-commercial-<version>.tar` - Docker image for web service
+- `minio-latest.tar` - Docker image for plane-minio service
+- `postgres-15.7-alpine.tar` - Docker image for plane-db service
+- `rabbitmq-3.13.6-management-alpine.tar` - Docker image for plane-mq service
+- `valkey-7.2.5-alpine.tar` - Docker image for plane-redis service
+
+## Install Plane
+1. Get in touch with [email protected] to get your installation download URL and the license file.
+
+2. On a machine that has internet access, download the installation package:
+
+    ```bash
+    curl -LO <asset-download-url>
+    ```
+    
+    The download may take 15 minutes. Once the file is downloaded you no longer need internet access.  
+
+3. Transfer the `airgapped-{arch}.tar.gz` file to your air-gapped machine.
+
+4. Once you have the file on your air-gapped machine, extract the package.
+
+    ```bash
+    mkdir -p airgapped
+    tar -xvzf airgapped-amd64.tar.gz -C airgapped
+    cd airgapped
+    ```
+
+    The airgapped directory contains your `plane.env`, `docker-compose.yml`, and `install.sh` files which are used in the following steps.  
+
+5. Run the installation script:
+    ```bash
+    bash install.sh
+    ```
+
+    The script will guide you through the process step by step. Here's what to expect:
+
+        ```bash
+        **********************************************************
+        You are about to install/upgrade Plane as airgapped setup
+
+        Pre-requisites:  
+
+        - Docker installed and running
+        - Docker version 24 or higher
+        - docker-compose or docker compose installed
+        - A tarball of all the images
+        - A docker-compose.yml file (docker-compose.yml)
+        - A plane.env file (plane.env)
+        **********************************************************
+
+        Enter the directory to install Plane (default: /home/ubuntu/planeairgapped):
+
+        Enter the domain or ip address to access Plane (default: 127.0.0.1): plane.mycompany.com
+
+        **********************************************************
+        Verify the final configuration:
+        - Setup Directory: /home/ubuntu/planeairgapped
+        - App Domain: plane.mycompany.com
+        - Installation Type: New
+        **********************************************************
+        ```
+
+    Once you confirm your settings, the installer will:
+        - Copy the `docker-compose.yml` and `plane.env` files to your chosen installation directory.
+        - Create the necessary folders for data and logs.
+        - Load all the Docker images into your local Docker registry.
+
+    You'll see something like this when the installation completes:
+        ```bash
+        **********************************************************
+        Plane Setup is ready to configure and start
+
+        Use below commands to configure and start Plane
+        Switch to the setup directory
+            cd /home/ubuntu/planeairgapped
+        Start the services
+            docker compose -f docker-compose.yml --env-file plane.env up -d
+        Check logs of migrator service and wait for it to finish using below command
+            docker compose logs -f migrator
+        Check logs of api service and wait for it to start using below command
+            docker compose logs -f api
+        Once the api service is started, you can access Plane at http://plane.mycompany.com
+        **********************************************************
+        Installation completed successfully
+        You can access Plane at http://plane.mycompany.com
+        ```
+
+    After installation, your directory structure will look like this:
+    ```bash
+    ~/planeairgapped/
+    ├── docker-compose.yml
+    ├── plane.env
+    ├── data/
+    └── logs/
+    ```
+
+## Environment variables
+
+The following key environment variables are automatically configured during installation:
+
+- `MACHINE_SIGNATURE` - A unique UUID generated for your installation
+- `DOMAIN_NAME` - The domain or IP address where Plane will be accessible
+- `WEB_URL` - The full URL where Plane will be accessible (e.g., `http://your-domain`)
+- `CORS_ALLOWED_ORIGINS` - Allowed origins for CORS (Cross-Origin Resource Sharing)
+
+## Start Plane
+1. To get Plane up and running, navigate to your installation directory and start the services:
+    ```bash
+    cd ~/planeairgapped
+    docker compose --env-file plane.env up -d
+    ```
+
+2. Watch the logs to make sure everything starts properly.
+    - To monitor the database migration process:
+    ```bash
+    docker compose logs -f migrator
+    ```
+
+    - To monitor the API service startup:
+    ```bash
+    docker compose logs -f api
+    ```
+
+    The api is healthy when you see`: api-1   listening at`
+
+Once both services are running smoothly, you can access Plane by opening your browser and going to the domain or IP address you configured during installation.
+
+## Activate your license
+
+Once your air-gapped installation is running, you'll need to activate your workspace with the provided license file.
+<Note>
+You should have received the `license_key.json` file as part of your air-gapped package. If you don't have this file, contact our support team.
+</Note>
+
+1. Go to your [Workspace Settings](/core-concepts/workspaces/overview#workspace-settings) in the Plane application.
+2. Select **Billing and plans** on the right pane.
+3. Click the **Activate this workspace** button.
+    ![Upload license file](/images/activate-license/upload-license-file.webp)
+4. Upload the license file `license_key.json` to activate your workspace.
+
+You now have Plane running in your air-gapped environment. If you run into any issues, check the logs using the commands above, or reach out to our support team for assistance.
+
+<Tip>
+*Optional*  
+Once everything is working, you can safely delete the `airgapped` folder that contains the installation script and image files to free up space.
+</Tip>

self-hosting/methods/airgapped-edition.mdx

@@ -5,40 +5,45 @@ sidebarTitle: Upgrade to Commercial Edition
 The Commercial edition comes with the free plan and the flexibility to upgrade to a paid plan at any point.
 
 <Warning> 
- Follow the instructions below first all the way to the end of the section **Restore data**.  
+**IMPORTANT**  
 
- The instructions provided on this page are specific to installations using Docker. If you are running Plane on Kubernetes, you'll need to manually create a database dump and back up your file storage by copying the relevant volumes or storage paths.
+Make sure you already have Commercial Edition installed on a fresh machine before starting this migration. If you haven’t installed it yet, follow our [Commercial Edition](/self-hosting/methods/docker-compose#recommended-edition) installation guide first.
+
+The instructions provided on this page are specific to installations using Docker. If you are running Plane on Kubernetes, you'll need to manually create a database dump and back up your file storage by copying the relevant volumes or storage paths.
 </Warning>
 
 ## Prerequisites
-
--  Install on a fresh machine, not the one running the Plane Community Edition.
+- Install the [Commercial Edition](/self-hosting/methods/docker-compose#recommended-edition) on a fresh machine, not the one running the Plane Community Edition.
 - Be sure to log in as the root user or as a user with sudo access. The `/opt` folder requires sudo or root privileges.
 
+## Back up data on Community instance
+1. Download the latest version of `setup.sh`.
+    ```bash
+    curl -fsSL https://github.com/makeplane/plane/releases/latest/download/setup.sh -o setup.sh
+    ```
 
-## Back up data on Community Edition
-
-`setup.sh` in the Community Edition now comes with an option to back up your data.
-
-1. Use  `./setup.sh` to open the operator menu and select `7` to backup your Plane data.
-2. When done, your data will be backed up to the folder shown on the screen.
-e.g., `/plane-selfhost/plane-app/backup/20240522-1027`
-3. This folder will contain 3 `tar.gz` files.
+2. Run the setup.sh backup script to take the backup of the Community Edition instance.
+    ```bash 
+    ./setup.sh backup
+    ```
+3. When done, your data will be backed up to the folder shown on the screen.
+    e.g., `/plane-selfhost/plane-app/backup/20240522-1027`
+     This folder will contain 3 `tar.gz` files.
     - `pgdata.tar.gz`
     - `redisdata.tar.gz`
     - `uploads.tar.gz`
-4. Copy all the 3 files from the server running the Community Edition to any folder on the server running Plane One on any folder of your choice.
 
-e.g., `~/ce-backup`
+4. Copy all the 3 files from the server running the Community Edition to any folder on the server running the Commercial Edition on any folder of your choice.
+
+    e.g., `~/ce-backup`
 
-## Restore data and install Commercial Edition
+## Restore data on Commercial instance
 1. Start any command-line interface like Terminal and go into the folder with the back-up files.
     ```
     cd ~/ce-backup
     ```
 2. Copy and paste the script below on Terminal and hit Enter.
     ```
-    
     TARGET_DIR=/opt/plane/data
     sudo mkdir -p $TARGET_DIR
     for FILE in *.tar.gz; do
@@ -55,7 +60,4 @@ e.g., `~/ce-backup`
     mkdir -p $TARGET_DIR/minio
     mv $TARGET_DIR/uploads/ $TARGET_DIR/minio/uploads/
     ```
-3. This script will extract your Community Edition data and restore it to /opt/plane/data.
-4. Install the **Commercial** Edition.
-    - Using [Docker](/self-hosting/methods/docker-compose#recommended-edition)
-    - Using [Kubernetes](/self-hosting/methods/kubernetes#recommended-edition)
+3. This script will extract your Community Edition data and restore it to `/opt/plane/data`.