Homelab--Bratonein-Kontrollzentrum--Tutorial/Kapitel 15

📝 Kapitel 15 – Git (Self-Hosted mit Gitea)

🎯 Ziel

In diesem Kapitel setzen wir einen eigenen Git-Server mit Gitea auf.
Damit sichern wir unsere Configs, Skripte und Dokumente versioniert und behalten die volle Kontrolle.
Zusätzlich können wir mit GitHub spiegeln – für Hybridbetrieb (intern privat, extern sichtbar).

---

✅ Voraussetzungen

• LXC-Container mit Debian 12 (Bookworm)
• Empfohlen: 1 vCPU, 512 MB – 1 GB RAM, ≥ 5 GB Speicher
• Netzwerkzugang (IPv4/IPv6)
• Optional: Nginx Proxy Manager + DynDNS (für Zugriff von außen)
• In diesem Kapitel installieren wir Docker + Compose

---

1️⃣ Container vorbereiten

apt update && apt upgrade -y
apt install -y curl gnupg lsb-release ca-certificates nano

👉 Damit stellen wir sicher, dass alle Pakete aktuell sind und wir wichtige Tools wie curl und nano haben.

---

2️⃣ Docker & Compose installieren

# Docker GPG-Key hinzufügen
mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Repository hinzufügen
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

# Installation
apt update
apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

👉 Damit haben wir Docker Engine + Docker Compose Plugin installiert.

---

3️⃣ Arbeitsverzeichnis & Compose-File

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

Beispiel docker-compose.yml:

version: "3"

services:
  gitea:
    image: gitea/gitea:latest
    container_name: gitea
    environment:
      - USER_UID=1000
      - USER_GID=1000
    volumes:
      - ./gitea:/data
    ports:
      - "3000:3000"   # Web
      - "222:22"      # SSH
    restart: always

👉 Erklärung:

• USER_UID / USER_GID: sorgt dafür, dass Gitea-Dateien deinem User (ID 1000) gehören.
• 3000:3000: Web-UI erreichbar unter http://<IP>:3000.
• 222:22: Host-Port 222 → Container-Port 22 (SSH). Wichtig für spätere Git-Clone-URLs.

---

4️⃣ Container starten & prüfen

docker compose up -d
docker ps

👉 Jetzt sollte gitea laufen, Ports 3000 und 222 sichtbar.

---

5️⃣ Erstkonfiguration im Browser

Browser öffnen: http://<IP>:3000

Wichtig: Die Werte hier bestimmen URLs, Ports, Dateipfade und Sicherheitsverhalten deiner Instanz. Alles wird in /data/gitea/conf/app.ini gespeichert und ist später änderbar – aber je sauberer jetzt, desto weniger Nacharbeit.

5.1 Datenbankeinstellungen

• Datenbanktyp: SQLite3
  Warum: Für Homelab klein & wartungsarm (keine Extra-DB).
• Pfad (nur bei SQLite): /data/gitea/gitea.db
  Speicherort der DB im gemounteten Datenordner.

Alternativen: MariaDB/PostgreSQL sind für Teams/Größe sinnvoll – dann Host, Port, DB-Name, User, Passwort angeben. Für dieses Kapitel bleiben wir bei SQLite.

---

5.2 Allgemeine / Server-Einstellungen

• Seitentitel: frei (z. B. Bratonien Git)
• Ausführen als (Run User): git
  Vorgabe im Container; nicht ändern.
• Server‑Domain: vorerst IP (z. B. 192.168.1.50), später Subdomain (git.deine-domain.tld) über NPM/DynDNS.
• SSH‑Server‑Port: 222
  Grund: In docker-compose.yml haben wir 222:22 gemappt → Container lauscht auf 22, von außen nutzen wir 222. Wenn du hier 22 einträgst, generiert Gitea falsche Clone‑URLs.
• HTTP‑Listen‑Port: 3000
  Entspricht dem Compose‑Mapping 3000:3000.
• Basis‑URL (App URL): http://<IP>:3000/
  Später auf https://git.deine-domain.tld/ umstellen, wenn NPM/SSL steht.

---

5.3 Pfade & Speicher

• Repository‑Verzeichnis: /data/git/repositories
  Ablage aller Repos (im Volume).
• Git‑LFS‑Wurzelpfad: leer lassen
  LFS = Large File Storage für große Binärdateien. Für Konfigs/Markdown nicht nötig; später aktivierbar.
• Anhänge/Assets (falls angezeigt): Standard belassen – Homelab nutzt selten große Datei‑Uploads über Gitea.

---

5.4 Registrierung, Nutzer & Darstellung

• Öffentliche Registrierung erlauben: empfohlen: aus
  Nur Admin legt Accounts an → kleiner, sicherer Kreis.
