Thomas/Homelab--Bratonein-Kontrollzentrum--Tutorial
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Homelab--Bratonein-Kontroll…/Kapitel 13/Free Rohtext.md

27 KiB
Raw Permalink Blame History

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:

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:

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:

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:

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:

mkdir /gitea && cd /gitea
nano docker-compose.yml

Füge folgenden Inhalt ein:

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:

docker compose up -d

Prüfe anschließend den Status:

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:

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:

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:
nano /gitea/gitea/conf/app.ini
  1. 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
  1. Datei speichern (Strg + O, Enter, Strg + X)
  2. Gitea-Container neu starten:
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

# 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:

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):

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:

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

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: 
    docker ps
    Wenn Gitea nicht angezeigt wird, neu starten: 
    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: 
    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: 
    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: 
    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: 
    apt update && apt upgrade -y
  • Docker-Container und Volumes regelmäßig prüfen: 
    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: 
    docker ps
    Wenn Gitea nicht angezeigt wird, neu starten: 
    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: 
    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: 
    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: 
    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: 
    apt update && apt upgrade -y
  • Docker-Container und Volumes regelmäßig prüfen: 
    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.