Merge pull request #55 from makeplane/migrator-troubleshooting

Added troubleshooting sections

Author: danciaclara

mint.json

@@ -107,13 +107,12 @@
         "self-hosting/manage/view-logs",
         "self-hosting/manage/migrate-plane",
         "self-hosting/manage/prime-cli"
-        
-        
       ]
     },
     {
       "group": "Troubleshoot",
       "pages": [
+        "self-hosting/troubleshoot/installation-errors",
         "self-hosting/troubleshoot/license-errors",
         "self-hosting/troubleshoot/cli-errors"
       ]

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

@@ -21,7 +21,11 @@ The Prime CLI lets you easily configure your Commercial Edition instance, provid
 
     - `External Postgres URL`  
         Provide the URL of your external PostgreSQL instance if you want to switch from the default Plane configuration.
-        *Default*: `Postgres 15.5` in the Docker container
+        *Default*: `Postgres 15.5` in the Docker container. 
+
+        <Warning>
+        Don’t use a database on your local machine. If you use `localhost` in the URL, it won’t work. Make sure to use a database hosted on a network-accessible server.
+        </Warning>
 
     - `External Redis URL`  
         Specify the URL of your external Redis instance to override the default Redis configuration.  

self-hosting/methods/kubernetes.mdx

@@ -26,6 +26,10 @@ Plane One and Plane Pro are enabled on this edition, so the Free plan on this ed
         DOMAIN_NAME=<subdomain.domain.tld or domain.tld>
         ```
 
+        <Warning>
+            When configuring the PLANE_VERSION environment variable, **do not** set it to `stable`. Always specify the latest version number (e.g., `1.6.0`). Using `stable` can lead to unexpected issues.
+        </Warning>
+
     3. Add the Plane helm chart repo.
 
         ```bash

self-hosting/troubleshoot/installation-errors.mdx

@@ -0,0 +1,25 @@
+---
+title: Installation errors
+---
+
+This guide is designed to help you resolve common issues encountered while installing Plane. Each section includes potential causes and step-by-step solutions for identified problems.
+
+## Error during Docker Compose execution
+
+<div style={{color:"red"}}> 
+    Error: Error during docker compose execution. Please check permissions and try again.
+</div>
+
+- This error typically occurs when the user doesn't have sudo or root privileges. To resolve this, ensure you're logged in as the root user or as a user with sudo access before attempting the installation again.
+
+- The issue may also be caused by using the older version of Docker Compose `docker-compose`. To fix this, install the latest version of Docker Compose `docker compose` and make sure the old version is removed.
+
+## Migrator container exited
+
+<div style={{color:"red"}}> 
+    Error: plane-migrator-1 container exited with status 1
+</div>
+
+This error typically occurs if you have configured an external database that is running on localhost. Since the connection is being attempted from inside the container, localhost won’t work, as the database is not running within the container.
+
+To resolve this issue, ensure that the database is hosted on a network-accessible server rather than localhost. Update the database URL to reflect the correct server address. See [how to configure external db](/self-hosting/govern/database-and-storage).

self-hosting/troubleshoot/license-errors.mdx

@@ -36,10 +36,7 @@ Updating typically resolves this issue. If the problem persists, double-check yo
 
 This usually occurs when the environment confiuration is incorrect. The  Env variable `payment_server_url` is missing in the setup. In this case, follow the below steps.
 
-1. Backup the `plane.env` file.
-    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.
+1. Backup the `plane.env` file. See [this](http://localhost:3000/self-hosting/manage/backup-restore#backup-plane-env).
 2. Run `prime-cli repair` to allow Prime CLI to attempt automatic fixes to the `plane.env` file.
 3. Try activating your workspace with the license key.
 3. If needed, you can configure the instance in [God mode](/self-hosting/govern/instance-admin#settings) or adjust the environment variables directly in the new plane.env file.