Teil 1: Gitea lokal im eigenen Netz betreiben

Ziele

Der Betrieb eines lokalen Gitea-Servers (GIT) ist eigentlich recht einfach und für den lokalen oder privaten Gebrauch völlig ausreichend. Wenn dieser Teil abgeschlossen ist, kann auf einen vollständigen Gitea-Server im lokalen Netzwerk zugegriffen werden.

Zusammenfassend sind folgende Schritte notwendig, um das Ziel dieses ersten Teils zu erreichen:

NEU: Für ganz ungeduldige habe ich einen Konsole only Abschnitt. Da gibts nur Befehle, keine Erklärungen.

Diese einfachste Ausbaustufe des ersten Teils ist NICHT für den öffentlichen Betrieb geeignet!
Der Zugriff erfolgt (noch) nicht über eine verschlüsselte Verbindung. Eine Transportverschlüsselung erfolgt bewusst nicht lokal, da GIT sehr allergisch auf selbstsignierte oder selbstgemachte Zertifikate reagiert. Das funktioniert zwar notfalls, ist aber umständlich.

Letzte Aktualisierung:

  • 05.02.2024: Konsole Abschnitt hinzugefügt
  • 05.01.2024: config Verzeichnis in data migriert, nur ein externes Verzeichnis nötig. gitea generate secret als Ersatz für openssl rand. backup Verzeichnis ergänzt. Kleinigkeiten angepasst.
  • 13.08.2023: Daten- und Konfigurationsspeicherung außerhalb des Jails optional ergänzt
  • 29.07.2023: Update für FreeBSD 13.2 und letzter Feinschliff
  • 20.05.2023: Initiales Dokument

Voraussetzungen für lokalen Betrieb

  • TrueNAS Core oder reiner FreeBSD Server
    • Ein Jail (z.B. mit dem Namen GITEA) ist eingerichtet.
    • SSH ist aktiviert und ein normaler BENUTZERNAME in der "wheel" Gruppe ist angelegt
    • IP Adresse des GITEA Jails ist bekannt (z.B. 192.168.178.103)
    • Hostname des GITEA Jails ist bekannt (z.B. git.domain.local) und per internem DNS erreichbar

Generell sollten solche Dienst in einer eigenen Umgebung eingerichtet werden. Das macht nicht nur die Sicherheit, sondern auch die Wartung wesentlich einfacher. Jails können relativ einfach gesichert werden und es sind nur die Pakete installiert, die absolut notwendig sind.

Begrifflichkeiten

  • USERNAME = SSH Benutzeraccount (root Login ist nicht direkt möglich) mit SU Rechten
  • GITEAIP = IP Adresse des lokalen GITEA Servers
  • GITEAHOSTNAME = Hostname des lokalen GITEA Servers

In diesem Artikel wird so viel wie möglich per Copy'n'Paste ermöglicht/vorbereitet.
Gerade bei längeren Konfigurationen kommt dann so etwas vor:

    cat > DATEINAME.sh << 'EOF'
    BEFEHL1
    BEFEHL2
    BEFEHL3
    'EOF'

Das erzeugt eine Datei mit dem Namen DATEINAME.sh mit dem Inhalt:

    BEFEHL1
    BEFEHL2
    BEFEHL3

Also immer komplett von cat bis EOF kopieren und einfügen!

Diagramm

Damit sieht das Setup lokal so aus:

                                                                  ┌─────────────────────────────┐
                                                                  │ TrueNAS                     │
                                                                  │   192.168.178.100           │
                                                                  │ ┌─────────────────────────┐ │
                                                                  │ │ Git-Jail                │ │
                                                                  │ │   192.168.178.103       │ │
                                                                  │ │                         │ │
                                              LAN: 0.0.0.0:3000 ──┼─┼─► gitea                 │ │
                                                                  │ └─────────────────────────┘ │
                                                                  └─────────────────────────────┘

Optional: Externe Datenverzeichnisse

