791 lines
27 KiB
Markdown
791 lines
27 KiB
Markdown
# 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.
|
||
|