docker.dateiverwaltung/INSTALLATION.md

# Dateiverwaltung - Installation & Deployment

**Version 1.1**

## Übersicht

Diese Anleitung beschreibt die Installation der Dateiverwaltung mit Docker und Portainer.

### Neue Features in Version 1.1
- **Dateimanager mit 3-Panel Layout** (Ordnerbaum, Dateiliste, Vorschau)
- **Separates Vorschau-Fenster** - öffnet auf zweitem Monitor
- **Resize-Handles** für flexible Panel-Größen (auch im vertikalen Modus)
- **Vorschau-Panel ausblendbar** wenn externes Fenster aktiv
- **Natürliche Sortierung** (Sonderzeichen → Zahlen → Buchstaben)
- **PDF-Vorschau** mit Fit-to-Page (erste Seite komplett sichtbar)

---

## 1. Voraussetzungen

- Docker & Docker Compose installiert
- Portainer (optional, für Web-UI Verwaltung)
- Zugriff auf die Ordner, die verwaltet werden sollen

---

## 2. Image erstellen

### Option A: tar.gz erstellen und in Portainer hochladen

1. **Auf deinem Rechner - Archiv erstellen:**
   ```bash
   cd /pfad/zum/projekt/docker.dateiverwaltung
   tar -czvf dateiverwaltung.tar.gz *
   ```

2. **In Portainer:**
   - **Images** → **Build image**
   - **Name:** `dateiverwaltung:latest`
   - **Build method:** Upload
   - **Select file:** Die erstellte `dateiverwaltung.tar.gz` hochladen
   - **Build the image** klicken

3. Warten bis "Successfully built" erscheint

### Option B: Auf dem Server bauen (einfacher)

```bash
# Projektordner erstellen
mkdir -p /opt/dateiverwaltung
cd /opt/dateiverwaltung

# Dateien kopieren (oder git clone)
# Alle Projektdateien hierhin kopieren

# Image bauen
docker build -t dateiverwaltung:latest .
```

### Option C: Mit Docker Compose bauen

```bash
cd /opt/dateiverwaltung
docker compose build
```

Das Image heißt dann `dockerdateiverwaltung-dateiverwaltung` (oder je nach Ordnername).

---

## 3. Schnellstart mit Docker Compose

### 2.1 Repository klonen oder Dateien kopieren

```bash
git clone <repository-url> /opt/dateiverwaltung
cd /opt/dateiverwaltung
```

### 2.2 Umgebungsvariablen konfigurieren

Erstelle eine `.env` Datei:

```bash
cp .env.example .env
nano .env
```

### 2.3 Container starten

```bash
docker compose up -d
```

Die Anwendung ist dann unter `http://localhost:8000` erreichbar.

---

## 4. Installation mit Portainer

### 4.1 Image bauen (falls noch nicht geschehen)

**Methode 1: Direkt auf dem Server**
```bash
cd /opt/dateiverwaltung
docker build -t dateiverwaltung:latest .
```

**Methode 2: In Portainer**
1. **Images** → **Build image**
2. Name: `dateiverwaltung:latest`
3. Upload: Projektdateien als tar.gz hochladen
   ```bash
   # Auf deinem PC/Server:
   cd /pfad/zum/projekt
   tar -czvf dateiverwaltung.tar.gz .
   # Diese Datei dann in Portainer hochladen
   ```
4. **Build the image** klicken

### 4.2 Stack erstellen

1. Öffne Portainer → **Stacks** → **Add Stack**
2. Name: `dateiverwaltung`
3. Wähle **Web editor** und füge folgende Konfiguration ein:

```yaml
services:
  dateiverwaltung:
    # WICHTIG: Entweder "image" ODER "build" verwenden, nicht beides!

    # Option 1: Bereits gebautes Image verwenden
    image: dateiverwaltung:latest

    # Option 2: Image beim Deploy bauen (Projektdateien müssen auf Server liegen)
    # build:
    #   context: /opt/dateiverwaltung
    #   dockerfile: Dockerfile

    container_name: dateiverwaltung
    restart: unless-stopped
    ports:
      - "${PORT:-8000}:8000"
    volumes:
      # Persistente Daten (Datenbank) - WICHTIG!
      - ${DATA_PATH:-/opt/dateiverwaltung/data}:/app/data

      # Quell-Ordner: Hier liegen die zu sortierenden Dateien
      - ${INBOX_PATH:-/mnt/inbox}:/mnt/inbox

      # Ziel-Ordner: Hierhin werden sortierte Dateien verschoben
      - ${ARCHIV_PATH:-/mnt/archiv}:/mnt/archiv

      # OCR-Backup Ordner (für Original-PDFs vor OCR)
      - ${BACKUP_PATH:-/mnt/backup}:/mnt/backup

      # Optional: Zusätzliche Ordner einbinden
      # - /mnt/nas/dokumente:/mnt/dokumente
      # - /mnt/scans:/mnt/scans

    environment:
      - TZ=${TIMEZONE:-Europe/Berlin}
      - DATABASE_URL=sqlite:////app/data/dateiverwaltung.db
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

### 4.4 Environment Variables in Portainer

Scrolle runter zu **Environment variables** und füge folgende Variablen hinzu:

| Variable | Beschreibung | Beispielwert |
|----------|--------------|--------------|
| `PORT` | Port für Web-UI | `8000` |
| `TIMEZONE` | Zeitzone | `Europe/Berlin` |
| `DATA_PATH` | Pfad für Datenbank (persistent!) | `/opt/dateiverwaltung/data` |
| `INBOX_PATH` | Ordner mit unsortieren Dateien | `/home/user/Dokumente/Inbox` |
| `ARCHIV_PATH` | Zielordner für sortierte Dateien | `/home/user/Dokumente/Archiv` |
| `BACKUP_PATH` | Backup-Ordner für PDFs vor OCR | `/home/user/Dokumente/Backup` |

### 4.5 Deploy Stack

Klicke auf **Deploy the stack**.

---

## 5. Komplette Schritt-für-Schritt Anleitung (Portainer)

### Schritt 1: Projektdateien auf Server kopieren

```bash
# Auf dem Server
mkdir -p /opt/dateiverwaltung
cd /opt/dateiverwaltung

# Projektdateien hierhin kopieren (z.B. per SCP, SFTP, Git)
# scp -r /lokaler/pfad/* user@server:/opt/dateiverwaltung/
```

### Schritt 2: Image bauen

```bash
cd /opt/dateiverwaltung
docker build -t dateiverwaltung:latest .
```

Warte bis "Successfully built" erscheint.

### Schritt 3: Datenordner erstellen

```bash
# Ordner für Datenbank erstellen
mkdir -p /opt/dateiverwaltung/data

# Ordner für Dateien (falls nicht vorhanden)
mkdir -p /mnt/inbox /mnt/archiv /mnt/backup
```

### Schritt 4: Stack in Portainer erstellen

1. Portainer öffnen → **Stacks** → **Add Stack**
2. Name: `dateiverwaltung`
3. Web editor → Diesen YAML-Code einfügen:

```yaml
services:
  dateiverwaltung:
    image: dateiverwaltung:latest
    container_name: dateiverwaltung
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - /opt/dateiverwaltung/data:/app/data
      - /mnt/inbox:/mnt/inbox
      - /mnt/archiv:/mnt/archiv
      - /mnt/backup:/mnt/backup
    environment:
      - TZ=Europe/Berlin
      - DATABASE_URL=sqlite:////app/data/dateiverwaltung.db
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
```

4. **Deploy the stack** klicken

### Schritt 5: Anwendung öffnen

- URL: `http://<server-ip>:8000`
- Dateimanager: `http://<server-ip>:8000/browser`

---

## 6. Ordner-Struktur

### Empfohlene Struktur auf dem Host:

```
/home/user/Dokumente/
├── Inbox/              # Unsortierte Dateien (Quell-Ordner)
│   ├── mail-anhänge/   # z.B. von Mail-Abruf
│   └── scans/          # z.B. vom Scanner
├── Archiv/             # Sortierte Dateien (Ziel-Ordner)
│   ├── rechnungen/
│   ├── verträge/
│   └── sonstiges/
└── Backup/             # Original-PDFs vor OCR
```

### Im Container sichtbar als:

```
/mnt/
├── inbox/              → Host: /home/user/Dokumente/Inbox
├── archiv/             → Host: /home/user/Dokumente/Archiv
└── backup/             → Host: /home/user/Dokumente/Backup
```

---

## 7. Erstmalige Einrichtung nach Start

### 5.1 Web-UI öffnen

Öffne `http://<server-ip>:8000`

### 5.2 Quell-Ordner hinzufügen

1. Klicke auf **+ Hinzufügen** bei "Quell-Ordner"
2. Konfiguriere:
   - **Name:** z.B. "Mail-Inbox"
   - **Quell-Pfad:** `/mnt/inbox` (wie im Container gemountet)
   - **Ziel-Ordner:** `/mnt/archiv`
   - **Dateitypen:** PDF, JPG, PNG, etc.

### 5.3 Regeln erstellen

#### Schnell-Regeln (Grob-Sortierung nach Typ):
1. Klicke auf **+ Schnell-Regel**
2. Wähle z.B. "E-Rechnungen (ZUGFeRD)" → Unterordner: `e-rechnungen`
3. Wähle "Bilder" → Unterordner: `bilder`

