Mein Versuch zu fixen

docs/README.md

@@ -0,0 +1,70 @@
+# Dokumentation
+
+## Ablauf
+
+1. Das Script ermittelt das Projektverzeichnis.
+2. Es legt Backup- und Log-Verzeichnis an.
+3. Es prüft benötigte Kommandos und freien Speicher.
+4. Es stoppt Docker mit `docker compose down`.
+5. Es erstellt ein `tar.gz`-Archiv des Projektordners.
+6. Es startet Docker mit `docker compose up -d`.
+7. Es lädt das Archiv per SFTP hoch.
+8. Es verschickt bei Erfolg oder Fehler eine Mail, sofern Mailversand konfiguriert ist.
+9. Es löscht das lokale Archiv, außer `KEEP_LOCAL_BACKUP=true` ist gesetzt.
+
+## Konfiguration
+
+| Variable | Standard | Beschreibung |
+| --- | --- | --- |
+| `SFTP_HOST` | `sftp.example.com` | Hostname des SFTP-Servers |
+| `SFTP_PORT` | `22` | Port des SFTP-Servers |
+| `SFTP_USER` | `user` | SFTP-Benutzer |
+| `SFTP_PASS` | `Tpassw0rd` | SFTP-Passwort |
+| `SFTP_REMOTE_DIR` | `/uploads` | Zielverzeichnis auf dem SFTP-Server |
+| `MAIL_TO` | leer | Empfängeradresse; leer deaktiviert Mailversand |
+| `MAIL_FROM` | leer | Optionaler Absender für `mail -r` |
+| `BACKUP_DIR` | Ordner neben dem Projekt | Lokales Ziel für Archive |
+| `LOG_DIR` | `${BACKUP_DIR}/logs` | Lokales Ziel für Logs |
+| `KEEP_LOCAL_BACKUP` | `false` | Lokales Archiv nach Lauf behalten |
+| `MIN_FREE_MB` | `1024` | Zusätzlicher freier Speicher, der neben der Quellgröße vorhanden sein muss |
+
+## Voraussetzungen
+
+Auf dem Server müssen diese Kommandos verfügbar sein:
+
+- `docker`
+- `tar`
+- `gzip`
+- `sshpass`
+- `sftp`
+- optional `mail`
+
+## Mailversand
+
+Das Script nutzt das lokale Kommando `mail`. Auf Debian/Ubuntu kann dafür zum Beispiel `mailutils`, `bsd-mailx` oder ein passendes Mail-Relay wie `msmtp` eingerichtet sein.
+
+Wenn keine Mail ankommt:
+
+- prüfen, ob `MAIL_TO` gesetzt ist
+- prüfen, ob `mail` installiert ist: `command -v mail`
+- einen manuellen Test ausführen: `echo test | mail -s "Test" empfaenger@example.com`
+- lokale Mail-Logs prüfen, zum Beispiel `/var/log/mail.log`
+- falls `MAIL_FROM` Probleme macht, testweise leer lassen
+
+## Speicherplatz und große Dateien
+
+Das Archiv wird bewusst nicht in `/tmp` erstellt, weil `/tmp` auf vielen Systemen als kleiner tmpfs-Mount eingerichtet ist. Für große Projekte sollte `BACKUP_DIR` auf ein Dateisystem mit ausreichend freiem Speicher zeigen, zum Beispiel:
+
+```bash
+BACKUP_DIR=/srv/backups/mein-projekt ./docker-backup-sftp-uploader.sh
+```
+
+Das Script prüft vor dem Docker-Stopp grob, ob genug Platz vorhanden ist. Der Mindestbedarf entspricht ungefähr der Quellgröße plus 10 Prozent Reserve plus `MIN_FREE_MB`.
+
+Der SFTP-Upload schreibt zuerst `${BACKUP_FILE}.part` und benennt die Datei nach erfolgreichem Upload um. Dadurch bleibt auf dem Zielserver erkennbar, ob ein Upload vollständig abgeschlossen wurde.
+
+## Cron-Beispiel
+
+```cron
+0 3 * * * SFTP_HOST=backup.example.com SFTP_USER=backup SFTP_PASS='secret' SFTP_REMOTE_DIR=/uploads MAIL_TO=admin@example.com BACKUP_DIR=/srv/backups/mein-projekt /pfad/zum/docker-backup-sftp-uploader.sh
+```