Merge pull request #143 from langflow-ai/docs-troubleshooting

docs: troubleshooting page

README.md

@@ -138,7 +138,7 @@ podman machine start
 
 ### Common Issues
 
-See common issues and fixes: [docs/reference/troubleshooting.mdx](docs/docs/reference/troubleshooting.mdx)
+See common issues and fixes: [docs/support/troubleshoot.mdx](docs/docs/reference/troubleshoot.mdx)
 
 
 

docs/docs/reference/troubleshooting.mdx

@@ -1,24 +0,0 @@
----
-title: Troubleshooting
-slug: /reference/troubleshooting
----
-
-# Troubleshooting
-
-## Podman on macOS
-
-If using Podman on macOS, you may need to increase VM memory:
-
-```bash
-podman machine stop
-podman machine rm
-podman machine init --memory 8192   # 8 GB example
-podman machine start
-```
-
-## Common Issues
-
-1. OpenSearch fails to start: Check that `OPENSEARCH_PASSWORD` is set and meets requirements
-2. Langflow connection issues: Verify `LANGFLOW_SUPERUSER` credentials are correct
-3. Out of memory errors: Increase Docker memory allocation or use CPU-only mode
-4. Port conflicts: Ensure ports 3000, 7860, 8000, 9200, 5601 are available

docs/docs/support/troubleshoot.mdx

@@ -0,0 +1,107 @@
+---
+title: Troubleshoot
+slug: /support/troubleshoot
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+This page provides troubleshooting advice for issues you might encounter when using OpenRAG or contributing to OpenRAG.
+
+## OpenSearch fails to start
+
+Check that `OPENSEARCH_PASSWORD` is set and meets requirements.
+The password must contain at least 8 characters, and must contain at least one uppercase letter, one lowercase letter, one digit, and one special character that is strong.
+
+## Langflow connection issues
+
+Verify the `LANGFLOW_SUPERUSER` credentials are correct.
+
+## Memory errors
+
+### Container out of memory errors
+
+Increase Docker memory allocation or use [docker-compose-cpu.yml](https://github.com/langflow-ai/openrag/blob/main/docker-compose-cpu.yml) to deploy OpenRAG.
+
+### Podman on macOS memory issues
+
+If you're using Podman on macOS, you may need to increase VM memory on your Podman machine.
+This example increases the machine size to 8 GB of RAM, which should be sufficient to run OpenRAG.
+   ```bash
+   podman machine stop
+   podman machine rm
+   podman machine init --memory 8192   # 8 GB example
+   podman machine start
+   ```
+   
+## Port conflicts
+
+Ensure ports 3000, 7860, 8000, 9200, 5601 are available.
+
+## Langflow container already exists
+
+If you are running other versions of Langflow containers on your machine, you may encounter an issue where Docker or Podman  thinks Langflow is already up.
+
+Remove just the problem container, or clean up all containers and start fresh. 
+
+To reset your local containers and pull new images, do the following:
+
+1. Stop your containers and completely remove them.
+
+<Tabs groupId="Container software">
+  <TabItem value="Docker" label="Docker" default>
+
+    ```bash
+    # Stop all running containers
+    docker stop $(docker ps -q)
+    
+    # Remove all containers (including stopped ones)
+    docker rm --force $(docker ps -aq)
+    
+    # Remove all images
+    docker rmi --force $(docker images -q)
+    
+    # Remove all volumes
+    docker volume prune --force
+    
+    # Remove all networks (except default)
+    docker network prune --force
+    
+    # Clean up any leftover data
+    docker system prune --all --force --volumes
+    ```
+
+   </TabItem>
+   <TabItem value="Podman" label="Podman">
+
+    ```bash
+    # Stop all running containers
+    podman stop --all
+    
+    # Remove all containers (including stopped ones)
+    podman rm --all --force
+    
+    # Remove all images
+    podman rmi --all --force
+    
+    # Remove all volumes
+    podman volume prune --force
+    
+    # Remove all networks (except default)
+    podman network prune --force
+    
+    # Clean up any leftover data
+    podman system prune --all --force --volumes
+    ```
+
+  </TabItem>
+</Tabs>
+
+2. Restart OpenRAG and upgrade to get the latest images for your containers.
+   ```bash
+   uv run openrag
+   ```
+
+3. In the OpenRAG TUI, click **Status**, and then click **Upgrade**.
+When the **Close** button is active, the upgrade is complete.
+Close the window and open the OpenRAG appplication. 

docs/sidebars.js

@@ -76,12 +76,12 @@ const sidebars = {
     },
     {
       type: "category",
-      label: "Reference",
+      label: "Support",
       items: [
         {
           type: "doc",
-          id: "reference/troubleshooting",
+          id: "support/troubleshoot",
-          label: "Troubleshooting"
+          label: "Troubleshoot"
         },
       ],
     },