### Quick Start: LocalGPT Docker Setup

Source: https://github.com/promtengineer/localgpt/blob/main/DOCKER_README.md

Provides a step-by-step bash script to quickly set up and run LocalGPT using Docker and Ollama. It includes installing Ollama, pulling models, cloning the repository, and starting the application.

```bash
# 1. Install Ollama locally
curl -fsSL https://ollama.ai/install.sh | sh

# 2. Start Ollama server
ollama serve

# 3. Install required models (in another terminal)
ollama pull qwen3:0.6b
ollama pull qwen3:8b

# 4. Clone and start LocalGPT
git clone https://github.com/your-org/rag-system.git
cd rag-system
./start-docker.sh

# 5. Access the application
open http://localhost:3000
```

--------------------------------

### Setup Python Dependencies for Direct Development

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Clones the repository, creates and activates a Python virtual environment, installs project dependencies from requirements.txt, and verifies the setup of key libraries like PyTorch and Transformers.

```bash
# Clone repository
git clone https://github.com/your-org/rag-system.git
cd rag-system

# Create virtual environment (recommended)
python -m venv venv

# Activate virtual environment
source venv/bin/activate  # macOS/Linux
# venv\Scripts\activate   # Windows

# Install Python dependencies
pip install -r requirements.txt

# Verify Python setup
python -c "import torch; print('✅ PyTorch OK')"
python -c "import transformers; print('✅ Transformers OK')"
python -c "import lancedb; print('✅ LanceDB OK')"
```

--------------------------------

### Configure and Test Ollama

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Starts the Ollama server, pulls necessary AI models (e.g., qwen3:0.6b), lists installed models, and tests a model with a sample prompt. Ollama must remain running.

```bash
# Start Ollama server
ollama serve

# In another terminal, install required models
ollama pull qwen3:0.6b      # Fast model (650MB)
ollama pull qwen3:8b        # High-quality model (4.7GB)

# Verify models are installed
ollama list

# Test Ollama
ollama run qwen3:0.6b "Hello, how are you?"

# API check for Ollama status
curl http://localhost:11434/api/tags
```

--------------------------------

### Install and Run Ollama

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Installs Ollama using a script and then starts the Ollama server. Ollama is required locally for model inference, even when using Docker. It also includes commands to pull specific language models.

```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama (in one terminal)
ollama serve

# Install models (in another terminal)
ollama pull qwen3:0.6b
ollama pull qwen3:8b
```

--------------------------------

### Clone and Start Docker RAG System

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Clones the RAG system repository, navigates into it, checks Ollama status via API, starts the Docker containers using a script, waits for them to initialize, and checks the deployment status.

```bash
# Clone repository
git clone <your-repository-url>
cd rag_system_old

# Verify Ollama is running
curl http://localhost:11434/api/tags

# Start Docker containers
./start-docker.sh

# Wait for containers to start (2-3 minutes)
sleep 120

# Verify deployment
./start-docker.sh status
```

--------------------------------

### Verify Direct Development Installation

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Verifies the installation and running status of the LocalGPT system in direct development mode. It checks system health and tests API endpoints.

```bash
# Check system health
python system_health_check.py

# Test endpoints
curl http://localhost:3000      # Frontend
curl http://localhost:8000/health  # Backend
curl http://localhost:8001/models  # RAG API
```

--------------------------------

### Setup Node.js Dependencies for Direct Development

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Installs Node.js project dependencies using npm and verifies the Node.js and npm versions. This is part of the direct development setup.

```bash
# Install Node.js dependencies
npm install

# Verify Node.js setup
node --version  # Should be 16+
npm --version
npm list --depth=0
```

--------------------------------

### Install Python and Node.js Dependencies

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Installs project dependencies for direct development. This involves using pip for Python packages and npm for Node.js packages.

```bash
# Install Python dependencies
pip install -r requirements.txt

# Install Node.js dependencies  
npm install
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Clones the project repository and changes the current directory to the project root. This is the initial step for both Docker and direct development setups.

```bash
git clone <your-repository-url>
cd rag_system_old
```

--------------------------------

### Start LocalGPT System (Direct Development)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Commands to start the LocalGPT system components when not using Docker. This includes a single command to run all services or individual commands to start the RAG API, backend, and frontend separately.

```bash
# Start all components with one command
python run_system.py

