Kapitel 13/Free Rohtext.md hinzugefügt

Kapitel 13/Free Rohtext.md

@@ -0,0 +1,790 @@
+# Kapitel 13 – Git (Self-Hosted mit Gitea)
+
+## Einleitung
+
+Das **selbst gehostete Git-System** ist ein zentrales Element des **UCC** und bildet die technische Basis für alle Projekte, Skripte und Dokumentationen.  
+Mit **Gitea** betreibst du dein eigenes Versionskontrollsystem – unabhängig von GitHub, GitLab oder anderen externen Plattformen.  
+Dadurch behältst du die volle Kontrolle über deine Daten, kannst Änderungen lückenlos nachverfolgen und Projekte sicher archivieren.
+
+👉 **Screenshot geeignet:** Übersicht UCC-Struktur mit hervorgehobener Position von Gitea zwischen Automatisierung (n8n) und Dokumentation (Nextcloud/Affine)
+
+Gerade für Content Creator, Streamer oder kleine Teams ist ein eigenes Git-System ein enormer Vorteil:  
+Es ermöglicht eine klare Struktur für Skripte, Overlays, Automatisierungen oder Tutorials – ohne Risiko, dass Plattformen plötzlich verschwinden oder kostenpflichtig werden.
+
+Gitea ist leichtgewichtig, performant und speziell für den privaten oder semiprofessionellen Einsatz optimiert.  
+Es benötigt kaum Ressourcen, lässt sich in wenigen Minuten aufsetzen und bietet trotzdem alle wichtigen Funktionen: Repository-Verwaltung, Nutzer- und Rechte-Management, Weboberfläche, SSH-Zugriff und wahlweise Spiegelung zu GitHub oder anderen Instanzen.
+
+> [!NOTE]  
+> Gitea ist keine abgespeckte Git-Variante, sondern eine vollwertige Lösung für alle gängigen Git-Workflows.  
+> Es eignet sich sowohl für einfache Projekte im Homelab als auch für komplexe Mehrbenutzer-Setups mit externem Zugriff über den Nginx Proxy Manager.
+
+Ziel dieses Kapitels ist der Aufbau eines stabilen und sicheren Containers, der Gitea als eigenständigen Dienst bereitstellt.  
+Nach Abschluss steht ein **vollwertiges, selbst gehostetes Git-System** zur Verfügung, das deine Arbeit dauerhaft versioniert, zentralisiert und vollständig unter deiner Kontrolle hält.
+
+👉 **Screenshot geeignet:** Zielzustand – Browserfenster mit Gitea-Startseite unter eigener Domain (`https://git.deinedomain.tld`)
+
+---
+
+## Voraussetzungen & Ressourcen
+
+Bevor du mit der Einrichtung des Git-LXC beginnst, überprüfe, ob dein System vollständig vorbereitet ist.  
+Die folgenden Punkte legen fest, welche Ressourcen und Bedingungen zwingend erfüllt sein müssen, damit Gitea zuverlässig betrieben werden kann.
+
+### Container-Ressourcen
+
+* **CPU: 2 vCPUs**  
+  Diese Zuweisung stellt sicher, dass Gitea auch bei gleichzeitigen Zugriffen (z. B. Push, Pull, Web-UI) stabil arbeitet.  
+  Eine geringere Zuweisung kann zu Verzögerungen bei Git-Operationen führen.
+
+* **RAM: 2 GB**  
+  Diese Größe deckt Weboberfläche, Git-Prozesse und Docker-Umgebung zuverlässig ab.  
+  Bei weniger Arbeitsspeicher kann es bei Repository-Klons oder größeren Commits zu Performance-Einbrüchen kommen.
+
+* **Speicherplatz: 20 GB**  
+  Reicht für System, Repositories, Logs und temporäre Git-Daten.  
+  Wenn du große Medienprojekte versionierst (z. B. mit LFS), sollte der Speicher bereits beim Erstellen des Containers erweitert werden.
+
+* **Betriebssystem: Debian 12 (Bookworm)**  
+  Debian bietet maximale Stabilität und Kompatibilität für Docker und Gitea.  
+  Alle Befehle und Pfade in diesem Kapitel beziehen sich auf Debian 12.
+
+* **Netzwerk: statische IP-Adresse oder DHCP-Reservierung**  
+  Der Container muss dauerhaft unter derselben IP erreichbar sein,  
+  da die Proxy-Einbindung über feste Zieladressen erfolgt.
+
+> [!TIP]  
+> Weise die IP-Adresse direkt beim Erstellen des Containers zu.  
+> Eine nachträgliche Änderung würde sämtliche Proxy- und SSH-Einträge betreffen.
+
+### Technische Voraussetzungen
+
+* **Proxmox VE ist installiert und funktionsfähig.**  
+  Der Container wird direkt über die Proxmox-Oberfläche erstellt und verwaltet.
+
+* **Nginx Proxy Manager (NPM) ist eingerichtet.**  
+  Er wird benötigt, um die Gitea-Weboberfläche über HTTPS bereitzustellen.
+
+* **DNS- oder DynDNS-Eintrag ist vorhanden.**  
+  Eine Subdomain wie `git.deinedomain.tld` ist vorbereitet und im DNS eingetragen.
+
+* **SSH-Zugriff auf den Container ist möglich.**  
+  Entweder über die Proxmox-Konsole oder per Terminal (z. B. `ssh root@10.0.0.13`).
+
+* **Docker und Docker Compose werden im Container installiert.**  
+  Diese dienen als Grundlage für den späteren Gitea-Dienst.
+
+* **Grundstruktur des UCC ist aktiv.**  
+  Proxmox, Proxy Manager und Netzwerkverbindungen laufen stabil,  
+  damit der Container nach Fertigstellung sofort integriert werden kann.
+
+> [!IMPORTANT]  
+> Der Git-LXC ist ein dauerhaft aktiver Dienst.  
+> Stelle sicher, dass er auf einem Host mit stabiler Netzwerkverbindung liegt und nicht gemeinsam mit anderen produktiven Containern auf einem kritischen Volume betrieben wird.
+
+👉 **Screenshot geeignet:** Ressourcen-Übersicht im Proxmox-Dialog beim Anlegen des Git-LXC (vCPU, RAM, Storage)
+
+---
+
+## Schritt-für-Schritt-Anleitung
+
+In diesem Abschnitt richtest du den **Git-LXC** vollständig ein.  
+Alle Befehle sind direkt übernehmbar und so gewählt, dass sie ohne Anpassung ausgeführt werden können.  
+Am Ende dieses Abschnitts steht ein vollständig lauffähiger Gitea-Container, erreichbar über HTTPS und mit funktionsfähiger Repository-Verwaltung.
+
+### Schritt 1 – System aktualisieren
+
+Starte den Container über die Proxmox-Oberfläche und öffne anschließend die Konsole oder verbinde dich per SSH.  
+Bringe das System auf den aktuellen Stand:
+
+```bash
+apt update && apt upgrade -y
+reboot
+```
+
+Nach dem Neustart erneut einloggen.
+
+> [!NOTE]  
+> Auch bei frisch erstellten Containern ist ein Systemupdate erforderlich.  
+> Veraltete Paketquellen führen später zu Problemen bei der Installation von Docker oder Gitea.
+
+👉 **Screenshot geeignet:** Proxmox-Konsole mit erfolgreichem Systemupdate
+
+### Schritt 2 – Grundpakete installieren
+
+Installiere die grundlegenden Werkzeuge, die für die Docker-Installation benötigt werden:
+
+```bash
+apt install -y curl gnupg lsb-release ca-certificates nano
+```
+
+Diese Pakete stellen sicher, dass Zertifikate, GPG-Schlüssel und Repositorys korrekt verwaltet werden.
+
+> [!TIP]  
+> Wenn du Docker bereits in anderen Containern nutzt, kannst du die Installation künftig in einem zentralen Skript automatisieren.
+
+### Schritt 3 – Docker und Docker Compose installieren
+
+Damit Gitea im Container als eigenständiger Dienst laufen kann, benötigst du Docker.  
+Füge zuerst den offiziellen GPG-Schlüssel und das Repository hinzu:
+
+```bash
+mkdir -p /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/debian/gpg | 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" | tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+apt update
+apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
+```
+
+Prüfe anschließend, ob Docker korrekt läuft:
+
+```bash
+systemctl status docker
+```
+
+Wenn der Status **active (running)** angezeigt wird, ist Docker einsatzbereit.
+
+> [!NOTE]  
+> Docker Compose wird in dieser Anleitung als Plugin installiert.  
+> Der Befehl lautet daher `docker compose` (mit Leerzeichen) statt `docker-compose`.
+
+👉 **Screenshot geeignet:** Statusanzeige von Docker im Terminal (active running)
+
+### Schritt 4 – Arbeitsverzeichnis und Compose-Datei anlegen
+
+Lege den Arbeitsordner für Gitea an und erstelle die Konfigurationsdatei für Docker Compose:
+
+```bash
+mkdir /gitea && cd /gitea
+nano docker-compose.yml
+```
+
+Füge folgenden Inhalt ein:
+
+```yaml
+version: "3"
+
+services:
+  gitea:
+    image: gitea/gitea:latest
+    container_name: gitea
+    environment:
+      - USER_UID=1000
+      - USER_GID=1000
+    volumes:
+      - ./gitea:/data
+    ports:
+      - "3000:3000"   # Weboberfläche
+      - "222:22"      # SSH-Zugriff
+    restart: always
+```
+
+Datei speichern (**Strg + O**, **Enter**, **Strg + X**).
+
+> [!TIP]  
+> Die UID /GID sorgen für korrekte Dateiberechtigungen.  
+> Port 222 wird als SSH-Port nach außen weitergeleitet, um Konflikte mit anderen Diensten zu vermeiden.
+
+👉 **Screenshot geeignet:** geöffnete `docker-compose.yml` mit vollständigem Inhalt
+
+### Schritt 5 – Gitea starten und Funktion prüfen
+
+Starte den Containerdienst:
+
+```bash
+docker compose up -d
+```
+
+Prüfe anschließend den Status:
+
+```bash
+docker ps
+```
+
+Wenn Gitea in der Liste erscheint, läuft der Dienst erfolgreich.  
+Die Weboberfläche ist jetzt erreichbar unter:
+
+```
+http://<IP-des-Containers>:3000
+```
+
+> [!NOTE]  
+> Der erste Start kann bis zu 30 Sekunden dauern, während Gitea seine interne Struktur anlegt.
+
+👉 **Screenshot geeignet:** Browser mit Gitea-Setup-Seite (`http://<IP>:3000`)
+
+### Schritt 6 – Erstkonfiguration im Browser
+
+Öffne im Browser die Adresse deines Containers:
+
+```
+http://<IP-des-Containers>:3000
+```
+
+Hier richtest du deine Gitea-Instanz zum ersten Mal ein.  
+Alle Einstellungen, die du jetzt festlegst, bestimmen das Verhalten und die Erreichbarkeit des Systems.
+
+#### Datenbankeinstellungen
+
+Für das Homelab genügt die integrierte SQLite-Datenbank.  
+Sie ist schnell, wartungsarm und benötigt keine zusätzliche Konfiguration.
+
+| Feld | Wert |
+|------|------|
+| **Datenbanktyp** | SQLite3 |
+| **Pfad** | `/data/gitea/gitea.db` |
+
+> [!TIP]  
+> SQLite ist ideal für Einzelanwender oder kleine Teams.  
+> Für größere Strukturen kann Gitea später jederzeit auf MariaDB oder PostgreSQL umgestellt werden.
+
+#### Server-Einstellungen
+
+| Feld | Empfohlener Wert |
+|------|------------------|
+| **Seitentitel** | Bratonien Git |
+| **Run User** | `git` |
+| **Domain** | IP-Adresse des Containers (z. B. `10.0.0.13`) |
+| **SSH-Port** | `222` |
+| **HTTP-Port** | `3000` |
+| **Basis-URL** | `http://10.0.0.13:3000/` |
+
+> [!NOTE]  
+> Nach der Integration in den Proxy Manager wird die Basis-URL später auf HTTPS umgestellt.
+
+#### Benutzer und Sicherheit
+
+- **Registrierung erlauben:** deaktiviert  
+- **Gravatar aktivieren:** deaktiviert  
+- **Offline-Modus:** aktiviert  
+- **Passwort-Hash:** `pbkdf2` (Standard und sicher)
+
+Damit ist deine Instanz vollständig lokal und datenschutzfreundlich konfiguriert.
+
+#### Administrator-Konto
+
+Trage deinen gewünschten Benutzernamen und Passwort ein.  
+E-Mail-Adresse kann als Dummy gesetzt werden, z. B. `admin@localhost`.  
+Klicke anschließend auf **Installieren**.
+
+Nach wenigen Sekunden startet Gitea automatisch neu und zeigt die Login-Seite an.
+
+👉 **Screenshot geeignet:** Gitea-Setup-Seite mit ausgefüllten Feldern (vor Installation)
+
+> [!IMPORTANT]  
+> Speichere die gewählten Zugangsdaten sicher ab.  
+> Der Administrator ist der einzige Benutzer mit Vollzugriff, bis weitere Accounts angelegt werden.
+
+### Schritt 7 – Erstes Repository anlegen
+
+Melde dich mit deinem Administrator-Account an.  
+Klicke in der Weboberfläche oben auf **Neues Repository**.
+
+| Feld | Beispielwert |
+|------|---------------|
+| **Besitzer** | `admin` |
+| **Repository-Name** | `tutorials` |
+| **Sichtbarkeit** | privat |
+| **README erstellen** | aktiviert |
+| **Lizenz** | CC BY (Namensnennung „Bratonien Tech“) |
+
+> [!TIP]  
+> Ein initiales README hilft dir, sofort einen Überblick über neue Projekte zu behalten.  
+> So erscheint dein Repository direkt mit einer Startseite und Beschreibung.
+
+Nach dem Erstellen kannst du das Repository direkt im Browser durchsuchen oder per Git verbinden.
+
+👉 **Screenshot geeignet:** Neues Repository mit Beispielname „tutorials“
+
+### Schritt 8 – Verbindung über das Terminal herstellen
+
+Wechsle auf dein lokales System (z. B. Streaming-PC, Laptop oder Arbeitsrechner).  
+Erstelle dort ein Testverzeichnis und initialisiere dein erstes Projekt:
+
+```bash
+mkdir testprojekt && cd testprojekt
+git init
+git remote add origin http://<IP-des-Containers>:3000/admin/tutorials.git
+echo "# Hallo Gitea" > README.md
+git add .
+git commit -m "Erster Commit"
+git push -u origin master
+```
+
+> [!NOTE]  
+> Wenn du SSH bevorzugst, kannst du alternativ diese Verbindung verwenden:
+> ```bash
+> git remote set-url origin ssh://git@<domain-oder-ip>:222/admin/tutorials.git
+> ```
+> Den benötigten SSH-Schlüssel legst du im Benutzerprofil in Gitea an.
+
+👉 **Screenshot geeignet:** Terminalausgabe nach erfolgreichem Push
+
+> [!TIP]  
+> Sobald dein erstes Repository erfolgreich gepusht wurde, gilt dein Gitea-Server als vollständig funktionsfähig.  
+> Weitere Projekte können direkt in der Weboberfläche oder per Git-Befehl angelegt werden.
+
+### Schritt 9 – Einbindung in Nginx Proxy Manager (NPM)
+
+Nachdem Gitea intern getestet wurde und über `http://<IP>:3000` erreichbar ist, erfolgt nun die Integration in den **Nginx Proxy Manager**.  
+Dadurch wird die Weboberfläche über HTTPS bereitgestellt und erhält eine feste, leicht merkbare Subdomain.
+
+> [!IMPORTANT]  
+> Führe diesen Schritt erst aus, wenn du die Gitea-Oberfläche bereits über die interne IP-Adresse aufrufen kannst.  
+> So lässt sich sicherstellen, dass eventuelle Fehler eindeutig auf den Proxy und nicht auf den Container zurückzuführen sind.
+
+#### Proxy-Host für Gitea anlegen
+
+1. Öffne das Dashboard des **Nginx Proxy Manager**.  
+2. Klicke auf **Add Proxy Host**.  
+3. Trage folgende Werte ein:
+
+| Feld | Wert |
+|------|------|
+| **Domain Names** | `git.deinedomain.tld` |
+| **Scheme** | `http` |
+| **Forward Hostname / IP** | IP-Adresse des Git-LXC |
+| **Forward Port** | `3000` |
+| **Block Common Exploits** | aktivieren |
+| **Websockets Support** | aktivieren |
+
+Wechsle anschließend in den Reiter **SSL**:
+
+- **Request a new SSL Certificate** → aktivieren  
+- **Force SSL** → aktivieren  
+- **HTTP/2 Support** → aktivieren  
+
+Speichere die Konfiguration mit **Save**.
+
+👉 **Screenshot geeignet:** NPM-Maske mit eingetragenem Proxy-Host `git.deinedomain.tld`
+
+> [!NOTE]  
+> Nach dem Speichern wird automatisch ein gültiges Let’s-Encrypt-Zertifikat erstellt.  
+> Damit ist die Verbindung zu deiner Git-Instanz verschlüsselt und über HTTPS erreichbar.
+
+#### Verbindung prüfen
+
+Öffne im Browser:
+
+```
+https://git.deinedomain.tld
+```
+
+Wenn die Login-Seite von Gitea angezeigt wird, funktioniert die Weiterleitung korrekt.  
+Logge dich mit deinem Administrator-Account ein und überprüfe, ob alle Repositories sichtbar sind.
+
+👉 **Screenshot geeignet:** Browserfenster mit Gitea-Login unter `https://git.deinedomain.tld`
+
+> [!TIP]  
+> Wenn die Seite nicht lädt oder eine Fehlermeldung erscheint, prüfe im NPM-Dashboard,  
+> ob der Forward-Port korrekt auf `3000` gesetzt ist und das SSL-Zertifikat gültig ist.
+
+#### Basis-URL in Gitea anpassen
+
+Damit interne Links, Repository-URLs und Web-Hooks über die neue Domain funktionieren,  
+muss die **ROOT_URL** direkt in der Konfigurationsdatei `app.ini` geändert werden.
+
+1. Öffne ein Terminal oder die Proxmox-Konsole.  
+2. Öffne die Gitea-Konfigurationsdatei im Container:
+
+```bash
+nano /gitea/gitea/conf/app.ini
+```
+
+3. Suche im Abschnitt `[server]` den Eintrag `ROOT_URL`.  
+   Wenn dieser noch nicht vorhanden ist, füge ihn hinzu oder passe ihn an:
+
+```
+[server]
+DOMAIN           = git.deinedomain.tld
+SSH_DOMAIN       = git.deinedomain.tld
+HTTP_PORT        = 3000
+ROOT_URL         = https://git.deinedomain.tld/
+DISABLE_SSH      = false
+START_SSH_SERVER = false
+```
+
+4. Datei speichern (**Strg + O**, **Enter**, **Strg + X**)  
+5. Gitea-Container neu starten:
+
+```bash
+docker compose restart
+```
+
+> [!NOTE]  
+> Die Datei `app.ini` liegt innerhalb des Volume-Verzeichnisses, das im Compose-File mit `./gitea:/data` eingebunden ist.  
+> Wenn du also ein anderes Verzeichnis verwendest, musst du den Pfad entsprechend anpassen (z. B. `/data/gitea/conf/app.ini`).
+
+> [!IMPORTANT]  
+> Änderungen an der `app.ini` werden erst nach einem Neustart wirksam.  
+> Anschließend generiert Gitea alle Links und Web-Hooks automatisch mit der neuen HTTPS-Domain.
+
+👉 **Screenshot geeignet:** geöffnete `app.ini` mit korrekt eingetragener ROOT_URL
+
+### Schritt 10 – Benutzerverwaltung und Rechte in Gitea
+
+Öffne Gitea im Browser und melde dich als Administrator an.
+
+#### 1. Selbstregistrierung deaktivieren (falls noch aktiv)
+**Site Administration → Konfiguration → Benutzerregistrierung:** deaktivieren  
+Speichern.
+
+#### 2. Standard-Rollen und Sichtbarkeit festlegen
+**Site Administration → Benutzer:**  
+- Lege für Team-Mitglieder individuelle Benutzer an.  
+- Weise Benutzern nur die nötigen Rechte pro Repository zu (z. B. **Write** statt **Admin**).
+
+#### 3. (Optional) Organisation anlegen
+- **Neu → Organisation** (z. B. `bratonien`)  
+- Teams anlegen (z. B. `editor`, `viewer`) und Rechte je Repo definieren.
+
+#### 4. SSH-Schlüssel hinterlegen
+**Profil (oben rechts) → SSH Keys → Add Key:**  
+- Öffentlichen Schlüssel einfügen und speichern.  
+- Klonen per SSH testen (siehe Schritt 12).
+
+> [!TIP]  
+> Nutze Organisation + Teams, wenn mehrere Personen arbeiten. Für Solo-Setups reichen Benutzer + Repo-Rechte.
+
+
+### Schritt 11 – Sicherheit und Zugriff beschränken
+
+#### 1. Admin-Konto absichern
+- Starkes Passwort (≥ 16 Zeichen).  
+- Zweites Admin-Konto für Notfälle anlegen, erstes Admin-Konto nicht im Alltag nutzen.
+
+#### 2. ROOT_URL und Domains in `app.ini` fest verankern
+```ini
+# Datei: /gitea/gitea/conf/app.ini
+[server]
+DOMAIN           = git.deinedomain.tld
+SSH_DOMAIN       = git.deinedomain.tld
+HTTP_PORT        = 3000
+ROOT_URL         = https://git.deinedomain.tld/
+DISABLE_SSH      = false
+START_SSH_SERVER = true
+```
+Speichern, dann:
+```bash
+docker compose restart
+```
+
+> [!IMPORTANT]  
+> NPM kann **kein SSH** terminieren. Für SSH-Zugriff von außen Port **222** am Router auf den LXC weiterleiten – oder SSH extern deaktivieren und nur **HTTPS** (Klon via Token) erlauben.
+
+#### 3. Firewall im LXC (UFW) setzen
+Nur internes Netz zulassen, direkte Zugriffe auf 3000/222 von außen blocken (Zugriff läuft über NPM bzw. gezielte Portweiterleitung):
+
+```bash
+apt install -y ufw
+ufw allow from 127.0.0.1
+ufw allow from 192.168.100.0/24
+ufw deny 3000
+ufw deny 222
+ufw enable
+```
+
+> [!NOTE]  
+> Ersetze `192.168.100.0/24` durch deinen LAN-Bereich. Wenn du SSH extern brauchst, **keinen** generellen `deny 222` setzen, sondern sauber am Router weiterleiten.
+
+#### 4. Backups einplanen
+- Volume `/gitea` regelmäßig sichern (Repos, `app.ini`, DB).  
+- Für SQLite genügt Dateisicherung; bei MariaDB/PostgreSQL zusätzlich DB-Dump.
+
+
+### Schritt 12 – Funktionstest (HTTPS, SSH, Push/Pull)
+
+#### 1. Web-Zugriff prüfen
+```
+https://git.deinedomain.tld
+```
+Login als Admin → Startseite wird geladen.
+
+#### 2. Klonen & Push über HTTPS (mit Personal Access Token)
+**Profil → Applications → Generate Token** (Scope: repo).  
+Dann lokal:
+```bash
+git clone https://git.deinedomain.tld/admin/tutorials.git
+cd tutorials
+echo "Test" >> CHECK.md
+git add .
+git commit -m "Connectivity test (HTTPS)"
+git push
+```
+
+#### 3. (Optional) Klonen & Push über SSH
+```bash
+git clone ssh://git@git.deinedomain.tld:222/admin/tutorials.git
+cd tutorials
+echo "SSH OK" >> SSH_CHECK.md
+git add .
+git commit -m "Connectivity test (SSH)"
+git push
+```
+
+#### 4. Links und RAW-Ansicht prüfen
+- Datei im Browser öffnen → **Raw** laden muss sofort funktionieren.  
+- Repo-URL zeigt die korrekte **HTTPS-Domain** (keine IP).
+
+> [!TIP]  
+> Wenn Push per HTTPS nach Token fragt: Benutzername = dein Gitea-User, Passwort = **Token**.
+
+---
+
+## Troubleshooting & Tipps
+
+Auch wenn Gitea im Normalbetrieb sehr stabil läuft, können während oder nach der Einrichtung kleinere Probleme auftreten.  
+Die folgenden Punkte decken die häufigsten Ursachen ab und zeigen, wie du sie schnell behebst.
+
+### Gitea-Weboberfläche nicht erreichbar
+
+Wenn `https://git.deinedomain.tld` nicht geladen wird oder eine Fehlermeldung wie *Verbindung fehlgeschlagen* erscheint:
+
+1. Prüfe, ob der Container aktiv ist:  
+   ```bash
+   docker ps
+   ```
+   Wenn Gitea nicht angezeigt wird, neu starten:  
+   ```bash
+   docker compose up -d
+   ```
+2. Wenn der Dienst läuft, aber nur per IP erreichbar ist, liegt der Fehler meist am Proxy-Eintrag:  
+   - Im Nginx Proxy Manager prüfen, ob der **Forward-Port** auf `3000` gesetzt ist.  
+   - Gültiges SSL-Zertifikat bestätigen.  
+3. Browser-Cache leeren und Seite erneut aufrufen.
+
+> [!TIP]  
+> Wenn du Gitea erst frisch über HTTPS angebunden hast, kann es bis zu einer Minute dauern, bis der Proxy und das Zertifikat aktiv sind.
+
+### Anmeldung funktioniert, aber Repositories fehlen
+
+Wenn du dich erfolgreich anmeldest, aber keine Repositories angezeigt werden:
+
+- Prüfe in **Site Administration → Benutzer**, ob dein Konto Besitzer oder Mitglied eines Repositories ist.  
+- Bei **privaten Repositories** musst du explizit Berechtigungen vergeben.  
+- Bei Organisationen sicherstellen, dass der Benutzer einem Team mit Zugriffsrechten zugeordnet ist.
+
+> [!NOTE]  
+> Administratoren sehen Repositories nicht automatisch.  
+> Die Rechte müssen pro Projekt oder Organisation vergeben werden.
+
+### Push schlägt fehl
+
+Wenn beim Push-Vorgang eine Fehlermeldung wie  
+`remote: invalid username or password`  
+oder  
+`fatal: Authentication failed`  
+erscheint:
+
+- Prüfe, ob du über **HTTPS mit Token** oder **SSH mit Schlüssel** arbeitest.  
+- Für HTTPS: Im Benutzerprofil unter **Applications → Generate Token** einen neuen Token erzeugen und als Passwort verwenden.  
+- Für SSH: Schlüssel neu hinterlegen (**Profil → SSH Keys → Add Key**) und Verbindung prüfen.
+
+> [!TIP]  
+> Benutzername beim Push ist dein Gitea-Account, Passwort ist der Token.  
+> Tokens können beliebig oft neu erzeugt werden, ohne das Benutzerpasswort zu ändern.
+
+### Fehlerhafte ROOT_URL oder falsche Links
+
+Wenn Repository-Links oder Webhooks noch auf die interne IP zeigen, obwohl HTTPS aktiv ist:
+
+1. Datei `/gitea/gitea/conf/app.ini` öffnen.  
+2. Im Abschnitt `[server]` prüfen:
+   ```
+   ROOT_URL = https://git.deinedomain.tld/
+   ```
+3. Gitea neu starten:
+   ```bash
+   docker compose restart
+   ```
+
+> [!NOTE]  
+> Änderungen an der ROOT_URL werden erst nach dem Neustart wirksam.
+
+### SSH-Verbindung schlägt fehl
+
+Wenn `ssh git@git.deinedomain.tld -p 222` keine Verbindung aufbaut:
+
+- Prüfen, ob im Compose-File der Port `222:22` korrekt gesetzt ist.  
+- Firewall (UFW) prüfen, ob `222` erlaubt ist.  
+- Wenn du SSH nur intern verwenden willst, Portweiterleitung im Router entfernen.  
+
+### Port oder Dienst blockiert
+
+Wenn der Container nicht startet oder „port already in use“ erscheint:
+
+1. Prüfen, ob ein anderer Dienst Port 3000 oder 222 nutzt:
+   ```bash
+   ss -tuln | grep 3000
+   ```
+2. Falls ja, Compose-File anpassen und einen anderen Host-Port verwenden, z. B. `3020:3000`.
+
+### Datenbank- oder Berechtigungsfehler
+
+Wenn beim Starten im Log ein Fehler wie `permission denied` oder `read-only file system` erscheint:
+
+- Prüfen, ob das Volume korrekt gemountet ist (`./gitea:/data`).  
+- Dateirechte sicherstellen:
+  ```bash
+  chown -R 1000:1000 /gitea
+  chmod -R 755 /gitea
+  ```
+- Container neu starten.
+
+> [!TIP]  
+> UID 1000 entspricht dem Standardbenutzer `git` im Container.  
+> Diese Zuordnung muss stimmen, sonst kann Gitea keine Repositories anlegen.
+
+### Regelmäßige Kontrolle
+
+Damit der Container langfristig stabil bleibt:
+
+- Einmal pro Monat Systemupdates durchführen:  
+  ```bash
+  apt update && apt upgrade -y
+  ```
+- Docker-Container und Volumes regelmäßig prüfen:  
+  ```bash
+  docker ps -a
+  docker system prune
+  ```
+- Backups des Ordners `/gitea` in dein Kopia- oder externes Sicherungssystem einbinden.
+
+> [!TIP]  
+> Eine einfache Routine:  
+> - Monatlich Updates  
+> - Wöchentlich Funktionstest  
+> - Nach jeder Änderung an Repositories ein Backup starten  
+> Damit bleibt deine Gitea-Instanz wartungsarm und jederzeit einsatzbereit.
+
+---
+
+## Troubleshooting & Tipps
+
+Auch wenn Gitea im Normalbetrieb sehr stabil läuft, können während oder nach der Einrichtung kleinere Probleme auftreten.  
+Die folgenden Punkte decken die häufigsten Ursachen ab und zeigen, wie du sie schnell behebst.
+
+### Gitea-Weboberfläche nicht erreichbar
+
+Wenn `https://git.deinedomain.tld` nicht geladen wird oder eine Fehlermeldung wie *Verbindung fehlgeschlagen* erscheint:
+
+1. Prüfe, ob der Container aktiv ist:  
+   ```bash
+   docker ps
+   ```
+   Wenn Gitea nicht angezeigt wird, neu starten:  
+   ```bash
+   docker compose up -d
+   ```
+2. Wenn der Dienst läuft, aber nur per IP erreichbar ist, liegt der Fehler meist am Proxy-Eintrag:  
+   - Im Nginx Proxy Manager prüfen, ob der **Forward-Port** auf `3000` gesetzt ist.  
+   - Gültiges SSL-Zertifikat bestätigen.  
+3. Browser-Cache leeren und Seite erneut aufrufen.
+
+> [!TIP]  
+> Wenn du Gitea erst frisch über HTTPS angebunden hast, kann es bis zu einer Minute dauern, bis der Proxy und das Zertifikat aktiv sind.
+
+### Anmeldung funktioniert, aber Repositories fehlen
+
+Wenn du dich erfolgreich anmeldest, aber keine Repositories angezeigt werden:
+
+- Prüfe in **Site Administration → Benutzer**, ob dein Konto Besitzer oder Mitglied eines Repositories ist.  
+- Bei **privaten Repositories** musst du explizit Berechtigungen vergeben.  
+- Bei Organisationen sicherstellen, dass der Benutzer einem Team mit Zugriffsrechten zugeordnet ist.
+
+> [!NOTE]  
+> Administratoren sehen Repositories nicht automatisch.  
+> Die Rechte müssen pro Projekt oder Organisation vergeben werden.
+
+### Push schlägt fehl
+
+Wenn beim Push-Vorgang eine Fehlermeldung wie  
+`remote: invalid username or password`  
+oder  
+`fatal: Authentication failed`  
+erscheint:
+
+- Prüfe, ob du über **HTTPS mit Token** oder **SSH mit Schlüssel** arbeitest.  
+- Für HTTPS: Im Benutzerprofil unter **Applications → Generate Token** einen neuen Token erzeugen und als Passwort verwenden.  
+- Für SSH: Schlüssel neu hinterlegen (**Profil → SSH Keys → Add Key**) und Verbindung prüfen.
+
+> [!TIP]  
+> Benutzername beim Push ist dein Gitea-Account, Passwort ist der Token.  
+> Tokens können beliebig oft neu erzeugt werden, ohne das Benutzerpasswort zu ändern.
+
+### Fehlerhafte ROOT_URL oder falsche Links
+
+Wenn Repository-Links oder Webhooks noch auf die interne IP zeigen, obwohl HTTPS aktiv ist:
+
+1. Datei `/gitea/gitea/conf/app.ini` öffnen.  
+2. Im Abschnitt `[server]` prüfen:
+   ```
+   ROOT_URL = https://git.deinedomain.tld/
+   ```
+3. Gitea neu starten:
+   ```bash
+   docker compose restart
+   ```
+
+> [!NOTE]  
+> Änderungen an der ROOT_URL werden erst nach dem Neustart wirksam.
+
+### SSH-Verbindung schlägt fehl
+
+Wenn `ssh git@git.deinedomain.tld -p 222` keine Verbindung aufbaut:
+
+- Prüfen, ob im Compose-File der Port `222:22` korrekt gesetzt ist.  
+- Firewall (UFW) prüfen, ob `222` erlaubt ist.  
+- Wenn du SSH nur intern verwenden willst, Portweiterleitung im Router entfernen.  
+
+### Port oder Dienst blockiert
+
+Wenn der Container nicht startet oder „port already in use“ erscheint:
+
+1. Prüfen, ob ein anderer Dienst Port 3000 oder 222 nutzt:
+   ```bash
+   ss -tuln | grep 3000
+   ```
+2. Falls ja, Compose-File anpassen und einen anderen Host-Port verwenden, z. B. `3020:3000`.
+
+### Datenbank- oder Berechtigungsfehler
+
+Wenn beim Starten im Log ein Fehler wie `permission denied` oder `read-only file system` erscheint:
+
+- Prüfen, ob das Volume korrekt gemountet ist (`./gitea:/data`).  
+- Dateirechte sicherstellen:
+  ```bash
+  chown -R 1000:1000 /gitea
+  chmod -R 755 /gitea
+  ```
+- Container neu starten.
+
+> [!TIP]  
+> UID 1000 entspricht dem Standardbenutzer `git` im Container.  
+> Diese Zuordnung muss stimmen, sonst kann Gitea keine Repositories anlegen.
+
+### Regelmäßige Kontrolle
+
+Damit der Container langfristig stabil bleibt:
+
+- Einmal pro Monat Systemupdates durchführen:  
+  ```bash
+  apt update && apt upgrade -y
+  ```
+- Docker-Container und Volumes regelmäßig prüfen:  
+  ```bash
+  docker ps -a
+  docker system prune
+  ```
+- Backups des Ordners `/gitea` in dein Kopia- oder externes Sicherungssystem einbinden.
+
+> [!TIP]  
+> Eine einfache Routine:  
+> - Monatlich Updates  
+> - Wöchentlich Funktionstest  
+> - Nach jeder Änderung an Repositories ein Backup starten  
+> Damit bleibt deine Gitea-Instanz wartungsarm und jederzeit einsatzbereit.
+