Zum Inhalt springen

Paperless AI

29. Januar 2026 durch
Mário Santiago

AI: Der ultimative Guide für Debian

Self-Hosted, Privat und ohne Cloud-Zwang

Paperless-NGX ist der Goldstandard für das papierlose Büro. Doch die Standard-Installation hat eine Schwäche: Die OCR (Texterkennung) ist "dumm" und Metadaten müssen oft manuell gepflegt werden. In diesem Guide bauen wir den "Super-Stack" aus dem Video von TechnoTim nach. Wir kombinieren Paperless-NGX mit lokaler KI (Ollama), um Dokumente intelligent zu verstehen, automatisch zu benennen und sogar Handschriften oder komplexe Layouts via Vision-Modellen zu analysieren

Das Beste: Keine Daten verlassen deinen Server. Alles läuft lokal.

📋 Voraussetzungen

3609186

  • OS: Debian 11/12 oder Ubuntu 22.04/24.04 LTS.

  • CPU: Moderne Multi-Core CPU (Intel N100 oder besser empfohlen).

  • RAM: Mindestens 16 GB RAM empfohlen (für den KI-Stack). 8 GB sind das absolute Minimum und können zu Abstürzen führen.

  • GPU (Optional aber empfohlen): NVIDIA GPU für schnelle KI-Antworten. Ohne GPU läuft alles auf der CPU (langsamer, aber funktional).

  • Software: Root-Zugriff oder Sudo-Rechte.

🚀 Schritt 1: System vorbereiten & Docker installieren

Wir aktualisieren das System und installieren die Docker-Engine.

Bash

# Update system
sudo apt update && sudo apt upgrade -y

# Install necessary packages
sudo apt install -y curl git apt-transport-https ca-certificates gnupg lsb-release

# Add Docker Repository (Official method)
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Test installation
sudo docker compose version

📂 Schritt 2: Ordnerstruktur anlegen

Wir erstellen eine saubere Struktur, damit Daten (PDFs, Datenbanken) sicher außerhalb der Container liegen..

Bash

# Create main directory
mkdir -p /opt/paperless-ai-stack
cd /opt/paperless-ai-stack

# Subfolders for data persistence
mkdir -p paperless/data paperless/media paperless/consume paperless/export
mkdir -p postgres/data
mkdir -p ollama/data
mkdir -p open-webui/data
mkdir -p paperless-ai/data
mkdir -p paperless-gpt/config

🛠️Schritt 3: Der Docker-Compose Stack

Dies ist das Herzstück. Wir kombinieren Paperless-NGX, Tika/Gotenberg (für Office-Dateien), Ollama (KI-Engine) und die KI-Brücken paperless-ai und paperless-gpt.

Erstelle die Datei docker-compose.yml:

Bash

nano docker-compose.yml

Füge folgenden Inhalt ein (Copy & Paste):

YAML