# Or start components manually in separate terminals:
# Terminal 1: RAG API
python -m rag_system.api_server

# Terminal 2: Backend
cd backend && python server.py

# Terminal 3: Frontend
npm run dev
```

--------------------------------

### Start Direct Development RAG System

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Ensures Ollama is running by checking its API, then starts the RAG system components. This can be done with a single command or by running individual component servers in separate terminals.

```bash
# Ensure Ollama is running
curl http://localhost:11434/api/tags

# Start all components with one command
python run_system.py

# Or start components manually in separate terminals:
# Terminal 1: python -m rag_system.api_server
# Terminal 2: cd backend && python server.py  
# Terminal 3: npm run dev
```

--------------------------------

### Start Docker Containers

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Provides commands to start the LocalGPT system using Docker. It includes a convenience script and the direct Docker Compose command for managing containers.

```bash
# Start all containers
./start-docker.sh

# Or manually:
docker compose --env-file docker.env up --build -d
```

--------------------------------

### Direct Development Management Commands

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Commands for managing the LocalGPT system during direct development. This includes starting all services, checking health, and starting individual components.

```bash
# System management
python run_system.py               # Start all services
python system_health_check.py      # Check system health

# Individual components
python -m rag_system.api_server    # RAG API only
cd backend && python server.py     # Backend only
npm run dev                         # Frontend only

# Stop: Press Ctrl+C in terminal running services
```

--------------------------------

### Install Docker on Windows

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Guides users to download and install Docker Desktop, enabling WSL 2 integration, and verifying the installation via PowerShell. This is for the Docker deployment option.

```shell
1. Download Docker Desktop from https://www.docker.com/products/docker-desktop/
2. Run installer and enable WSL 2 integration
3. Restart computer and start Docker Desktop
4. Verify in PowerShell: `docker --version`
```

--------------------------------

### Clone Repository and Verify Docker

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/docker_usage.md

Initial setup involves cloning the project repository and verifying that Docker is installed and accessible on your system.

```bash
git clone <your-repository-url>
cd rag_system_old

docker version
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Sets environment variables for application configuration, including Ollama host, Node environment, and API URLs. Provides examples for both Docker and direct development setups.

```bash
# For Docker (automatic via docker.env):
# OLLAMA_HOST=http://host.docker.internal:11434
# NODE_ENV=production
# RAG_API_URL=http://rag-api:8001
# NEXT_PUBLIC_API_URL=http://localhost:8000

# For Direct Development (set automatically by run_system.py):
# OLLAMA_HOST=http://localhost:11434
# RAG_API_URL=http://localhost:8001
# NEXT_PUBLIC_API_URL=http://localhost:8000
```

--------------------------------

### Install and Configure Ollama

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/docker_usage.md

This section details the steps to install Ollama locally, start its server, pull necessary language models, and verify the connection to the Ollama API.

```bash
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama server (in one terminal)
ollama serve

# Install required models (in another terminal)
ollama pull qwen3:0.6b      # Fast model (650MB)
ollama pull qwen3:8b        # High-quality model (4.7GB)

# Verify models are installed
ollama list

# Test Ollama connection
curl http://localhost:11434/api/tags
```

--------------------------------

### Docker Management Commands

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

A collection of essential commands for managing Docker containers related to the LocalGPT system, including starting, stopping, viewing logs, and checking status.

```bash
# Container management
./start-docker.sh                    # Start all containers
./start-docker.sh stop              # Stop all containers
./start-docker.sh logs              # View logs
./start-docker.sh status            # Check status

# Manual Docker Compose
docker compose ps                    # Check status
docker compose logs -f              # Follow logs
docker compose down                 # Stop containers
docker compose up --build -d        # Rebuild and start
```

--------------------------------

### LocalGPT Docker Management: Start/Stop

Source: https://github.com/promtengineer/localgpt/blob/main/DOCKER_README.md