Die Verzeichnisse /var/db/gitea und /mnt/backup können in eigene Datasets außerhalb des Jails abgelegt werden. Damit sind diese Daten unabhängig vom Jail gespeichert. Ziel ist es, ähnlich wie bei Docker, möglichst wenig vom Jail selber abhängig zu sein. Wenn das Jail aus irgendeinem Grund beschädigt oder gelöscht wurde, sind wir so in der Lage, die vorherige Konfiguration und Daten mit minimalem Aufwand wiederherzustellen. Wie das (generisch) erreicht werden kann, habe ich hier beschrieben.

Dies ist eher für fortgeschrittenen Anwender gedacht, die schon etwas Erfahrung besitzen. Da im Detail drauf einzugehen, würde den Rahmen hier etwas sprengen. Das wichtigste ist aber: Es werden 2 neue Verzeichnisse (Datasets) benötigt, die alles Gitea relevante beinhalten.

└── jails_data
    └── GITEA
        ├── backup # /mnt/backup
        └── data   # /var/db/gitea

Damit zeigt z.B im Jail GITEA das Verzeichnis /var/db/gitea auf das eigentlich extern liegende Verzeichnis /mnt/ZPOOLNAME/jails_data/GITEA/data. Alles klar? Gut!

Jail starten

Login per SSH in das GITEA Jail:
ssh USERNAME@GITEAIP oder ssh USERNAME@GITEAHOSTNAME um mit su root Rechte zu erlangen.

Paketequelle anpassen

Zuvor passen wir die Paketquellen auf die latest an, damit auch wirklich die neueste Pakete bezogen werden

Pakete installieren & Dienste aktivieren

Nun die Paketquelle mit pkg update aktualisieren und dann die benötigten Pakete installieren: pkg install gitea
Dienste aktivieren damit diese beim Start des Jails automatisch mit starten: service gitea enable

Gitea

Konfiguration erstellen

Eigentlich erwartet Gitea seine Konfigurationsdatei in der Datei /usr/local/etc/gitea/conf/app.ini, was aber außerhalb des Gitea Datenverzeichnisses /var/db/gitea/ liegt. Um wirklich alles relevante an einem Ort (und im Backup) zu haben, bedienen wir uns einem Kniff mit symbolischen Links: ln -sf /var/db/gitea/app.ini /usr/local/etc/gitea/conf/app.ini schafft die Verknüpfung zu /usr/local/etc/gitea/conf/app.ini.

Im Vergleich zur mitgelieferten Standard-Konfiguration hat diese mitunter ein paar Änderungen:

  • Indexer für die Volltextsuche ist aktiviert (REPO_INDEXER_ENABLED = true)
  • Gravatar wird deaktiviert (zur Verhinderung von unerwünschte Verbindungen zu Dritten) (DISABLE_GRAVATAR = true)
  • E-Mail Benachrichtigungen etc. bleiben deaktiviert (ENABLED = false)
  • Version und Branding im Footer werden ausgeblendet (SHOW_FOOTER_BRANDING = false)
  • Zugriff per SSH wird deaktiviert und nur HTTP/HTTPS bleiben aktiviert (DISABLE_SSH = true)
  • Zugriff ist nicht nur per localhost möglich (HTTP_ADDR = 0.0.0.0)
cat > /usr/local/etc/gitea/conf/app.ini << 'EOF'
APP_NAME = Gitea
RUN_USER = git
RUN_MODE = prod

[database]
DB_TYPE  = sqlite3
HOST     = 127.0.0.1:3306
NAME     = gitea
PASSWD   =
PATH     = /var/db/gitea/gitea.db
USER     = root
SSL_MODE = disable

[indexer]
ISSUE_INDEXER_PATH = /var/db/gitea/indexers/issues.bleve
REPO_INDEXER_ENABLED = true

[log]
ROOT_PATH = /var/log/gitea
MODE      = file
LEVEL     = Info

[mailer]
ENABLED = false

[oauth2]
JWT_SECRET = GITEAJWTSECRET

[picture]
AVATAR_UPLOAD_PATH      = /var/db/gitea/data/avatars
DISABLE_GRAVATAR        = true
ENABLE_FEDERATED_AVATAR = false

