From eb78e04262bacbc4c59bb239c4ef48e86ecd59cb Mon Sep 17 00:00:00 2001
From: HMS091 Bot <hms091-bot@users.noreply.github.com>
Date: Wed, 3 Jun 2026 18:07:06 +0000
Subject: [PATCH] fix: Add a troubleshooting page for common setup errors

Closes #321

Bounty submission.
---
 README.md               | 249 ++++++++--------------------------------
 docs/troubleshooting.md | 160 ++++++++++++++++++++++++++
 2 files changed, 209 insertions(+), 200 deletions(-)
 create mode 100644 docs/troubleshooting.md

diff --git a/README.md b/README.md
index 4a1697c..25f18f9 100644
--- a/README.md
+++ b/README.md
@@ -1,230 +1,79 @@
-<div align="center">
+# LocalMind
 
-<img src="https://img.shields.io/badge/LocalMind-v2.0.0-7C3AED?style=for-the-badge&logoColor=white" />
+LocalMind is a privacy-focused, local-first AI chat application that runs entirely on your machine. It uses Ollama for local LLM inference, supports RAG (Retrieval-Augmented Generation), and provides a modern web interface.
 
-# LocalMind v2.0
-### Offline AI Assistant - Chat with Your Documents. Privately.
+## Features
 
-**No cloud. No API key. No data leaks. Runs 100% on your machine.**
+- 🤖 **Local AI**: Runs models locally using Ollama – no data leaves your machine
+- 💬 **Chat Interface**: Clean, responsive UI for conversations
+- 📄 **RAG Support**: Upload documents and ask questions about them
+- 🔌 **Plugin System**: Extend functionality with custom plugins
+- 📤 **Export**: Export conversations in various formats
+- 🎨 **Customizable**: Adjust settings to your preferences
 