Bash commands to manage the lifecycle of LocalGPT Docker services. Includes starting, stopping, and restarting all services defined in the Docker Compose setup.

```bash
# Start all services
./start-docker.sh

# Stop all services
./start-docker.sh stop

# Restart services
./start-docker.sh stop && ./start-docker.sh
```

--------------------------------

### Install Docker on Ubuntu/Debian

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Installs Docker and Docker Compose using convenience scripts and apt-get, then adds the user to the docker group for non-sudo access. Verifies installation.

```bash
# Update system
sudo apt-get update

# Install Docker using convenience script
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Add user to docker group
sudo usermod -aG docker $USER
newgrp docker

# Install Docker Compose V2
sudo apt-get install docker-compose-plugin

# Verify installation
docker --version
docker compose version
```

--------------------------------

### Install and Test Additional Models

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Shows how to install alternative embedding and generation models using Ollama and tests switching between models by making a chat request.

```bash
# Install additional models (optional)
ollama pull nomic-embed-text        # Alternative embedding model
ollama pull llama3.1:8b            # Alternative generation model

# Test model switching
curl -X POST http://localhost:8001/chat \
  -H "Content-Type: application/json" \
  -d '{"query": "Hello", "model": "qwen3:8b"}'
```

--------------------------------

### Install Ollama on macOS/Linux

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Installs Ollama using a convenience script and verifies the installation by checking the version. This is a prerequisite for both Docker and direct development setups.

```bash
curl -fsSL https://ollama.ai/install.sh | sh

# Verify installation
ollama --version
```

--------------------------------

### Clone and Set Up Repository

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Clones the project repository, navigates into the directory, lists contents, creates necessary directories for data storage and logs, and sets appropriate file permissions.

```bash
# Clone repository
git clone https://github.com/your-org/rag-system.git
cd rag-system

# Check repository structure
ls -la

# Create required directories
mkdir -p lancedb index_store shared_uploads logs backend
touch backend/chat_data.db

# Set permissions
chmod -R 755 lancedb index_store shared_uploads
chmod 664 backend/chat_data.db
```

--------------------------------

### Install Docker (Ubuntu/Debian)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Installs Docker Engine and Docker Compose plugin on Ubuntu/Debian systems. It downloads the Docker installation script, runs it, adds the user to the docker group, and installs the compose plugin.

```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker

sudo apt-get update
sudo apt-get install docker-compose-plugin
```

--------------------------------

### Start and Manage System Operations

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Python scripts for initiating and monitoring the overall system, including starting the main process and checking its health status.

```python
# Start system
python run_system.py

# Check system health
python system_health_check.py
```

--------------------------------

### Start Individual Components

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Commands to start specific components of the LocalGPT system independently, such as the RAG API, backend server, and frontend development server.

```bash
# Start components individually
python -m rag_system.api_server    # RAG API on port 8001
cd backend && python server.py     # Backend on port 8000
npm run dev                         # Frontend on port 3000
```

--------------------------------

### Install Ollama (Shell)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Installs Ollama, a tool for running large language models locally. This command downloads and executes the official installation script.

```bash
curl -fsSL https://ollama.ai/install.sh | sh
```

--------------------------------

### Launch System (Direct Development)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Starts the RAG system components when developing directly. It offers an integrated launcher script or manual startup of individual services.

```bash
# Option A: Integrated Launcher (Recommended)
python run_system.py

# Option B: Manual Component Startup
# Terminal 1: RAG API
python -m rag_system.api_server

# Terminal 2: Backend
cd backend && python server.py

# Terminal 3: Frontend
npm run dev

# Access at http://localhost:3000
```

--------------------------------

### Troubleshoot Docker Daemon and Cache

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Guides on checking if the Docker daemon is running, restarting Docker Desktop or service, and clearing Docker cache to resolve build failures.

```bash
# Docker daemon not running
docker version

# Restart Docker Desktop (macOS/Windows)
# Or restart docker service (Linux)
sudo systemctl restart docker

# Clear Docker cache if build fails
docker system prune -f
```

--------------------------------

### Verify LocalGPT Setup and Run

