minmal-file-cloud-email-pim-passmanager/README.md

Mini-Cloud

Selbstgehostete Web-Cloud-Plattform mit Dateiverwaltung, Kalender, Kontakte, E-Mail-Webclient, Office-Editor und Passwort-Manager.

Features

• Dateiverwaltung - Upload/Download (Drag & Drop + Ordner-Upload), Berechtigungen, Share-Links (Lesen/Schreiben/Nur-Upload, Passwort, Ablaufdatum), Papierkorb, Ordner als ZIP downloaden
• Kalender - CalDAV-kompatibel (iOS, DAVx5, Thunderbird, Outlook), iCal-Export, Teilen mit Benutzern
• Kontakte - CardDAV-kompatibel, vCard-Export, Adressbuecher teilen
• E-Mail-Webclient - IMAP/SMTP-Proxy (kein eigener Mailserver), Multi-Account, Absender-Logik
• Office-Editor - DOCX, XLSX, PPTX bearbeiten mit OnlyOffice; PDF, Bilder, Text als Vorschau
• Passwort-Manager - AES-256-GCM clientseitig verschluesselt, TOTP, Passkeys, KeePass/Firefox/CSV-Import, Ordner teilen
• Benutzerverwaltung - Rollen (Admin/User), Speicher-Quotas, Einladungslinks, oeffentliche Registrierung an/aus
• Backup - Lokales ZIP-Backup, SFTP-Backup mit Scheduler + Versionierung, Einzeldatei-Restore
• Benachrichtigungen - System-Email bei Freigaben, Downloads, neuen Benutzern
• Sync-API - Delta-Sync fuer Desktop/Mobile-Clients

Tech-Stack

Bereich	Technologie
Backend	Python / Flask
Frontend	Vue 3 / Vite / PrimeVue
Datenbank	SQLite (WAL-Modus)
Auth	JWT (Web-UI) + HTTP Basic Auth (CalDAV/CardDAV)
Office-Editor	OnlyOffice Document Server (optional)

Installation

Voraussetzungen

• Python 3.11+
• Node.js 18+
• npm
• Docker (fuer Produktion)

Entwicklungsumgebung

# Repository klonen
git clone <repo-url>
cd mini-cloud-datei-email-kalender-kontakte

# .env anlegen
cp .env.example .env
# SECRET_KEY und JWT_SECRET_KEY generieren:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"
# Generierte Werte in .env eintragen

# Backend einrichten
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Backend starten
python wsgi.py
# -> laeuft auf http://localhost:5000 (nur API, nicht im Browser oeffnen)

# Frontend einrichten (neues Terminal)
cd frontend
npm install

# Frontend starten
npm run dev
# -> laeuft auf http://localhost:3100

Wichtig - Ports in der Entwicklung:

Port	Dienst	Im Browser oeffnen?
5000	Backend (Flask API)	Nein - nur API, kein Frontend
3100	Frontend (Vite Dev Server)	Ja - hier arbeiten!

Im Entwicklungsmodus immer http://localhost:3100 im Browser oeffnen. Der Vite Dev Server leitet API-Aufrufe automatisch an Port 5000 weiter (Proxy in vite.config.js).

In der Docker-Produktion laeuft alles auf einem einzigen Port (5000) - Backend liefert das gebaute Frontend direkt mit aus.

Beim ersten Registrieren wird der Benutzer automatisch zum Admin.

Docker (Produktion)

# .env anlegen und Secrets eintragen
cp .env.example .env
# SECRET_KEY und JWT_SECRET_KEY generieren und eintragen:
python3 -c "import secrets; print(secrets.token_urlsafe(64))"

# Starten
docker-compose up --build -d

Die Datenbank und hochgeladene Dateien liegen unter ./data/ (Bind Mount, keine Docker Volumes).

Nginx Reverse-Proxy (Beispiel)

Die Datei nginx.example.conf enthaelt eine vollstaendige Beispielkonfiguration:

# cloud.example.com -> Mini-Cloud (Port 5000)
server {
    listen 443 ssl http2;
    server_name cloud.example.com;
    ssl_certificate /etc/letsencrypt/live/cloud.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/cloud.example.com/privkey.pem;
    client_max_body_size 0;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Let's Encrypt Zertifikat erstellen:

certbot --nginx -d cloud.example.com

OnlyOffice Document Server

Fuer die Bearbeitung von Word, Excel und PowerPoint Dateien direkt im Browser. OnlyOffice benoetigt eine eigene Subdomain mit HTTPS.

1. .env - OnlyOffice URL setzen:

ONLYOFFICE_URL=https://office.example.com

Das JWT-Secret wird automatisch vom JWT_SECRET_KEY verwendet - kein extra Secret noetig.

2. docker-compose.yml - OnlyOffice-Service aktivieren:

Der OnlyOffice-Service ist in der docker-compose.yml bereits vorbereitet. Er nutzt den gleichen JWT_SECRET_KEY aus der .env.

3. Nginx - Eigene Subdomain fuer OnlyOffice:

server {
    listen 443 ssl http2;
    server_name office.example.com;
    ssl_certificate /etc/letsencrypt/live/office.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/office.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

4. Starten:

certbot --nginx -d office.example.com
docker-compose up --build -d

Ohne OnlyOffice (ONLYOFFICE_URL leer) werden Office-Dateien in einer einfachen Vorschau angezeigt. Mit OnlyOffice erhaelt man einen vollwertigen Editor (wie Google Docs).

Verwendung

Dateien

• Dateien per Drag-and-Drop oder Upload-Button hochladen
• Ganze Ordner mit Unterordnern hochladen (Drag & Drop oder Ordner-Button)
• Ordner erstellen, Dateien verschieben/umbenennen
• Ordner als ZIP herunterladen
• Geloeschte Dateien landen im Papierkorb (wiederherstellen oder endgueltig loeschen)
• Share-Links erstellen mit drei Berechtigungsstufen:
  • Nur Lesen - Download, Ordnerinhalt sehen
  • Lesen + Schreiben - Download, Upload, Loeschen
  • Nur Upload - Hochladen ohne Einblick (Briefkasten-Modus)
• Optional: Passwort und Ablaufdatum fuer Share-Links
• Dateien/Ordner mit anderen Benutzern teilen (Lesen/Schreiben/Admin)
• Gruenes Icon zeigt an welche Dateien bereits Freigaben haben

Kalender

• Kalender erstellen, Events anlegen (Monats-/Tagesansicht)
• Kalender mit anderen Benutzern teilen (Lesen oder Lesen+Schreiben)
• iCal-Link generieren fuer Read-Only-Import in Google Calendar, Apple Kalender etc.
• CalDAV-Zugriff fuer native Sync:
  • iOS: Einstellungen > Kalender > Accounts > Anderer > CalDAV
  • Android (DAVx5): Server-URL: https://<deine-domain>/dav/
  • Thunderbird: Neuer Kalender > Im Netzwerk > CalDAV
  • Outlook (CalDAV-Synchronizer): Server-URL: https://<deine-domain>/dav/

Kontakte

• Adressbuecher anlegen, Kontakte erstellen/bearbeiten
• Adressbuecher mit anderen Benutzern teilen
• vCard-Export fuer Backup
• CardDAV-Zugriff analog zum Kalender

E-Mail

• E-Mail-Konten unter Einstellungen hinzufuegen (IMAP/SMTP-Zugangsdaten)
• Admin kann E-Mail-Konten fuer andere Benutzer anlegen
• Kein eigener Mailserver noetig - verbindet sich mit externen Mailservern
• Bei keinem konfigurierten Konto wird der E-Mail-Bereich ausgeblendet
• Mehrere Konten: Ordner nach Konten gruppiert, Standard-Absender = aktives Konto

Office-Dateien

• Doppelklick oder Auge-Icon oeffnet die Vorschau
• Mit OnlyOffice: Vollwertiger Editor fuer DOCX, XLSX, PPTX (wie Google Docs)
• Ohne OnlyOffice: Einfache Vorschau (HTML/Tabelle/Folien), Text-Dateien bearbeitbar
• PDF wird inline angezeigt, Bilder mit Vorschau

Passwort-Manager

• Alle Daten clientseitig mit AES-256-GCM verschluesselt (Zero Knowledge)
• TOTP-Codes direkt generieren
• Passwort-Generator integriert
• Import aus: KeePass (.kdbx), Firefox (CSV), Chrome/Bitwarden/1Password (CSV)
• Ordner/Gruppen wie in KeePass
• Einzelne Passwoerter oder ganze Ordner mit anderen Benutzern teilen

Backup & Restore

• Lokales Backup: ZIP-Download mit Datenbank + allen Dateien
• SFTP-Backup: Automatisch auf SFTP-Server sichern
  • Mehrere Backup-Ziele moeglich
  • Konfigurierbares Intervall (15 Min. bis woechentlich)
  • Versionierung mit automatischem Aufraumen
  • Versionen durchsuchen und Einzeldateien wiederherstellen
• Restore: ZIP hochladen (Chunked Upload fuer grosse Backups) oder direkt von SFTP

Administration

• Benutzer anlegen, bearbeiten, deaktivieren, loeschen
• Benutzersuche
• E-Mail-Konten pro Benutzer verwalten
• Oeffentliche Registrierung an/aus
• Einladungslinks (funktionieren auch bei deaktivierter Registrierung)
• System-Email (SMTP) fuer Benachrichtigungen und Einladungen

Projektstruktur

backend/
  app/
    api/          # REST-Endpunkte
    models/       # SQLAlchemy-Models
    services/     # Business-Logik (Crypto, SFTP, Email, Scheduler)
    dav/          # CalDAV/CardDAV (Radicale-Vorbereitung)
  wsgi.py         # Einstiegspunkt

frontend/
  src/
    views/        # Vue-Seiten
    components/   # Wiederverwendbare Komponenten
    stores/       # Pinia State Management
    api/          # Axios API-Client
    router/       # Vue Router

data/             # Laufzeitdaten (gitignored)
  minicloud.db    # SQLite-Datenbank
  files/          # Hochgeladene Dateien

Desktop Sync Client

Der Desktop-Client (clients/desktop/) synchronisiert Dateien zwischen der Cloud und einem lokalen Ordner. Gebaut mit Tauri 2 (Rust + Vue).

Bauen

# Voraussetzung: Docker

# Linux:
./build.sh linux

# Windows (Cross-Compile):
./build.sh windows

# macOS (nur auf Mac):
./build.sh mac

# Alle Desktop-Plattformen:
./build.sh all-desktop

Auto-Upload auf den Server

Nach dem Build kann der Client automatisch auf den Cloud-Server hochgeladen werden und steht dort zum Download bereit.

Auf der Entwicklungsmaschine (nicht auf dem Server!) in die .env eintragen:

# URL der Cloud-Instanz
CLOUD_URL=https://cloud.example.com

# SECRET_KEY des Zielservers (identisch mit SECRET_KEY in der Server-.env)
BUILD_UPLOAD_TOKEN=der-secret-key-vom-server

Danach laedt ./build.sh linux (etc.) den Build automatisch hoch. Auf der Login-Seite erscheint dann "Desktop & Mobile Clients herunterladen".

Wichtig: CLOUD_URL und BUILD_UPLOAD_TOKEN gehoeren NUR in die .env der Entwicklungsmaschine, NICHT auf den Produktionsserver!

Roadmap

• Mobile Sync-Client (iOS, Android) mit On-Demand-Download + File Provider
• Native Passwort-Manager Clients mit Autofill und Biometrie
• Radicale-Integration fuer vollstaendiges CalDAV/CardDAV-Protokoll

Lizenz

Privates Projekt.