diff --git a/Kapitel 13/Free Rohtext.md b/Kapitel 13/Free Rohtext.md new file mode 100644 index 0000000..f2e3f14 --- /dev/null +++ b/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://: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://:3000`) + +### Schritt 6 – Erstkonfiguration im Browser + +Öffne im Browser die Adresse deines Containers: + +``` +http://: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://: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@: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://: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. +