Source: https://github.com/promtengineer/localgpt/blob/main/CONTRIBUTING.md

Provides commands to verify the development environment setup and start the LocalGPT system in development mode. These commands ensure all components are functioning correctly before making changes.

```bash
# Run health check
python system_health_check.py

# Start development system
python run_system.py --mode dev
```

--------------------------------

### Install Docker on macOS

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Installs Docker Desktop using Homebrew or a direct download and verifies the installation. This is required for the Docker deployment option.

```bash
# Install Docker Desktop via Homebrew
brew install --cask docker

# Or download from: https://www.docker.com/products/docker-desktop/
# Start Docker Desktop from Applications

# Verify installation
docker --version
docker compose version
```

--------------------------------

### Troubleshooting Docker Issues

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Provides commands and steps to troubleshoot common issues encountered with Docker deployments, such as checking the Docker daemon status, identifying port conflicts, and restarting services.

```bash
# Check Docker daemon
docker version

# Check what's using ports
lsof -i :3000 -i :8000 -i :8001

# Restart Docker Desktop and try again
./start-docker.sh
```

--------------------------------

### Troubleshooting Direct Development Issues

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Offers solutions for common problems in direct development, including checking Python and Node.js versions, and reinstalling dependencies to resolve import or runtime errors.

```bash
# Check Python installation
python --version  # Should be 3.8+

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall

# Check Node version
node --version    # Should be 16+

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### Initial Setup and Permissions

Source: https://github.com/promtengineer/localgpt/blob/main/DOCKER_TROUBLESHOOTING.md

Commands to create necessary directories, set file permissions, and ensure correct ownership for the LocalGPT project's data and configuration files.

```bash
# Create directories if they don't exist
mkdir -p lancedb index_store shared_uploads backend

# Fix permissions
chmod -R 755 lancedb index_store shared_uploads
chmod 664 backend/chat_data.db

# Check ownership
ls -la lancedb/ shared_uploads/ backend/

# Reset permissions if needed
sudo chown -R $USER:$USER lancedb shared_uploads backend
```

--------------------------------

### Install Python Dependencies (Shell)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Installs Python dependencies for direct development. It involves cloning the repository, creating a virtual environment, and installing packages from requirements.txt.

```bash
# Clone repository (if not already done)
git clone https://github.com/your-org/rag-system.git
cd rag-system

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install Python packages
pip install -r requirements.txt
```

--------------------------------

### Troubleshoot Ollama Connectivity and Models

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Provides commands to check Ollama API responsiveness, restart the Ollama service if it fails, and reinstall models if necessary.

```bash
# Ollama not responding
curl http://localhost:11434/api/tags

# If fails, restart Ollama
pkill ollama
ollama serve

# Reinstall models if needed
ollama pull qwen3:0.6b
ollama pull qwen3:8b
```

--------------------------------

### Install Docker (macOS)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Installs Docker Desktop on macOS using Homebrew. This command installs the Docker application, which includes Docker Engine and Docker Compose.

```bash
brew install --cask docker
```

--------------------------------

### Launch Docker System (Shell)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Starts all Docker containers for the RAG system. It can be done using a convenience script or directly with Docker Compose.

```bash
# Using convenience script
./start-docker.sh

# Or manually with Docker Compose
docker compose --env-file docker.env up --build -d
```

--------------------------------

### Test RAG System Initialization and Embedding

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Tests the initialization of the RAG system by retrieving an agent instance and verifies embedding generation by creating an embedding for a sample text.

```python
from rag_system.main import get_agent
agent = get_agent('default')
print('✅ RAG System initialized successfully')
```

```python
from rag_system.main import get_agent
agent = get_agent('default')
embedder = agent.retrieval_pipeline._get_text_embedder()
test_emb = embedder.create_embeddings(['Hello world'])
print(f'✅ Embedding generated: {test_emb.shape}')
```

--------------------------------

### LocalGPT API Endpoints

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Documentation for key API endpoints used to interact with the LocalGPT system. This includes endpoints for checking backend health and retrieving model information.

```APIDOC
API Endpoints:

GET /health
  Description: Checks the health status of the backend service.
  Returns: A JSON object indicating the health status (e.g., {"status": "ok"}).

