diff --git a/Kapitel 15/README.md b/Kapitel 15/README.md index 77eff47..6019bef 100644 --- a/Kapitel 15/README.md +++ b/Kapitel 15/README.md @@ -1,106 +1,255 @@ -# 📘 Kapitel 15: Git (Self-Hosted mit Gitea) +# 📝 Kapitel 15 – Git (Self-Hosted mit Gitea) -**Ziel:** Ein eigenes Git-System mit **Gitea** im LXC via Docker aufsetzen, vollstĂ€ndig konfigurieren, erstes Repository anlegen (Web-UI + Terminal) und **GitHub-Mirroring** nutzen – fĂŒr **Datenhoheit** und **Hybridbetrieb** (Self-Hosted + GitHub). +## 🎯 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: **Debian 12 (Bookworm)** -- Empfohlen: **1 vCPU**, **512 MB–1 GB RAM**, **≄ 5 GB** Speicher -- Netzwerk: IPv4/IPv6 -- Optional fĂŒr externen Zugriff: **Nginx Proxy Manager** + **DynDNS** (siehe eigene Kapitel) +- 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** --- -## đŸ§© Was wir aufbauen -- **Container:** `gitea/gitea:latest` -- **Ports:** `3000:3000` (Web), `222:22` (SSH in Container → Host nutzt **222**) -- **Persistenz:** Volume `./gitea:/data` → Daten liegen auf dem Host unter **`/gitea/gitea`** -- **Rechte:** `USER_UID=1000`, `USER_GID=1000` (Dateien gehören deinem Standard-User) - ---- - -## đŸ—ș Kapitelablauf (KurzĂŒberblick) -1. System vorbereiten (Update, Tools) -2. **Docker & Compose** installieren -3. Arbeitsverzeichnis **`/gitea`** anlegen, `docker-compose.yml` schreiben -4. Container starten & prĂŒfen (`docker compose up -d`, `docker ps`) -5. **Erstkonfiguration im Browser** – alle Felder, inkl. **SSH-Port 222** & **LFS leer** -6. **Repository in der Web-UI** anlegen (mit **README**, **Lizenz** = **CC BY** fĂŒr Content) -7. Lokales Repo initialisieren & pushen (Terminal) -8. **GitHub-Mirroring** (Pull- & Push-Mirror) - ---- - -## 🔧 Kerneinstellungen (wichtig!) -- **SSH-Port:** In Gitea **222** eintragen - > Hintergrund: In Compose ist `222:22` gemappt → Container lauscht auf 22, von außen nutzt du 222. -- **LFS:** **leer lassen** (Large File Storage nur fĂŒr große BinĂ€rdateien nötig) -- **UID/GID:** `USER_UID=1000`, `USER_GID=1000` → korrekte Dateirechte auf dem Host - ---- - -## 🌐 Erstkonfiguration (Setup-Formular) -**Datenbank** -- Typ: `SQLite3` · Pfad: `/data/gitea/gitea.db` - -**Allgemein** -- Seitentitel: frei (z. B. *Bratonien Git*) -- Repo-Verzeichnis: `/data/git/repositories` -- Git-LFS-Wurzelpfad: **leer lassen** -- AusfĂŒhren als: `git` -- Server-Domain: vorerst IP, spĂ€ter Subdomain (NPM + DynDNS) -- **SSH-Server-Port:** **222** - -**Netzwerk** -- HTTP-Port: `3000` -- Basis-URL: `http://:3000/` (spĂ€ter `https://git.deine-domain.tld` via NPM) - -**Logs** -- Pfad: `/data/gitea/log` - -**Optionen (Homelab-Empfehlung)** -- ✅ Offline-Modus · ✅ Gravatar aus · ❌ Föderation aus -- 🔒 Registrierung **deaktivieren** (Admin lĂ€dt Nutzer ein) – optional -- OpenID nach Bedarf - -**E-Mail** -- FĂŒr Homelab meist **leer** (kein SMTP nötig) -- Admin-E-Mail: Dummy (z. B. `admin@localhost`) reicht ohne Mailserver - -**Sicherheit** -- Passwort-Hash: `pbkdf2` (Standard) - -**Admin-Benutzer** -- Benutzername/Passwort setzen · **Installieren** - ---- - -## 🆕 Repository ĂŒber die Web-UI anlegen (mit Substanz) -**Pflichtfelder** -- **Besitzer:** dein User (z. B. `admin`) oder eine Organisation -- **Repo-Name:** kurz, kleinschreibung-mit-bindestrich (z. B. `testprojekt`) -- **Sichtbarkeit:** *privat* (Homelab) oder *öffentlich* (Beispiel/Sharing) - -**Initialdateien – wann sinnvoll?** -- **README:** erzeugen → Startseite hat sofort Inhalt (**empfohlen**) -- **.gitignore:** bei Codeprojekten sinnvoll (Build/Cache raus) · bei reinen Markdown/Configs optional -- **Lizenz:** - - **Content/Leitfaden:** **CC BY** (freie Nutzung mit Namensnennung „Bratonien Tech“) - - (Bei echtem Software-Code wĂ€re z. B. **MIT** ĂŒblich) - -**Erweitert** -- Standardbranch: `main` · Objektformat: `sha1` (beides belassen) - ---- - -## đŸ’» Lokales Repo pushen (HTTP & SSH) +## 1ïžâƒŁ Container vorbereiten ```bash -# Beispiel HTTP +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 +```bash +# 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 +```bash +mkdir /gitea && cd /gitea +nano docker-compose.yml +``` + +**Beispiel `docker-compose.yml`:** +```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" # 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://:3000`. +- `222:22`: Host-Port 222 → Container-Port 22 (SSH). Wichtig fĂŒr spĂ€tere Git-Clone-URLs. + +--- + +## 4ïžâƒŁ Container starten & prĂŒfen +```bash +docker compose up -d +docker ps +``` +👉 Jetzt sollte `gitea` laufen, Ports `3000` und `222` sichtbar. + +--- + +## 5ïžâƒŁ Erstkonfiguration im Browser +Browser öffnen: `http://: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://: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 +```bash +# Lokal initialisieren mkdir testprojekt && cd testprojekt git init + +# Remote hinzufĂŒgen git remote add origin http://: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**: +```bash +git remote set-url origin ssh://git@: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.