-[![Python](https://img.shields.io/badge/Python-3.11+-3776AB?style=flat-square&logo=python)](https://python.org)
-[![FastAPI](https://img.shields.io/badge/FastAPI-0.115-009688?style=flat-square&logo=fastapi)](https://fastapi.tiangolo.com)
-[![React](https://img.shields.io/badge/React-18-61DAFB?style=flat-square&logo=react&logoColor=black)](https://react.dev)
-[![Ollama](https://img.shields.io/badge/Ollama-Local_LLM-black?style=flat-square)](https://ollama.ai)
-[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=flat-square)](LICENSE)
-[![SSoC 2026](https://img.shields.io/badge/SSoC-2026-blueviolet?style=flat-square)](https://ssoc.dev)
-[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=flat-square)](CONTRIBUTING.md)
-
-<br/>
-
-[Quick Start](#quick-start) · [Features](#features) · [Tech Stack](#tech-stack) · [Contributing](#contributing) · [Screenshots](#screenshots)
-
----
+## Quick Start
 
-</div>
+### Prerequisites
 
-## What's New in v2.0
+- [Docker](https://docs.docker.com/get-docker/) & [Docker Compose](https://docs.docker.com/compose/install/)
+- [Ollama](https://ollama.com/download) (for local LLM)
 
-| Feature | Description |
-|---------|-------------|
-| Streaming Responses | See AI reply token-by-token in real time |
-| Plugin System | Calculator, Word Counter, JSON Formatter, Code Runner, Summarizer |
-| 8 Languages | English, Hindi, Tamil, Telugu, Kannada, French, German, Spanish |
-| Export Chats | Download conversations as Markdown, JSON, or TXT |
-| Session Manager | Full CRUD - create, rename, search, delete chat sessions |
-| Settings Panel | Temperature, RAG chunks, model, theme, language |
-| Docker v2 | Health checks, persistent volumes, nginx reverse proxy |
-| 30+ Tests | Full pytest suite with mocked Ollama |
+### Setup
 
----
+1. **Clone the repository**
+   ```bash
+   git clone https://github.com/imDarshanGK/localmind.git
+   cd localmind
+   ```
 
-## All Features
+2. **Set up environment variables**
+   ```bash
+   cp .env.example .env
+   cp frontend/.env.example frontend/.env
+   ```
 
-| Feature | Status |
-|---------|--------|
-| Fully Offline (Ollama) | Included |
-| PDF / TXT / CSV / DOCX / MD / HTML upload | Included |
-| RAG — Chat with Documents | Included |
-| Streaming Responses (SSE) | Included |
-| Multi-Model (Llama3, Mistral, Phi3, Gemma, DeepSeek) | Included |
-| 8 UI Languages | Included |
-| Chat History (SQLite) | Included |
-| Session Manager (CRUD) | Included |
-| Session Search | Included |
-| Plugin System (6 plugins) | Included |
-| Export (MD / JSON / TXT) | Included |
-| Settings Panel | Included |
-| Docker Compose | Included |
-| 30+ Tests | Included |
-| Zero telemetry | Included |
+3. **Pull a model (optional but recommended)**
+   ```bash
+   ollama pull llama3.2
+   ```
 
----
+4. **Start the application**
+   ```bash
+   docker compose up --build
+   ```
 
-## 🛠 Tech Stack
+5. **Access the app**
+   - Frontend: [http://localhost:3000](http://localhost:3000)
+   - Backend API: [http://localhost:8000](http://localhost:8000)
 
-```
-┌────────────────────────────────────────────────┐
-│               LocalMind v2.0                   │
-├──────────────┬─────────────────────────────────┤
-│  Frontend    │  React 18 + Tailwind + Vite     │
-│  Backend     │  Python 3.11 + FastAPI          │
-│  AI Engine   │  Ollama (local LLM)             │
-│  RAG         │  LangChain + ChromaDB           │
-│  Embeddings  │  sentence-transformers (local)  │
-│  Database    │  SQLite (100% local)            │
-│  Streaming   │  Server-Sent Events (SSE)       │
-│  Deploy      │  Docker Compose + nginx         │
-│  Testing     │  pytest + TestClient            │
-└──────────────┴─────────────────────────────────┘
-```
+## Development
 
----
-
-## Quick Start
-
-### Option 1 - Docker (Recommended, 3 commands)
+### Backend
 
 ```bash
-# 1. Pull a model (one-time, ~4GB)
-ollama pull llama3
-
-# 2. Clone and start
-git clone https://github.com/yourusername/localmind.git
-cd localmind && docker compose up
-
-# 3. Open browser
-open http://localhost:3000
-```
-
-### Option 2 - Manual Setup
-
-```bash
-git clone https://github.com/yourusername/localmind.git
-cd localmind
-
-# Backend
 cd backend
-python -m venv venv && source venv/bin/activate
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
 pip install -r requirements.txt
-cp ../.env.example ../.env
-uvicorn app:app --reload --port 8000
-
-# Frontend (new terminal)
-cd frontend
-npm install && npm run dev
-# Open http://localhost:3000
+python app.py
 ```
 
-**Prerequisites:** [Python 3.11+](https://python.org) | [Node 18+](https://nodejs.org) | [Ollama](https://ollama.ai) | [Docker](https://docker.com)
-
-### Render Deploy
-
-If you deploy on Render, set the frontend build to use `VITE_API_BASE_URL` and configure the backend with `CORS_ORIGINS`.
+### Frontend
 
 ```bash
-# backend service envs
-OLLAMA_HOST=http://<your-ollama-host>:11434
-DEFAULT_MODEL=llama3
-CORS_ORIGINS=https://<your-frontend>.onrender.com
-
-# frontend static site envs
-VITE_API_BASE_URL=https://<your-backend>.onrender.com/api
-```
-
-The included `render.yaml` defines a backend web service and a frontend static site for the same repo.
-
----
-
-## Project Structure
-
-```
-localmind/
-├── backend/
-│   ├── app.py                    # FastAPI entry point
-│   ├── routes/
-│   │   ├── chat.py               # /api/chat — streaming + standard
-│   │   ├── sessions.py           # /api/sessions — full CRUD
-│   │   ├── upload.py             # /api/upload — file indexing
-│   │   ├── models.py             # /api/models — Ollama management
-│   │   ├── plugins.py            # /api/plugins — 6 built-in plugins
-│   │   ├── export.py             # /api/export — MD, JSON, TXT
-│   │   └── settings.py           # /api/settings — app config
-│   ├── services/
-│   │   ├── rag_service.py        # LangChain + ChromaDB RAG
-│   │   ├── ollama_service.py     # Ollama + streaming
-│   │   └── db_service.py        # SQLite — all CRUD
-│   ├── models/
-│   │   └── schemas.py           # Pydantic v2 schemas
-│   ├── tests/
-│   │   └── test_api.py          # 30+ tests
-│   ├── requirements.txt
-│   └── Dockerfile
-├── frontend/
-│   ├── src/
-│   │   ├── App.jsx               # Root — state, routing
-│   │   ├── components/
-│   │   │   ├── ChatWindow.jsx    # Messages + streaming + export
-│   │   │   ├── Sidebar.jsx       # Sessions + model + language
-│   │   │   ├── StatusBar.jsx     # Header toolbar
-│   │   │   ├── UploadPanel.jsx   # Drag-drop file upload
-│   │   │   ├── PluginsPanel.jsx  # Plugin runner UI
-│   │   │   └── SettingsPanel.jsx # Settings form
-│   │   └── utils/
-│   │       └── api.js            # All backend API calls
-│   ├── package.json
-│   ├── vite.config.js
-│   └── Dockerfile
-├── docker-compose.yml
-├── .env.example
-├── .gitignore
-├── README.md
-├── CONTRIBUTING.md
-└── ROADMAP.md
-```
-
----
-
-## Plugins
-
-| Plugin | Description |
-|--------|-------------|
-| Calculator | Safe math evaluator (supports `sqrt`, `log`, `sin`, etc.) |
-| Summarizer | Extractive summary of long text |
-| Word Counter | Words, chars, sentences, paragraphs |
-| {} JSON Formatter | Validate and pretty-print JSON |
-| Code Runner | Run Python snippets in a sandbox |
-| Translator | Language detection + translation via LocalMind |
-
----
-
-## Running Tests
-
-```bash
-cd backend
-pip install pytest pytest-asyncio
-pytest tests/ -v
-# 30+ tests covering: sessions, chat, plugins, upload, export, settings
+cd frontend
+npm install
+npm run dev
 ```
 
----
-
-## 🤝 Contributing
-
-1. Fork → Clone → Create branch (`git checkout -b feature/your-feature`)
-2. Make changes → Write tests → Commit (`git commit -m "feat: ..."`)
-3. Push → Open Pull Request
+## Troubleshooting
 
-Issues labeled [`good-first-issue`](https://github.com/yourusername/localmind/issues?q=label%3Agood-first-issue) are perfect for beginners!
+If you encounter any issues during setup, please refer to our [Troubleshooting Guide](docs/troubleshooting.md) for solutions to common problems.
 
-Read [CONTRIBUTING.md](CONTRIBUTING.md) for the full guide.
+## Contributing
 
----
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
 
 ## License
 
-MIT © 2026
-<div align="center">
-
-If LocalMind helped you, please star the repo. ⭐✨🚀
-
-</div>
\ No newline at end of file
+This project is licensed under the MIT License – see the LICENSE file for details.
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
new file mode 100644
index 0000000..c9078bd
--- /dev/null
+++ b/docs/troubleshooting.md
@@ -0,0 +1,160 @@
+# Troubleshooting Guide
+
+This page covers common setup errors and how to resolve them when running LocalMind locally.
+
+## Prerequisites
+
+- Docker & Docker Compose installed
+- Node.js 18+ and npm (for frontend development)
+- Python 3.10+ (for backend development)
+
+---
+
+## 1. Docker / Docker Compose Issues
+
+### Error: `docker: command not found`
+
+**Cause:** Docker is not installed or not in your PATH.
+
+**Solution:**
+- Install Docker Desktop from [docker.com](https://www.docker.com/products/docker-desktop/)
+- After installation, restart your terminal and verify with `docker --version`
+
+### Error: `docker-compose: command not found`
+
+**Cause:** Docker Compose is not installed separately (older Docker versions).
+
+**Solution:**
+- Docker Compose is included in Docker Desktop (v2+). Use `docker compose` (without hyphen) instead.
+- Or install it manually: [Install Docker Compose](https://docs.docker.com/compose/install/)
+
+### Error: `port is already allocated` or `address already in use`
+
+**Cause:** Another service is using port 3000 (frontend) or 8000 (backend).
+
+**Solution:**
+- Stop the conflicting service, or
+- Change the port mapping in `docker-compose.yml`:
+  ```yaml
+  services:
+    frontend:
+      ports:
+        - "3001:80"   # change 3000 to 3001
+    backend:
+      ports:
+        - "8001:8000" # change 8000 to 8001
+  ```
+
+### Error: `Cannot connect to the Docker daemon`
+
+**Cause:** Docker daemon is not running.
+
+**Solution:**
+- On macOS/Windows: Start Docker Desktop from your applications.
+- On Linux: Run `sudo systemctl start docker` (or `sudo service docker start`).
+
+---
+
+## 2. Backend Issues
+
+### Error: `ModuleNotFoundError: No module named 'backend'`
+
+**Cause:** Running Python commands from the wrong directory.
+
+**Solution:**
+- Always run backend commands from the `backend/` directory:
+  ```bash
+  cd backend
+  pip install -r requirements.txt
+  ```
+
+### Error: `sqlite3.OperationalError: unable to open database file`
+
+**Cause:** The database directory does not exist or has wrong permissions.
+
+**Solution:**
+- Create the data directory:
+  ```bash
+  mkdir -p backend/data
+  ```
+- Ensure the directory is writable:
+  ```bash
+  chmod 755 backend/data
+  ```
+
+### Error: `ollama_service.py` connection refused
+
+**Cause:** Ollama is not running or not accessible.
+
+**Solution:**
+- Ensure Ollama is installed and running: [Ollama Download](https://ollama.com/download)
+- Start Ollama: `ollama serve`
+- Pull a model: `ollama pull llama3.2` (or any model you want to use)
+- Verify connection: `curl http://localhost:11434/api/tags`
+
+---
+
+## 3. Frontend Issues
+
+### Error: `npm: command not found`
+
+**Cause:** Node.js/npm is not installed.
+
+**Solution:**
+- Install Node.js 18+ from [nodejs.org](https://nodejs.org/)
+- Verify with `node --version` and `npm --version`
+
+### Error: `Module not found: Error: Can't resolve '...'`
+
+**Cause:** Missing npm dependencies.
+
+**Solution:**
+- Run `npm install` from the `frontend/` directory:
+  ```bash
+  cd frontend
+  npm install
+  ```
+
+### Error: Blank page / white screen after starting frontend
+
+**Cause:** Backend API is not reachable or CORS issues.
+
+**Solution:**
+- Ensure the backend is running on port 8000.
+- Check the browser console for network errors.
+- If running frontend standalone, update the API URL in `frontend/src/utils/api.js` to point to your backend.
+
+---
+
+## 4. Environment Variables
+
+### Error: Missing `.env` file
+
+**Cause:** Required environment variables are not set.
+
+**Solution:**
+- Copy the example files:
+  ```bash
+  cp .env.example .env
+  cp frontend/.env.example frontend/.env
+  ```
+- Edit the `.env` files with your configuration.
+
+### Common `.env` variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OLLAMA_HOST` | Ollama server URL | `http://localhost:11434` |
+| `DATABASE_URL` | Database connection string | `sqlite:///./data/localmind.db` |
+| `SECRET_KEY` | Flask secret key | (generate one) |
+
+---
+
+## 5. Still Having Issues?
+
+- Check the [GitHub Issues](https://github.com/imDarshanGK/localmind/issues) for similar problems.
+- Open a new issue with:
+  - Your operating system and versions (Docker, Node.js, Python)
+  - The exact error message
+  - Steps you have already tried
+- Join the community discussions if available.