GET /models
  Description: Retrieves a list of available models supported by the RAG API.
  Returns: A JSON object containing an array of model names and their details.
```

--------------------------------

### Create Backup Script (Bash)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Creates a shell script to automate backups of critical data. Copies databases, indexes, and uploads to a timestamped directory.

```bash
# Create backup script
cat > backup_system.sh << 'EOF'
#!/bin/bash
BACKUP_DIR="backups/$(date +%Y%m%d_%H%M%S)"
mkdir -p "$BACKUP_DIR"

# Backup databases and indexes
cp -r backend/chat_data.db "$BACKUP_DIR/"
cp -r lancedb "$BACKUP_DIR/"
cp -r index_store "$BACKUP_DIR/"
cp -r shared_uploads "$BACKUP_DIR/"

echo "Backup completed: $BACKUP_DIR"
EOF

chmod +x backup_system.sh
```

--------------------------------

### Troubleshoot Python Dependencies and Environment

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Checks Python version, verifies the active virtual environment, and provides commands to reinstall project dependencies with force-reinstall option.

```bash
# Check Python version
python --version  # Should be 3.8+

# Check virtual environment
which python
pip list | grep torch

# Reinstall dependencies
pip install -r requirements.txt --force-reinstall
```

--------------------------------

### Initialize SQLite Database

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Initializes the SQLite database by creating the necessary tables and schema using a Python script. Verifies initialization by listing the tables in the database file.

```python
from backend.database import ChatDatabase
db = ChatDatabase()
db.init_database()
print('✅ Database initialized')
```

```bash
sqlite3 backend/chat_data.db ".tables"
```

--------------------------------

### Verify Docker Deployment

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Checks the status of running Docker containers and tests the accessibility of the system's frontend, backend, and RAG API endpoints using curl.

```bash
# Check container status
docker compose ps

# Test endpoints
curl http://localhost:3000      # Frontend
curl http://localhost:8000/health  # Backend  
curl http://localhost:8001/models  # RAG API
```

--------------------------------

### Docker Environment Variables

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Example environment variables for Docker configuration, including Ollama host settings and service URLs for the RAG API and frontend.

```bash
# Ollama Configuration
OLLAMA_HOST=http://host.docker.internal:11434

# Service Configuration
NODE_ENV=production
RAG_API_URL=http://rag-api:8001
NEXT_PUBLIC_API_URL=http://localhost:8000
```

--------------------------------

### Ollama API Endpoints

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Demonstrates common API interactions with Ollama, including checking available models and running inference. These are useful for verifying Ollama's status and functionality.

```APIDOC
GET /api/tags
  Description: List all models available on Ollama.
  Example:
    curl http://localhost:11434/api/tags

POST /api/generate
  Description: Run inference with a specific model.
  Request Body:
    model: string (e.g., "qwen3:0.6b")
    prompt: string (e.g., "What is RAG?")
    stream: boolean (optional, default: true)
  Example:
    curl http://localhost:11434/api/generate -d '{"model": "qwen3:0.6b", "prompt": "What is RAG?", "stream": false}'
```

--------------------------------

### Contributor Quick Start

Source: https://github.com/promtengineer/localgpt/blob/main/README.md

A set of bash commands to quickly set up a development environment for contributors. This includes cloning the repository, installing dependencies, setting up models, and verifying the system.

```bash
# Fork and clone the repository
git clone https://github.com/PromtEngineer/localGPT.git
cd localGPT

# Set up development environment
pip install -r requirements.txt
npm install

# Install Ollama and models
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull qwen3:0.6b qwen3:8b

# Verify setup
python system_health_check.py
python run_system.py --mode dev
```

--------------------------------

### Functional Testing: Document Upload

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Describes the manual steps for testing document upload functionality through the web interface, including creating an index, uploading a PDF, and testing chat.

```markdown
1. Access http://localhost:3000
2. Click "Create New Index"
3. Upload a PDF document
4. Configure settings and build index
5. Test chat functionality
```

--------------------------------

### Troubleshoot Node.js Environment

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Checks the Node.js version and provides commands to clear the `node_modules` and `package-lock.json` files and reinstall dependencies.

```bash
# Check Node version
node --version  # Should be 16+