[repository]
ROOT = /var/db/gitea/gitea-repositories
SCRIPT_TYPE = sh
DISABLED_REPO_UNITS = repo.packages,repo.releases
DEFAULT_BRANCH = main

[repository.upload]
TEMP_PATH = /var/db/gitea/data/tmp/uploads

[security]
INSTALL_LOCK = true
INTERNAL_TOKEN = GITEAINTERNALTOKEN
SECRET_KEY   = GITEASECRETKEY

[session]
PROVIDER = file
PROVIDER_CONFIG = /var/db/gitea/data/sessions

[server]
DOMAIN       = GITEAHOSTNAME
HTTP_ADDR    = 0.0.0.0
HTTP_PORT    = 3000
ROOT_URL     = http://GITEAHOSTNAME:3000/
DISABLE_SSH  = false
SSH_DOMAIN   = %(DOMAIN)s
SSH_PORT     = 22
DISABLE_SSH  = true
OFFLINE_MODE = false
APP_DATA_PATH = /var/db/gitea/data

[service]
REGISTER_EMAIL_CONFIRM = false
ENABLE_NOTIFY_MAIL     = false
DISABLE_REGISTRATION   = false
ENABLE_CAPTCHA         = false
REQUIRE_SIGNIN_VIEW    = true

[other]
SHOW_FOOTER_BRANDING = false
SHOW_FOOTER_VERSION = false
SHOW_FOOTER_TEMPLATE_LOAD_TIME = false
'EOF'

Nachträglich werden noch gefüllt:

  • GITEAHOSTNAME, GITEAINTERNALTOKEN, GITEAJWTSECRET und GITEASECRETKEY
sed -i '' 's/GITEAHOSTNAME/'`hostname -f`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAINTERNALTOKEN/'`gitea generate secret INTERNAL_TOKEN`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAJWTSECRET/'`gitea generate secret JWT_SECRET`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEASECRETKEY/'`gitea generate secret SECRET_KEY`'/' /usr/local/etc/gitea/conf/app.ini

Zum Schluss noch die Berechtigung der Konfigurationsdatei mit chown git:git /var/db/gitea/app.ini anpassen

Dienste starten

Damit sind wir nun am Ende der Vorbereitungen angelangt und Gitea wird mit service gitea start gestartet.

Registrierung

Nun erfolgt der erste Aufruf von Gitea, in dem direkt der erste Benutzer registriert wird.

Hierzu mit dem Lieblingsbrowser nun die IP oder Hostname des Gitea Jails aufrufen:
http://GITEAIP:3000 oder http://GITEAHOSTNAME:3000

wilkommen

Dieser erste Benutzer ist dann automatisch auch der Benutzer mit Administrations Rechten
Der Benutzer darf *NICHT admin heissen

registrieren

admin

Nachdem der erste "Admin"-Benutzer erstellt wurde, kann in Betracht gezogen werden, die eigenständige Registrierung zu deaktivieren und dem Admin die Aufgabe zu übertragen, neue Benutzer im System anzulegen. Dazu genügt es in der /var/db/gitea/conf/app.ini den Eintrag DISABLE_REGISTRATION von false auf true zu setzen und den Gitea Dienst mit service gitea restart neu zu starten.

Konsole

pkg install -y gitea
service gitea enable
fetch https://github.com/marzlberger/bsdbox/blob/main/gitea/app.ini -o /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAHOSTNAME/'`hostname -f`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAINTERNALTOKEN/'`gitea generate secret INTERNAL_TOKEN`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEAJWTSECRET/'`gitea generate secret JWT_SECRET`'/' /usr/local/etc/gitea/conf/app.ini
sed -i '' 's/GITEASECRETKEY/'`gitea generate secret SECRET_KEY`'/' /usr/local/etc/gitea/conf/app.ini
service gitea start

Voilá

Damit das ganze auch unterwegs aus genutzt werden kann, wird in Teil 2 erklärt
und für die ersten Schritte mit einem Git wurde ein eigener Artikel gewidmet.