#### Fein-Regeln (nach Inhalt):
1. Klicke auf **+ Hinzufügen** bei "Fein-Regeln"
2. Konfiguriere Keywords und Dateinamen-Schema

### 5.4 OCR-Backup aktivieren (empfohlen)

1. Aktiviere "Backup vor OCR-Einbettung erstellen"
2. Wähle Backup-Ordner: `/mnt/backup`

---

## 8. Persistente Daten

### Diese Daten werden gespeichert:

| Pfad im Container | Inhalt | Wichtig? |
|-------------------|--------|----------|
| `/app/data/dateiverwaltung.db` | SQLite-Datenbank mit allen Einstellungen | **JA** |
| `/app/data/` | Logs und temporäre Dateien | Ja |

### Backup der Einstellungen:

```bash
# Datenbank sichern
docker cp dateiverwaltung:/app/data/dateiverwaltung.db ./backup/

# Oder Volume-Pfad direkt sichern
cp /opt/dateiverwaltung/data/dateiverwaltung.db ./backup/
```

---

## 9. Beispiel: Komplette docker-compose.yml

```yaml
version: '3.8'

services:
  dateiverwaltung:
    build: .
    container_name: dateiverwaltung
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      # Datenbank (WICHTIG: Persistent!)
      - ./data:/app/data

      # === ANPASSEN: Deine Ordner ===
      # Inbox: Hier landen unsortierte Dateien
      - /home/benutzer/Dokumente/Inbox:/mnt/inbox

      # Archiv: Hierhin werden Dateien sortiert
      - /home/benutzer/Dokumente/Archiv:/mnt/archiv

      # Backup: Original-PDFs vor OCR
      - /home/benutzer/Dokumente/Backup:/mnt/backup

      # NAS-Ordner (optional)
      - /mnt/nas/scans:/mnt/scans

    environment:
      - TZ=Europe/Berlin
      - DATABASE_URL=sqlite:////app/data/dateiverwaltung.db
```

---

## 10. Dateimanager (Dual-Pane Browser)

Die Anwendung enthält einen separaten Dateimanager unter `/browser`:

- **URL:** `http://<server-ip>:8000/browser`
- **Features:**
  - Dual-Pane Layout (Ordner links, Vorschau rechts)
  - Dateien umbenennen, verschieben, löschen
  - PDF/Bild-Vorschau ohne Dateisperrung
  - Kann auf separatem Monitor geöffnet werden

**Tipp:** Öffne den Link in einem neuen Fenster für Multi-Monitor-Setup.

---

## 11. Troubleshooting

### Container startet nicht

```bash
# Logs prüfen
docker logs dateiverwaltung

# Container neu bauen
docker compose build --no-cache
docker compose up -d
```

### Dateien können nicht gelesen/geschrieben werden

```bash
# Berechtigungen prüfen
ls -la /home/benutzer/Dokumente/Inbox/

# Container-User prüfen (läuft als root)
docker exec dateiverwaltung id

# Berechtigungen setzen
chmod -R 755 /home/benutzer/Dokumente/
```

### Datenbank zurücksetzen

```bash
# Alle Einstellungen löschen
docker exec dateiverwaltung rm /app/data/dateiverwaltung.db
docker restart dateiverwaltung
```

---

## 12. Updates

```bash
# Neueste Version holen
git pull

# Container neu bauen und starten
docker compose build
docker compose up -d
```

---

## 13. Portainer Stack Template (Copy & Paste)

Für schnelles Deployment in Portainer, kopiere diesen Stack:

```yaml
version: '3.8'

services:
  dateiverwaltung:
    build:
      context: /opt/dateiverwaltung
    container_name: dateiverwaltung
    restart: unless-stopped
    ports:
      - "8000:8000"
    volumes:
      - dateiverwaltung_data:/app/data
      - /mnt/inbox:/mnt/inbox
      - /mnt/archiv:/mnt/archiv
      - /mnt/backup:/mnt/backup
    environment:
      - TZ=Europe/Berlin
      - DATABASE_URL=sqlite:////app/data/dateiverwaltung.db
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  dateiverwaltung_data:
```

**Nach Deploy:**
1. Web-UI öffnen: `http://<ip>:8000`
2. Quell-Ordner hinzufügen: `/mnt/inbox` → `/mnt/archiv`
3. Regeln erstellen
4. Fertig!

---

## Zusammenfassung der wichtigsten Pfade

| Was | Pfad im Container | Host-Pfad (anpassen!) |
|-----|-------------------|----------------------|
| Datenbank | `/app/data/` | `./data` oder Volume |
| Inbox (Quelle) | `/mnt/inbox` | `/home/user/Inbox` |
| Archiv (Ziel) | `/mnt/archiv` | `/home/user/Archiv` |
| OCR-Backup | `/mnt/backup` | `/home/user/Backup` |