# Clear and reinstall
rm -rf node_modules package-lock.json
npm install
```

--------------------------------

### Integration Testing Workflow

Source: https://github.com/promtengineer/localgpt/blob/main/DOCKER_TROUBLESHOOTING.md

Steps to start the full LocalGPT system, wait for services, and test basic API endpoints for integration validation.

```bash
# Full system test
./start-docker.sh

# Wait for all services to be ready
sleep 60

# Test complete workflow
curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Session"}'

# Test document upload (if you have a test PDF)
# curl -X POST http://localhost:8000/upload -F "file=@test.pdf"

# Clean up
./start-docker.sh stop
```

--------------------------------

### Reinstall Ollama Models (bash)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Downloads specific Ollama models, such as 'qwen3:0.6b' and 'qwen3:8b'. This is useful for ensuring you have the correct model versions or after a fresh Ollama installation.

```bash
ollama pull qwen3:0.6b
ollama pull qwen3:8b
```

--------------------------------

### Key Project Files Overview

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Lists essential files and directories within the LocalGPT project structure, including deployment scripts, launchers, health checks, dependency files, and documentation folders.

```bash
rag-system/
├── 🐳 start-docker.sh           # Docker deployment script
├── 🏃 run_system.py             # Direct development launcher
├── 🩺 system_health_check.py    # System verification
├── 📋 requirements.txt          # Python dependencies
├── 📦 package.json              # Node.js dependencies
├── 📁 Documentation/            # Complete documentation
└── 📁 rag_system/              # Core system code
```

--------------------------------

### Troubleshoot Ollama Connectivity

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Check if Ollama is running by querying its API and restart it if necessary. This involves using curl to hit the /api/tags endpoint and pkill/ollama serve for restarting.

```bash
# Check if Ollama is running
curl http://localhost:11434/api/tags

# Restart Ollama
pkill ollama
ollama serve
```

--------------------------------

### Manage Docker Containers with Convenience Script

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/docker_usage.md

Utilize the provided `./start-docker.sh` script for simplified management of Docker containers, including starting, stopping, viewing logs, and checking status.

```bash
# Start all containers
./start-docker.sh

# Stop all containers
./start-docker.sh stop

# View logs
./start-docker.sh logs

# Check status
./start-docker.sh status

# Restart containers
./start-docker.sh stop
./start-docker.sh
```

--------------------------------

### LocalGPT Docker Management: Manual Compose

Source: https://github.com/promtengineer/localgpt/blob/main/DOCKER_README.md

Direct Docker Compose commands for managing LocalGPT services, offering more granular control. Includes starting, stopping, and rebuilding specific services.

```bash
# Start manually
docker compose --env-file docker.env up --build -d

# Stop manually
docker compose down

# Rebuild specific service
docker compose build --no-cache rag-api
docker compose up -d rag-api
```

--------------------------------

### Manage Individual Docker Compose Services

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/docker_usage.md

Control specific services within the Docker Compose setup, allowing for targeted starting, restarting, stopping, and log viewing.

```bash
# Start specific service
docker compose up -d frontend
docker compose up -d backend
docker compose up -d rag-api

# Restart specific service
docker compose restart rag-api

# Stop specific service
docker compose stop backend

# View specific service logs
docker compose logs -f rag-api
```

--------------------------------

### Verify Direct Development Installation (API)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Checks the health and status of the RAG system after direct development setup. This command executes a Python script designed for system verification.

```APIDOC
Check system health:
python system_health_check.py
```

--------------------------------

### Simple Index Creation Script Usage

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Utilize the simple bash script for quick document indexing. It supports single or multiple files, including wildcards, and handles common document types like PDF, TXT, DOCX, and MD.

```bash
# Basic usage
./simple_create_index.sh "Index Name" "document.pdf"

# Multiple documents
./simple_create_index.sh "Research Papers" "paper1.pdf" "paper2.pdf" "notes.txt"

