Kapitel 13/Free Rohtext.md hinzugefügt

2025-10-16 14:27:36 +00:00
parent 6dc87c63a0
commit 8a23cb499f
1 changed files with 790 additions and 0 deletions
--- a/Rohtext.md
+++ b/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.