External Integrations

Analysis Date: 2026-04-17

Overview

OhnePapier is designed for zero cloud dependencies. All integrations are local or intra-container. No bytes leave the machine during normal operation. All service-to-service communication happens over Docker's internal network or via host.docker.internal.

Internal Service Integrations

paperless-ai → Paperless-ngx (REST API)

• Direction: paperless-ai polls Paperless-ngx
• Protocol: HTTP REST
• Internal URL: http://webserver:8000/api
• Auth: Bearer token (PAPERLESS_API_TOKEN)
• Schedule: Every 30 minutes (SCAN_INTERVAL=*/30 * * * *)
• Operations:
• Fetches unprocessed documents
• Writes back generated metadata (title, tags, correspondent, document type, date)
• Critical config note: PAPERLESS_API_URL must end with /api; PAPERLESS_URL must NOT have /api

paperless-ai → Ollama (LLM Inference)

• Direction: paperless-ai sends document text, receives metadata suggestions
• Protocol: HTTP (Ollama REST API)
• URL: http://host.docker.internal:11434 (crosses Docker network boundary to host)
• Model: llama3.2 (primary), llama2 (also installed)
• Provider setting: AI_PROVIDER=ollama
• Why host-native: Ollama runs on the host (not containerized) to access GPU hardware
• Critical config note: network_mode: bridge must NOT be set on paperless-ai or host.docker.internal DNS fails

Paperless-ngx → PostgreSQL

• Direction: Paperless-ngx (Django ORM) → PostgreSQL
• Protocol: PostgreSQL wire protocol
• Internal host: db:5432
• Database: paperless
• User: paperless
• Config: PAPERLESS_DBHOST=db (set in docker-compose.yml)
• Port: Not exposed to host

Paperless-ngx → Redis

• Direction: Paperless-ngx (Celery task queue) → Redis
• Protocol: Redis protocol
• Internal URL: redis://broker:6379
• Config: PAPERLESS_REDIS=redis://broker:6379 (set in docker-compose.yml)
• Role: Message broker for async OCR and document processing tasks
• Port: Not exposed to host

paperless-ai → ChromaDB / RAGZ (Vector Embeddings)

• Direction: Internal to the paperless-ai container
• Stack: ChromaDB + RAGZ + SentenceTransformer
• Storage: paperless-ai_data Docker volume (/app/data in container)
• Purpose: Vector embeddings for semantic document search (RAG layer)
• RAG service config: RAG_SERVICE_URL=http://webserver:8000, RAG_SERVICE_ENABLED=true
• Status: Active — vectors generated from imported documents

Data Storage

Primary Database:
- PostgreSQL 18
- Image: docker.io/library/postgres:18
- Connection: internal Docker network (db:5432)
- Volume: pgdata (Docker-managed)
- Holds: all Paperless-ngx document metadata, users, tokens, tags, etc.

Document File Storage:
- Local filesystem (Docker volumes + bind mounts)
- media volume: original and OCR-processed document files
- data volume: Paperless-ngx application state
- ./consume/: drop zone for new documents (bind-mounted)
- ./export/: document export target (bind-mounted)

Vector Storage:
- ChromaDB (embedded inside paperless-ai container)
- Volume: paperless-ai_data
- Populated by: SentenceTransformer embeddings on imported documents

Caching / Message Queue:
- Redis 8 (docker.io/library/redis:8)
- Volume: redisdata (persistent)
- Used by: Paperless-ngx Celery workers

Authentication & Identity

Paperless-ngx:
- Web UI: username/password (stored in PostgreSQL)
- API: DRF token authentication (Authorization: Token <token>)
- Token generation: docker exec paperless-webserver-1 python3 manage.py shell -c "..."
- Admin user created from docker-compose.env (ADMIN_USER, ADMIN_PASSWORD)

paperless-ai:
- Separate username/password (created at first setup via :3000/setup)
- Does not share credentials with Paperless-ngx; uses API token to connect

Ollama:
- No authentication — local HTTP endpoint only

LLM Provider

Ollama (local):
- Endpoint: http://host.docker.internal:11434
- Models installed: llama3.2, llama2
- Active model: llama3.2
- Inference: fully local, GPU-accelerated on host machine
- No API key required
- No telemetry / no cloud calls

Monitoring & Observability

Error Tracking: None — no external service

Logs:
- docker compose logs -f webserver — Paperless-ngx / Django / Celery logs
- docker compose logs -f paperless-ai — AI tagging activity
- docker compose logs -f db — PostgreSQL logs
- docker compose logs -f broker — Redis logs

Health Checks: None configured in docker-compose.yml (noted as a known risk — services can appear healthy while the connection chain is broken)

CI/CD & Deployment

Hosting: Local machine only (no cloud deployment)

CI Pipeline: None

Update process:

docker compose pull
docker compose up -d

Planned Integrations (Not Yet Active)

Eule / Qdrant (Vector Bridge):
- Purpose: Cross-system RAG search between OhnePapier and the Eule system (crumbforest.org)
- Status: Planned, not implemented

Nullfeld (FPGA x SoC star maps):
- Purpose: Additional data layer for star map visualization
- Status: Planned, not implemented

Webhooks & Callbacks

Incoming: None configured

Outgoing: None — paperless-ai uses polling (cron interval) not webhooks

Network Architecture

Host machine
├── Ollama (:11434)  ← GPU inference, not containerized
│
└── Docker network (default bridge)
    ├── broker (Redis :6379)       ← internal only
    ├── db (PostgreSQL :5432)      ← internal only
    ├── webserver (Paperless :8000) ← exposed to host
    └── paperless-ai (:3000)       ← exposed to host
         └── → host.docker.internal:11434 → Ollama

Environment Variables Reference

Integration audit: 2026-04-17