# Using wildcards
./simple_create_index.sh "Invoice Collection" ./invoices/*.pdf

# Supported file types: PDF, TXT, DOCX, MD
```

--------------------------------

### Clone Repository (Shell)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Clones the RAG system repository from GitHub and navigates into the project directory. This is the first step for both deployment methods.

```bash
git clone https://github.com/your-org/rag-system.git
cd rag-system
```

--------------------------------

### Development Tools and Package Management

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Essential commands for development workflows, including building the frontend for production and updating Python dependencies.

```bash
# Development tools
npm run build                       # Build frontend for production
pip install -r requirements.txt --upgrade  # Update Python packages
```

--------------------------------

### Install and Start Ollama

Source: https://github.com/promtengineer/localgpt/blob/main/README.md

Installs Ollama, a tool for running large language models locally, and pulls specific AI models (qwen3:0.6b, qwen3:8b). It then starts the Ollama server, which is a core dependency for LocalGPT's AI capabilities.

```shell
# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull recommended models
ollama pull qwen3:0.6b          # Fast generation model
ollama pull qwen3:8b            # High-quality generation model

# Start Ollama server
ollama serve
```

--------------------------------

### Install and Manage Ollama

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/docker_usage.md

Commands for installing Ollama, pulling and managing AI models, and checking its status. Includes methods for both direct installation and within Docker environments.

```bash
# Install Ollama (one-time setup)
curl -fsSL https://ollama.ai/install.sh | sh

# Start Ollama server
ollama serve

# Check Ollama status (CLI)
curl http://localhost:11434/api/tags

# Check Ollama status from container
docker compose exec rag-api curl http://host.docker.internal:11434/api/tags

# Test Ollama connection
curl -X POST http://localhost:11434/api/generate \
  -H "Content-Type: application/json" \
  -d '{"model": "qwen3:0.6b", "prompt": "Hello", "stream": false}'

# Monitor Ollama logs (if running with logs)
# Ollama logs appear in the terminal where you ran 'ollama serve'

# Restart Ollama
pkill ollama
ollama serve

# Check Ollama is running (for troubleshooting)
curl http://localhost:11434/api/tags
```

```bash
# Install models
ollama pull qwen3:0.6b      # Fast model
ollama pull qwen3:8b        # High-quality model

# List installed models
ollama list

# Update models
ollama pull qwen3:0.6b
ollama pull qwen3:8b

# Remove unused models
ollama rm old-model-name

# Check model information
ollama show qwen3:0.6b
```

--------------------------------

### Install Node.js Dependencies (Shell)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Installs Node.js dependencies for the project, typically for frontend or backend services managed by Node.js. This command uses npm to install packages listed in package.json.

```bash
npm install
```

--------------------------------

### Pre-commit Hooks Setup (Bash)

Source: https://github.com/promtengineer/localgpt/blob/main/CONTRIBUTING.md

Provides commands to install and set up pre-commit hooks for automated code quality checks before committing. Includes steps for installation and manual execution.

```bash
# Install pre-commit
pip install pre-commit

# Set up hooks
pre-commit install

# Run manually
pre-commit run --all-files
```

--------------------------------

### Backend API Endpoints

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Defines the API endpoints for the backend service, including methods for session management and health checks.

```APIDOC
POST /sessions
  Description: Creates a new chat session.
  Request Body:
    Content-Type: application/json
    Schema:
      type: object
      properties:
        title: { type: string, description: "The title for the new session" }
      required:
        - title
  Responses:
    201 Created: Session created successfully.

GET /health
  Description: Checks the health status of the backend service.
  Responses:
    200 OK: Service is healthy.
```

--------------------------------

### Clone LocalGPT Repository

Source: https://github.com/promtengineer/localgpt/blob/main/README.md

Clones the specified branch of the LocalGPT repository from GitHub and navigates into the project directory. This is a foundational step for installation and setup.

```bash
git clone -b localgpt-v2 https://github.com/PromtEngineer/localGPT.git
cd localGPT
```

--------------------------------

### Direct Development Architecture Diagram

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Mermaid syntax for visualizing the direct development architecture, illustrating the local processes for Frontend, Backend, RAG API, and Ollama Server.

```mermaid
graph TB
    subgraph "Local Processes"
        Frontend[Next.js Dev Server<br/>Port 3000]
        Backend[Python Backend<br/>Port 8000]
        RAG[RAG API<br/>Port 8001]
        Ollama[Ollama Server<br/>Port 11434]
    end
    
    Frontend --> Backend
    Backend --> RAG
    RAG --> Ollama
```

--------------------------------

### Set File Permissions (Bash)

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Sets specific file and directory permissions for security. Restricts access to the SQLite database and the Lancedb vector store.

```bash
# Set proper file permissions
chmod 600 backend/chat_data.db    # Restrict database access
chmod 700 lancedb/                # Restrict vector DB access
```

--------------------------------

### API Testing: Sessions, Models, and Health

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Demonstrates API testing using curl to create a new session, retrieve available models, and check the health status of backend and RAG API services.

```bash
# Test session creation
curl -X POST http://localhost:8000/sessions \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Session"}'

# Test models endpoint
curl http://localhost:8001/models

# Test health endpoints
curl http://localhost:8000/health
curl http://localhost:8001/health
```

--------------------------------

### View Python Packages

Source: https://github.com/promtengineer/localgpt/blob/main/DOCKER_README.md

Lists installed Python packages within the 'rag-api' container, filtering for specific libraries like torch, transformers, and lancedb.

```bash
docker compose exec rag-api pip list | grep -E "(torch|transformers|lancedb)"
```

--------------------------------

### RAG API Endpoints

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Defines the API endpoints for the RAG service, including methods for retrieving model information, checking health, and handling chat requests.

```APIDOC
GET /models
  Description: Retrieves a list of available models.
  Responses:
    200 OK: List of models.

GET /health
  Description: Checks the health status of the RAG API service.
  Responses:
    200 OK: Service is healthy.

POST /chat
  Description: Sends a query to the chat model.
  Request Body:
    Content-Type: application/json
    Schema:
      type: object
      properties:
        query: { type: string, description: "The user's query" }
        model: { type: string, description: "The model to use for generation (e.g., qwen3:8b)" }
  Responses:
    200 OK: Chat response.
```

--------------------------------

### Test Direct Development RAG System

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/installation_guide.md

Executes a Python script to check the overall health and status of the RAG system components when set up for direct development.

```python
# Check system health
python system_health_check.py
```

--------------------------------

### Install Ollama

Source: https://github.com/promtengineer/localgpt/blob/main/backend/README.md

Instructions to install Ollama, a tool for running large language models locally. This script downloads and executes the Ollama installation script.

```Bash
# Visit https://ollama.ai or run:
curl -fsSL https://ollama.ai/install.sh | sh
```

--------------------------------

### Performance Monitoring Tools

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/deployment_guide.md

Commands for monitoring system performance, including Docker container statistics and general system resource usage for direct development.

```bash
# Docker monitoring
docker stats

# Direct development monitoring
htop           # Overall system
nvidia-smi     # GPU usage (if available)
```

--------------------------------

### Comprehensive System Verification Checks

Source: https://github.com/promtengineer/localgpt/blob/main/Documentation/quick_start.md

Perform a full system health check by verifying connectivity to frontend, backend, RAG API, and Ollama services. This includes checking Docker container status if applicable.

```bash
# Check all endpoints
curl -f http://localhost:3000 && echo "✅ Frontend OK"
curl -f http://localhost:8000/health && echo "✅ Backend OK"  
curl -f http://localhost:8001/models && echo "✅ RAG API OK"
curl -f http://localhost:11434/api/tags && echo "✅ Ollama OK"

# For Docker: Check containers
docker compose ps
```

--------------------------------

### Run Minimal Docker (RAG API Only)

Source: https://github.com/promtengineer/localgpt/blob/main/DOCKER_TROUBLESHOOTING.md

Builds a Docker image for the RAG API, runs it on a specified port, and starts other components (backend, frontend) directly.

```bash
docker build -f Dockerfile.rag-api -t rag-api .
docker run -p 8001:8001 rag-api
cd backend && python server.py &
npm run dev
```