• Anmeldung erforderlich, um Seiten zu sehen: optional
  Aktivieren, wenn das komplette UI privat sein soll.
• OpenID‑Anmeldung erlauben: optional
  Ermöglicht SSO‑Login via OpenID; für Homelab meist nicht notwendig.
• OpenID‑Selbstregistrierung erlauben: optional
• Gravatar deaktivieren: an
  Keine externen Avatar‑Anfragen → Datenschutz.
• Föderierte Avatare/Profile: aus
  Nicht erforderlich im Homelab.
• Offline‑Modus: an
  Unterbindet unnötige externe Requests.

---

5.5 E‑Mail (SMTP)

• SMTP‑Host / Port / Benutzer / Passwort / From: leer lassen, wenn kein Mailserver genutzt wird.
  Gitea funktioniert auch ohne SMTP; Passwort‑Reset per Mail geht dann natürlich nicht.
• TLS/STARTTLS: nur konfigurieren, wenn SMTP genutzt wird.
• Versteckte E‑Mail‑Domain: Standard (noreply.localhost) belassen.

Admin‑E‑Mail darf eine Dummy‑Adresse sein (z. B. admin@localhost), wenn kein SMTP vorhanden ist.

---

5.6 Sicherheit

• Passwort‑Hash: pbkdf2 (Standard; sicher & ressourcenschonend)
• Captcha / Registrierungsbestätigung: nur relevant, wenn offene Registrierung aktiv ist; im Homelab meist aus.

---

5.7 Logging

• Log‑Dateipfad: /data/gitea/log
  Bleibt im Volume; einfach zu sichern/prüfen.

---

5.8 Administrator

• Benutzername: z. B. admin
• Passwort: stark wählen
• E‑Mail: admin@localhost (ohne SMTP ok)
• Installieren klicken → Gitea startet mit diesen Werten.

Nach der Installation findest du die Konfig in /data/gitea/conf/app.ini. Änderungen sind dort oder im UI möglich.

---

6️⃣ Erstes Repository in der Web-UI anlegen

Pflicht:

• Besitzer: z. B. admin (oder Organisation)
• Name: testprojekt (klein, mit Bindestrich)
• Sichtbarkeit: privat (Homelab) oder öffentlich (Sharing)

Initialdateien (mit Erklärung):

• README erzeugen: empfohlen → Startseite hat sofort Inhalt.
• .gitignore: bei Codeprojekten sinnvoll (Build/Cache raus); bei reiner Doku optional.
• Lizenz: Content/Leitfaden → CC BY (freie Nutzung mit Namensnennung „Bratonien Tech“).
  Hinweis: Bei echtem Code wäre z. B. MIT üblich.

Erweitert:

• Standardbranch: main (belassen)
• Objektformat: sha1 (belassen)

Pflichtfelder:

• Besitzer: z. B. admin
• Name: testprojekt
• Sichtbarkeit: privat oder öffentlich

Optionale Felder:

• README: hinzufügen (empfohlen)
• .gitignore: optional (bei Codeprojekten)
• Lizenz: für Content → CC BY (Namensnennung „Bratonien Tech“)

Erweitert:

• Standardbranch: main
• Objektformat: sha1

---

7️⃣ Repository per Terminal nutzen

# Lokal initialisieren
mkdir testprojekt && cd testprojekt
git init

# Remote hinzufügen
git remote add origin http://<IP>:3000/admin/testprojekt.git

echo "# Hallo Gitea" > README.md
git add .
git commit -m "Erster Commit"

# Push
git push -u origin master

👉 SSH statt HTTP:

git remote set-url origin ssh://git@<domain-oder-ip>:222/admin/testprojekt.git

(SSH-Key vorher im Gitea-Userprofil hochladen)

---

8️⃣ GitHub-Mirroring

• Pull-Mirror: GitHub → Gitea (Projekte importieren)
• Push-Mirror: Gitea → GitHub (eigene Projekte zusätzlich veröffentlichen)

👉 Einrichtung im Repo unter Settings → Mirroring.

---

⚠️ Typische Stolperfallen

• ❌ SSH-Port falsch: immer 222 eintragen (wegen Mapping)
• ❌ UID/GID falsch: Container kann keine Dateien schreiben → prüfe USER_UID=1000, USER_GID=1000
• ❌ Mailserver leer: unkritisch, Gitea läuft auch ohne Mail
• ❌ Lizenz vergessen: für Content immer CC BY wählen

---

✅ Zusammenfassung

• Gitea läuft im Docker-Container, Daten persistieren in /gitea/gitea
• SSH-Port = 222
• Git LFS bleibt leer
• Erstes Repo → README + CC-BY-Lizenz
• GitHub-Mirroring möglich

Damit haben wir unser eigenes Git-Kontrollzentrum in Bratonien eingerichtet.