CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

OhnePapier ("Without Paper") is a fully local, privacy-first document management stack. It is a Docker Compose orchestration project — there is no source code to compile or test. The goal is zero cloud dependencies.

Part of the Crumbforest ecosystem (crumbforest.io / crumbforest.org). All documentation is in German.

Stack

Service Image Purpose
webserver paperless-ngx OCR, document storage, web UI (:8000)
db PostgreSQL 18 Primary database (:5432)
redis Redis 8 Message broker/cache (:6379)
paperless-ai paperless-ai AI analysis/tagging layer (:3000)
Ollama host (not containerized) Local LLM inference (:11434)

Ollama runs on the host machine, not inside Docker, to use GPU. Containers reach it via host.docker.internal:11434.

Commands

# Start stack
docker compose up -d

# Tail logs
docker compose logs -f [webserver|paperless-ai|db|redis]

# Generate Paperless API token (needed for paperless-ai config)
docker exec paperless-webserver-1 python3 manage.py shell -c "
from rest_framework.authtoken.models import Token
from django.contrib.auth.models import User
user = User.objects.first()
token, _ = Token.objects.get_or_create(user=user)
print(f'Token: {token.key}')
"

# Access Django shell
docker exec -it paperless-webserver-1 python3 manage.py shell

Data Flow

Upload/Scan → Paperless-ngx (OCR + storage)
                    ↓ (REST API, every 30 min)
              paperless-ai (Node.js)
                    ↓
              Ollama/llama3.2 (local LLM)
                    ↓
              Auto-generates: title, tags, correspondent, document type, date
                    ↓ (writes back via API)
              Paperless-ngx (updated metadata)
                    ↓
              ChromaDB/RAGZ (vector embeddings via SentenceTransformer)

Fresh Install Pre-flight

Services on :8000 and :3000 can appear healthy while the connection chain is silently broken. Check these before docker compose up:

  1. docker-compose.env exists — not in git, must be created manually with ADMIN_USER, ADMIN_PASSWORD, SECRET_KEY, etc.
  2. Ollama is running on the host — it is NOT inside Docker. Start it with ollama serve before bringing up the stack.
  3. network_mode: bridge is NOT set on paperless-ai — it breaks host.docker.internal access to Ollama.

Only after these three pass: start the stack, generate the API token, then configure paperless-ai.

Configuration

paperless-ai environment (set inside its container config):

PAPERLESS_API_URL=http://webserver:8000/api   # Must end with /api
PAPERLESS_URL=http://webserver:8000           # Must NOT have /api
PAPERLESS_API_TOKEN=<generated-token>
AI_PROVIDER=ollama
OLLAMA_API_URL=http://host.docker.internal:11434
OLLAMA_MODEL=llama3.2
SCAN_INTERVAL=*/30 * * * *

Project Status (v0.0)

  • ✅ Paperless-ngx + PostgreSQL + Redis running
  • ✅ Ollama (llama3.2 + llama2) connected
  • ✅ paperless-ai scanning and tagging (~467 documents imported)
  • ⏳ Custom Fields not yet configured
  • ⏳ Nullfeld-Integration (FPGA × SoC star maps layer) — planned
  • ⏳ Vector-Bridge to Eule/Qdrant (cross-system RAG) — planned

Philosophical Context

This project follows Crumbforest principles — local-first, community-oriented, anti-surveillance computing. Two relevant guides apply when working here:

  • NO_AHAB_GUIDE.md — Warns against obsessive over-optimization ("the Ahab trap"). Work should flow, not be forced. Three warning signs: Druck (pressure), Vergleich (comparison), Zwang (coercion).
  • CKL.md / HHL.md — Ethical licenses extending MIT: non-military, non-surveillance, human-before-machine.

When suggesting changes, prefer simple and maintainable over clever and optimal.