services:
  # --- CORE: Paperless-NGX ---
  broker:
    image: docker.io/library/redis:7
    restart: unless-stopped
    volumes:
      - redis_data:/data

  db:
    image: docker.io/library/postgres:16
    restart: unless-stopped
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: ${PAPERLESS_DB_NAME}
      POSTGRES_USER: ${PAPERLESS_DB_USER}
      POSTGRES_PASSWORD: ${PAPERLESS_DB_PASS}

  webserver:
    image: ghcr.io/paperless-ngx/paperless-ngx:latest
    restart: unless-stopped
    depends_on:
      - db
      - broker
      - gotenberg
      - tika
    ports:
      - "8000:8000"
    volumes:
      - ./paperless/data:/usr/src/paperless/data
      - ./paperless/media:/usr/src/paperless/media
      - ./paperless/export:/usr/src/paperless/export
      - ./paperless/consume:/usr/src/paperless/consume
    environment:
      PAPERLESS_REDIS: redis://broker:6379
      PAPERLESS_DBHOST: db
      PAPERLESS_DBPASS: ${PAPERLESS_DB_PASS}
      PAPERLESS_DBUSER: ${PAPERLESS_DB_USER}
      PAPERLESS_DBNAME: ${PAPERLESS_DB_NAME}
      PAPERLESS_SECRET_KEY: ${PAPERLESS_SECRET_KEY}
      PAPERLESS_URL: ${PAPERLESS_URL}
      PAPERLESS_TIME_ZONE: "Europe/Berlin"
      PAPERLESS_OCR_LANGUAGE: "deu+eng"
      PAPERLESS_TIKA_ENABLED: 1
      PAPERLESS_TIKA_GOTENBERG_ENDPOINT: http://gotenberg:3000
      PAPERLESS_TIKA_ENDPOINT: http://tika:9998
      USERMAP_UID: 1000
      USERMAP_GID: 1000

  gotenberg:
    image: docker.io/gotenberg/gotenberg:8.7
    restart: unless-stopped
    command:
      - "gotenberg"
      - "--chromium-disable-routes=true"

  tika:
    image: docker.io/apache/tika:latest
    restart: unless-stopped

  # --- AI BRAIN: Ollama & WebUI ---
  ollama:
    image: ollama/ollama:latest
    restart: unless-stopped
    volumes:
      - ./ollama/data:/root/.ollama
    # If you have an NVIDIA GPU, uncomment the following block:
    # deploy:
    #   resources:
    #     reservations:
    #       devices:
    #         - driver: nvidia
    #           count: 1
    #           capabilities: [gpu]

  open-webui:
    image: ghcr.io/open-webui/open-webui:latest
    restart: unless-stopped
    ports:
      - "3001:8080"
    volumes:
      - ./open-webui/data:/app/backend/data
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434

  # --- AI INTEGRATION 1: Paperless-AI (Metadata & Chat) ---
  paperless-ai:
    image: ghcr.io/clusterzx/paperless-ai:latest
    restart: unless-stopped
    ports:
      - "3000:3000"
    volumes:
      - ./paperless-ai/data:/app/data
    environment:
      - PAPERLESS_API_URL=http://webserver:8000/api
      - PAPERLESS_API_TOKEN=${PAPERLESS_API_TOKEN}
      - AI_PROVIDER=ollama
      - OLLAMA_URL=http://ollama:11434
      - OLLAMA_MODEL=llama3.2:3b

  # --- AI INTEGRATION 2: Paperless-GPT (Vision OCR) ---
  paperless-gpt:
    image: ghcr.io/icereed/paperless-gpt:latest
    restart: unless-stopped
    ports:
      - "3002:8080"
    environment:
      - PAPERLESS_BASE_URL=http://webserver:8000
      - PAPERLESS_API_TOKEN=${PAPERLESS_API_TOKEN}
      - OLLAMA_HOST=http://ollama:11434
      # The Vision Model for better OCR
      - OCR_MODEL_NAME=minicpm-v:8b

volumes:
  redis_data:

🔐 Schritt 4: Die Umgebungsvariablen (.env)

Erstelle die .env Datei im gleichen Ordner. Hier werden Passwörter und Tokens definiert.

Bash

nano .env

Füge ein (unbedingt anpassen!):

Ini, TOML

# Database & Paperless Configuration
PAPERLESS_DB_USER=paperless
PAPERLESS_DB_NAME=paperless
PAPERLESS_DB_PASS=YourSecureDBPassword123!
# Generate a long random string for this (e.g., with 'openssl rand -hex 32')
PAPERLESS_SECRET_KEY=a1b2c3d4e5f6...

# The URL under which Paperless is accessible (Important for CORS)
PAPERLESS_URL=http://YOUR-SERVER-IP:8000

# API Token (Will be generated in Step 6 and added here later!)
# Leave this empty or set a placeholder for now
PAPERLESS_API_TOKEN=placeholder

