Kapitel 15/README.md aktualisiert
This commit is contained in:
@@ -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://<IP>: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://<IP>: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://<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
|
||||
```bash
|
||||
# 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**:
|
||||
```bash
|
||||
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.
|
||||
|
||||
Reference in New Issue
Block a user