Kotaemon

Expanded Installation Guide for Ubuntu 24.04 — Docker Deployment

Introduction

Kotaemon is a clean open-source RAG interface for chatting with your documents. It supports local + cloud LLMs (OpenAI, Azure, Ollama, Groq), hybrid full-text + vector retrieval with re-ranking, and multi-modal QA with figures, tables, and OCR. It offers multi-user login, private/public collections, advanced citations with an in-browser PDF viewer, and agent-based reasoning.

Prerequisites

Resource	Minimum
CPU	2 cores
RAM	4 GB (8+ GB for local LLM)
Disk	10 GB free
Docker	Engine 24.0+
Network	Port 7860 open

Install Docker Engine

sudo apt-get update
sudo apt-get install -y ca-certificates curl gnupg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo systemctl enable docker && sudo systemctl start docker
sudo usermod -aG docker $USER
newgrp docker

Docker Compose

mkdir -p ~/kotaemon && cd ~/kotaemon
cat <<'EOF' > docker-compose.yml
services:
  kotaemon:
    image: ghcr.io/cinnamon/kotaemon:main-lite
    container_name: kotaemon
    restart: unless-stopped
    ports:
      - "7860:7860"
    volumes:
      - ./ktem_app_data:/app/ktem_app_data
    environment:
      - GRADIO_SERVER_NAME=0.0.0.0
      - GRADIO_SERVER_PORT=7860
EOF
docker compose up -d

Image variants: :main-lite (PDF/HTML/XLSX), :main-full (+DOCX/CSV), :main-ollama (+bundled Ollama). Default login: admin/admin. Visit http://YOUR_IP:7860.

Nginx Reverse Proxy

sudo apt-get install -y nginx certbot python3-certbot-nginx
sudo tee /etc/nginx/sites-available/kotaemon <<'EOF'
server {
    listen 80;
    server_name kotaemon.yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:7860;
        proxy_set_header Host $host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 300s;
    }
}
EOF
sudo ln -s /etc/nginx/sites-available/kotaemon /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
sudo certbot --nginx -d kotaemon.yourdomain.com

Environment Variables

Variable	Purpose	Example
GRADIO_SERVER_NAME	Bind address	0.0.0.0
GRADIO_SERVER_PORT	Web UI port	7860
DEFAULT_LLM	Default chat model	gpt-4o
OLLAMA_BASE_URL	Ollama endpoint	http://host.docker.internal:11434
EMBEDDING_MODEL	Embedding model	nomic-embed-text
CHUNK_SIZE	Chunk size (chars)	1024
RETRIEVER_TOP_K	Chunks per query	5

# Add to docker-compose.yml under environment:
  - DEFAULT_LLM=gpt-4o
  - OLLAMA_BASE_URL=http://host.docker.internal:11434
  - EMBEDDING_MODEL=nomic-embed-text
  - CHUNK_SIZE=1024
  - RETRIEVER_TOP_K=5
docker compose down && docker compose up -d

RAG Configuration

Connect local Ollama: Settings → LLMs and Embeddings → select Ollama provider, set API Base URL to http://host.docker.internal:11434. Choose a chat model (e.g. llama3.1:8b). Under Embeddings, select Ollama Embeddings, enter nomic-embed-text (pull first: ollama pull nomic-embed-text). Save and Set as Default.

Document Upload

Files tab → drag-and-drop or click to upload. Organize into collections.

Format	Lite	Full
PDF	Yes	Yes
DOCX/DOC	No	Yes
HTML/MHTML	Yes	Yes
XLSX	Yes	Yes
CSV	No	Yes

Backup & Update

# Backup
docker compose stop
tar czf ~/kotaemon-backup-$(date +%Y%m%d).tar.gz -C ~/kotaemon ktem_app_data
docker compose start

# Restore
docker compose down && rm -rf ~/kotaemon/ktem_app_data
tar xzf ~/kotaemon-backup-20260728.tar.gz -C ~/kotaemon
docker compose up -d

# Update
cd ~/kotaemon && docker compose pull && docker compose up -d
docker image prune -f

Troubleshooting

Ollama connection failed: Check Ollama is running (docker ps | grep ollama). Test: docker exec kotaemon curl -s http://host.docker.internal:11434/api/tags. Verify OLLAMA_BASE_URL.

Embedding not found: Run ollama pull nomic-embed-text. Verify name is case-sensitive in Settings. Re-save and set as default.

Document parsing errors: Use :main-full for DOCX/CSV. For scanned PDFs, enable PaddleOCR or Azure Document Intelligence in Settings.

Slow retrieval on large docs: Increase CHUNK_SIZE to 2048, lower RETRIEVER_TOP_K to 3, or use GPU for embeddings.

---

GitHub · Docs · RunThis AI