▶️ Schritt 5: Erster Start & User anlegen

Wir starten den Core-Stack, um den Admin-User zu erstellen.

Bash

# Start containers
sudo docker compose up -d

# Wait until everything is running, then create Admin User for Paperless
sudo docker compose exec webserver manage.py createsuperuser

Folge den Anweisungen (Username, Email, Passwort).

Logge dich nun ein unter: http://DEINE-SERVER-IP:8000

🧠  Schritt 6: KI-Modelle laden & Token generieren

Damit die KI funktioniert, müssen wir die Modelle in Ollama laden und Paperless mit den KI-Containern verbinden.

1. Modelle laden:

Oeffne die Open-WebUI (http://DEINE-SERVER-IP:3001) oder nutze die CLI. Wir nutzen die CLI, da es schneller geht:

Bash

# Small, fast model for Text/Metadata
sudo docker compose exec ollama ollama pull llama3.2:3b

# Vision model for superior OCR (reading images)
sudo docker compose exec ollama ollama pull minicpm-v:8b

2. API Token generieren:

  1. Gehe in Paperless (Port 8000) -> Einstellungen (Profil oben rechts).

  2. Tab API Tokens.

  3. Erstelle einen neuen Token. Kopiere diesen.

3.  .env aktualisieren:

Öffne wieder deine .env Datei:

Bash

nano .env

Füge den kopierten Token bei PAPERLESS_API_TOKEN ein.

4. Neustart:

Bash

sudo docker compose down && sudo docker compose up -d

⚙️  Schritt 7: Konfiguration der KI-Tools

A.  Paperless-AI (Metadaten & Chat)

Erreichbar unter: http://DEIN-SERVER-IP:3000

  1. Logge dich ein (initialer Setup-Wizard).

  2. Verbinde es mit Paperless (URL intern: http://webserver:8000, Token aus Schritt 6).

  3. Wähle bei AI Provider "Ollama" und Modell llama3.2:3b.

  4. Feature: Hier kannst du einstellen, dass Dokumente automatisch Tags erhalten ("Rechnung", "Versicherung") oder du mit deinen Dokumenten "chatten" kannst ("Wieviel habe ich 2024 für Strom bezahlt?").

B. Paperless-GPT (Vision OCR)

Erreichbar unter: http://DEINE-SERVER-IP:3002

Paperless-GPT ist besonders mächtig, um schlechte Scans zu lesen.

  1. Es nutzt das Modell minicpm-v:8b.

  2. Workflow einrichten: Erstelle in Paperless-NGX einen Workflow, der beim Upload automatisch den Tag paperless-gpt-auto vergibt.

  3. Paperless-GPT überwacht diesen Tag. Sobald ein Dokument den Tag hat, liest die KI das Dokument visuell (statt nur Text-Layer) und schreibt den Inhalt neu in Paperless zurück. Das Ergebnis ist oft drastisch besser als Standard-OCR.

📝 Zusammenfassung & Abschluss

Was wir gemacht haben:

  1. Wir haben einen Debian-basierten Docker-Host aufgesetzt.

  2. Wir haben Paperless-NGX (Dokumentenverwaltung) installiert.

  3. Wir haben Ollama (Lokale KI) integriert, um Datenschutz zu gewährleisten.

  4. Wir haben Paperless-AI für intelligente Metadaten (Tags, Korrespondenten) konfiguriert.

  5. Wir haben Paperless-GPT für Vision-basiertes OCR eingerichtet, um selbst schwierigste Dokumente lesbar zu machen.

Backup Hinweis::

Sichere regelmäßig den Ordner /opt/paperless-ai-stack. Er enthält deine Datenbank, deine PDFs und deine Konfigurationen.

Viel Erfolg mit deinem wirklich smarten, papierlosen Büro!

Paperless Basics (Kopie) (Kopie)
FInden nicht suchen..