GitHub - 2dogsandanerd/Knowledge-Base-Self-Hosting-Kit: A Docker-powered RAG system that understands the difference between code and prose. Ingest your codebase and documentation, then query them with full privacy and zero configuration.

# 1. Clone the repository
git clone https://github.com/yourusername/self-hosting-kit.git
cd self-hosting-kit

# 2. Configure & Start
# Run the interactive setup script to set your document folder
./setup.sh

# (Alternative) Manual setup:
# cp .env.example .env
# docker compose up -d

# 4. Check health
curl http://localhost:8080/health
# Expected: {"status":"healthy","chromadb":"connected","collections_count":0}

# 5. Open the application
open http://localhost:8080

curl -X POST http://localhost:8080/api/v1/rag/collections \
  -F "collection_name=my_docs" \
  -F "embedding_provider=ollama" \
  -F "embedding_model=nomic-embed-text"

curl -X POST http://localhost:8080/api/v1/rag/documents/upload \
  -F "files=@document.pdf" \
  -F "collection_name=my_docs" \
  -F "chunk_size=512" \
  -F "chunk_overlap=128"

curl -X POST http://localhost:8080/api/v1/rag/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What is this document about?",
    "collection": "my_docs",
    "k": 5
  }'

import requests

BASE_URL = "http://localhost:8080/api/v1/rag"

# 1. Create a collection
response = requests.post(
    f"{BASE_URL}/collections",
    files={
        "collection_name": (None, "my_knowledge"),
        "embedding_provider": (None, "ollama"),
        "embedding_model": (None, "nomic-embed-text")
    }
)
print(f"Collection created: {response.json()}")

# 2. Upload documents
with open("document.pdf", "rb") as f:
    response = requests.post(
        f"{BASE_URL}/documents/upload",
        files={"files": f},
        data={
            "collection_name": "my_knowledge",
            "chunk_size": 512,
            "chunk_overlap": 128
        }
    )
print(f"Upload status: {response.json()}")

# 3. Query the knowledge base
response = requests.post(
    f"{BASE_URL}/query",
    json={
        "query": "What are the main topics?",
        "collection": "my_knowledge",
        "k": 5
    }
)
result = response.json()
print(f"Answer: {result.get('answer')}")
print(f"Sources: {len(result.get('sources', []))}")

import requests
import time

BASE_URL = "http://localhost:8080/api/v1/rag"

# Start folder ingestion
response = requests.post(
    f"{BASE_URL}/ingest-folder",
    json={
        "folder_path": "/host_root/path/to/your/docs",
        "collection_name": "my_docs",
        "profile": "documents",
        "recursive": True
    }
)

task_id = response.json()["task_id"]
print(f"Ingestion started: {task_id}")

# Poll for status
while True:
    status = requests.get(f"{BASE_URL}/ingest-status/{task_id}").json()

    if status["status"] == "completed":
        print(f"✅ Processed {status['processed_files']} files")
        break
    elif status["status"] == "failed":
        print(f"❌ Failed: {status['error']}")
        break
    else:
        print(f"⏳ Processing: {status.get('current_file')} ({status.get('processed')}/{status.get('total')})")
        time.sleep(2)

# Health check
curl http://localhost:8080/health

# List collections
curl http://localhost:8080/api/v1/rag/collections

# Get collection stats
curl http://localhost:8080/api/v1/rag/collections/my_docs/stats

# Query with specific parameters
curl -X POST http://localhost:8080/api/v1/rag/query \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Explain the architecture",
    "collection": "my_docs",
    "k": 10,
    "similarity_threshold": 0.5
  }'

# Delete a collection
curl -X DELETE http://localhost:8080/api/v1/rag/collections/my_docs

const BASE_URL = "http://localhost:8080/api/v1/rag";

async function queryKnowledgeBase(question, collection = "my_docs") {
  const response = await fetch(`${BASE_URL}/query`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      query: question,
      collection: collection,
      k: 5
    })
  });

  const result = await response.json();
  return {
    answer: result.answer,
    sources: result.sources
  };
}

// Usage
const result = await queryKnowledgeBase("What is RAG?");
console.log(result.answer);

┌─────────────────────────────────────────────────┐
│             FastAPI Backend (Port 8081)         │
│  ┌──────────────┐  ┌─────────────────────────┐ │
│  │ RAG API      │  │ Lifespan Management     │ │
│  │ - Query      │  │ - ChromaDB Connection   │ │
│  │ - Upload     │  │ - Singleton Patterns    │ │
│  │ - Collections│  │ - Circuit Breaker       │ │
│  └──────┬───────┘  └────────────┬────────────┘ │
└─────────┼──────────────────────┼───────────────┘
          │                      │
          ↓                      ↓
┌─────────────────┐    ┌──────────────────────┐
│  ChromaDB       │    │  Ollama / LLM        │
│  Vector Storage │    │  Embeddings & Chat   │
│  (Port 8001)    │    │  (Port 11434)        │
└─────────────────┘    └──────────────────────┘

environment:
  - LLM_PROVIDER=openai
  - OPENAI_API_KEY=sk-...
  - EMBEDDING_PROVIDER=openai

.
├── backend/
│   ├── src/
│   │   ├── api/v1/rag/         # RAG endpoints
│   │   │   ├── collections.py  # Collection CRUD
│   │   │   ├── documents/      # Upload, management
│   │   │   ├── query.py        # RAG queries
│   │   │   ├── ingestion/      # Folder scanning, batch processing
│   │   │   └── cockpit.py      # System status
│   │   ├── core/
│   │   │   ├── chroma_manager.py      # ChromaDB singleton
│   │   │   ├── docling_loader.py      # Document parser
│   │   │   ├── query_engine.py        # Query execution
│   │   │   ├── retrievers/            # Hybrid, BM25, reranker
│   │   │   ├── config.py              # Multi-LLM config
│   │   │   └── feature_limits.py      # Edition tiers
│   │   └── services/
│   │       ├── docling_service.py     # Central doc processing
│   │       ├── classification.py      # Doc classification
│   │       └── generators/            # Summaries, configs
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/
│   └── index.html              # Zero-build dashboard (Vanilla JS)
├── docker-compose.yml          # Full stack orchestration
├── CLAUDE.md                   # Development guide
└── README.md

cd backend
pip install -r requirements.txt
uvicorn src.main:app --host 0.0.0.0 --port 8080 --reload

# Edit code in backend/src/
# Changes reflect immediately, no rebuild needed

# View logs
docker compose logs -f backend

# Restart if needed
docker compose restart backend

docker compose down
docker compose up -d --build

# Check all services
docker compose ps

# View backend logs
docker compose logs backend

# Check ChromaDB connection
docker compose logs chromadb

# Ensure Ollama is running
ollama serve

# Pull embedding model
ollama pull nomic-embed-text

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

# Check ChromaDB service
docker compose logs chromadb

# Restart ChromaDB
docker compose restart chromadb

# Restart backend to reload modules
docker compose restart backend

@software{validated_table_extractor,
  title = {Validated Table Extractor: Audit-Ready PDF Table Extraction},
  author = {2dogsandanerd},
  year = {2025},
  url = {https://github.com/2dogsandanerd/validated-table-extractor}
}