Gitea ist ein Fork von Gogs, welcher entstanden ist, da viele Contributor unzufrieden über die Hierarchie waren, dass lediglich der Hauptentwickler der einzige Maintainer ist. Gitea besitzt eine wachsende Community, die aktiv Code beisteuert und mittlerweile über 1.000 Commits mehr aufweißt als Gogs.

Gitea benötigt eine Datenbank, ich verwende MariaDB/MySQL. Außerdem wird git selbst und go benötigt. Ich installiere gitea aus dem AUR, so werden die fehlenden Abhängigkeiten gleich mit installiert. Ein weiterer Vorteil besteht darin, dass die entsprechenden Berechtigungen für benötigte Verzeichnisse gleich mit gesetzt werden und wir uns nicht darum kümmern müssen.

$ yaourt -S gitea

Ist die Installation abgeschlossen, legen wir als nächstes die Datenbank an:

$ mysql -u root -p
> CREATE DATABASE `gitea` DEFAULT CHARACTER SET `utf8mb4` COLLATE `utf8mb4_general_ci`;
> CREATE USER `gitea`@'localhost' IDENTIFIED BY 'SECRETPASSWORD;
> GRANT ALL PRIVILEGES ON `gitea`.* TO `gitea`@`localhost`;
> EXIT

nginx verwenden wir als Reverse Proxy, um den go-Server auszuliefern. Dazu den folgenden server-Block in die nginx.conf einfügen:

/etc/nginx/nginx.conf

    server {
        listen 443 ssl http2;
        listen [::]:443 ssl http2;
        server_name git.domain.tld;

        client_max_body_size 50M;

        ssl_certificate /etc/letsencrypt/live/domain.tld/fullchain.pem;
        ssl_certificate_key /etc/letsencrypt/live/domain.tld/privkey.pem;
        ssl_trusted_certificate /etc/letsencrypt/live/domain.tld/fullchain.pem;

        location / {
            proxy_pass http://localhost:3000;
            proxy_set_header Host $host;
            proxy_set_header X-Real-IP $remote_addr;
            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
            proxy_set_header X-Forwarded-Proto $scheme;
        }

        location ~ '/.well-known/acme-challenge' {
            default_type "text/plain";
            root /tmp/letsencrypt;
        }
    }

Die Konfiguration verschiedener Parameter kann sowohl beim ersten Ausführen der Webseite erfolgen, als auch mittels der während der Installation erstellten Datei /etc/gitea/app.ini. Ich entscheide mich für letzteres und ändere folgende Werte, bzw. stelle sicher, dass sie korrekt gesetzt sind:

/etc/gitea/app.ini

[repository]
DISABLE_HTTP_GIT = true
[server]
DOMAIN = git.domain.tld
ROOT_URL = https://git.domain.tld/
DISABLE_SSH = false
SSH_PORT = 22222
SSH_ROOT_PATH = /home/git/.ssh
[database]
DB_TYPE = mysql
HOST = 127.0.0.1:3306
NAME = gitea
USER = gitea
PASSWD = SECRETPASSWORD
[session]
COOKIE_SECURE = true

Dabei verwenden wir im Abschnitt [database] die zuvor beim Anlegen der Datenbank verwendeten Werte.

Für SSH_PORT den Port verwenden, der für den SSH-Server verwendet wird. Dieser sollte mit dem Wert in der /etc/ssh/sshd_config übereinstimmen, die wir im Folgenden modifizieren, wobei AuthorizedKeysFile .ssh/authorized_keys und AllowUsers git relevant sind:

/etc/ssh/sshd_config

Port 22222
AuthorizedKeysFile .ssh/authorized_keys
PermitUserEnvironment yes
PermitRootLogin no
PasswordAuthentication no
PermitEmptyPasswords no
PubkeyAuthentication yes
PrintMotd no
AllowUsers OTHER_USERS git

Sofern der Benutzer git noch nicht existiert, legen wir ihn mitsamt zugehöriger Gruppe an. Bei mir existierte der Benutzer bereits, womöglich durch die Installation von git selbst.

# groupadd --system git
# useradd --system -c 'Git' -g git -m -d /home/git -s /bin/bash git

Sollte der Benutzer schon existieren, aber das Home-Verzeichnis nicht, lässt sich mittels

$ grep git /etc/passwd | cut -d ":" -f6

überprüfen, ob ihm ein Home-Verzeichnis zugeteilt ist. Sollte dabei / als Verzeichnis auftauchen, sollte ihm /home/git zugewiesen werden:

# usermod -d /home/git git

Das Home-Verzeichnis selbst können wir mit

# mkhomedir_helper git

anlegen. Sollte der Benutzer nicht der Gruppe git angehören, was sich mit groups git überprüfen lässt, so wird diese mit

# usermod -aG git git

hinzugefügt.

Wichtig: Damit der SSH-Zugriff über diesen Benutzer funktioniert, muss er ein Passwort besitzen. Sollte dies nicht der Fall sein, kann ihm mittels

# passwd git

ein Passwort zugewiesen werden.

Damit sollte fast alles vorbereitet sein. Bevor wir jedoch den Service starten, ändern wir noch eine Kleinigkeit in der Datei /usr/lib/systemd/system/gitea.service.

Aufgrund der Konfiguration und den gesetzten Umgebungsvariablen durch die Installation ist es nicht möglich, ein custom-Verzeichnis unter /var/lib/gitea zu verwenden. Es wird schlicht ignoriert. Stattdessen sucht Gitea im Verzeichnis des installierten Binaries, also unter /usr/bin/custom. Um dies zu korrigieren, muss gitea die Umgebungsvariable GITEA_CUSTOM mit auf den Weg gegeben werden. Dazu die eben genannte Datei öffnen und am Ende des [Service]-Blocks die folgende Environment Zeile einfügen:

/usr/lib/systemd/system/gitea.service

[Service]
...
Environment=GITEA_CUSTOM=/var/lib/gitea/custom

So kann Gitea bedenkenlos angepasst werden und Dateien werden nach einem Update nicht überschrieben.

Nun ist alles bereit und wir können die geänderten Konfigurationen laden sowie Gitea selbst starten:

# systemctl restart nginx
# systemctl restart sshd
# systemctl start gitea

Hat alles geklappt, können wir Gitea mit

# systemctl enable gitea

automatisch starten lassen. Wir sollten beim Aufruf von https://git.domain.tld automatisch zu https://git.domain.tld/install weitergeleitet werden. Dort ergänzen wir die fehlenden Informationen und passen die Konfiguration unseren Wünschen an. Dabei muss zumindest das Passwort für die MySQL-Datenbank eingegeben werden, um die Formulardaten absenden zu können.

Soltle ein 502 Bad Gateway erscheinen, könnte es ein Problem beim Starten von Gitea gegeben haben. Dazu mit systemctl status gitea sehen, ob der Prozess läuft, oder via journalctl -xe herausfinden, was das Problem ist.

Ist die Einrichtung abgeschlossen, sollten wir zur Login-Seite weitergeleitet werden. Wurde im vorherigen Schritt kein Administrator angelegt, so wird der erste registrierte Benutzer automatisch Administrator. Jetzt muss nur noch der gewünschte Benutzeraccount registriert werden und wir können Gitea verwenden.

Um den SSH-Zugriff für einen Benutzer zu aktivieren, muss dieser lokal ein neues SSH-Schlüsselpaar generieren, sofern er noch keins besitzt. Der Inhalt der erzeugten Datei ~/.ssh/id_rsa.pub muss in den Einstellungen des Benutzers unter SSH / GPG Schlüssel als neuer SSH-Schlüssel hinzugefügt werden.

Um zu testen, ob der SSH-Zugriff funktioniert, muss als erstes wie gerade beschrieben ein öffentlicher Schlüssel hinterlegt sein. Ist dies der Fall, kann lokal mittels

$ ssh -p PROTNUMMER git@git.domain.tld

versucht werden, sich via SSH zu authentifizieren. Falls als Ausgabe

Hi there, You've successfully authenticated, but Gitea does not provide shell access.
If this is unexpected, please log in with password and setup Gitea under another user.

erscheint, hat alles funktioniert und der SSH-Zugriff ist gewährleistet.

Sollte dies nicht funktionieren, kann mit -v eine erweiterte Ausgabe von Debug-Meldungen erzwungen werden.

Möglichkeiten, warum der Zugriff nicht funktioniert, können sein:

• Die Berechtigungen für die SSH-Dateien sind zu großzügig und die Verwendung wird abgelehnt.
• Der falsche SSH-Schlüssel wird verwendet. Dazu kann es sinnvoll sein, lokal die ~/.ssh/config zu modifiezieren:

~/.ssh/config

    Host git.domain.tld
        HostName git.domain.tld
        User git
        IdentityFile ~/.ssh/id_rsa.git  # privater Schlüssel zu dem bei Gitea hinterlegten öffentlichen Schlüssel
        IdentitiesOnly yes
    

• Dem Benutzer git ist auf dem Server kein Passwort zugewiesen, s. Benutzer anlegen.

Letzteres kann sich beispielsweise darin äußern, dass scheinbar alles korrekt konfiguriert ist, allerdings beim Versuch des Verbindungsaufbaus (Ausgaben mit ssh […] -v)

debug1: Offering public key: RSA SHA256:<random_looking_characters> /home/USER/.ssh/id_rsa.git
…
debug1: No more authentication methods to try.
git@git.domain.tld: Permission denied (publickey).

zurückgeliefert wird. Dabei kann es sinnvoll sein, einen Blick in die Logs auf dem Server zu werfen, in diesem Fall

# journalctl -xe

wobei

TIMESTAMP HOSTNAME sshd[PID]: User git not allowed because account is locked

einen Hinweis darauf liefert, dass der Benutzer-Account wegen beispielsweise eines fehlenden Passworts nicht berechtigt ist, Verbindungen via SSH aufzubauen.

Arch Linux verwendet noch den alten 10.1 Versionszweig von MariaDB, da die neue Version 10.2 aufgrund von größeren Änderungen an Bibliotheksnamen und Strukturänderungen von Datentypen zu weitreichenden Problemen mit anderen Programmen führt. Das Problem beim Update auf Gitea 1.5 ist, dass MariaDB in der alten Version andere kleinere Datentypen verwendet, weswegen die Datenbankmigrationen im Zuge des Updates vermeintlich zu viel Platz beanspruchen. Dies macht sich in den Log-Dateien von Gitea unter /var/log/gitea/gitea.log bemerkbar:

2018/08/21 13:37:00 [I] Migration: Reformat and remove incorrect topics
2018/08/21 13:37:00 [I] This migration could take up to minutes, please be patient.
2018/08/21 13:37:00 […itea/routers/init.go:60 GlobalInit()] [E] Failed to initialize ORM engine: migrate: do migrate: Sync2: Error 1071: Specified key was too long; max key length is 767 bytes

Das Problem lässt sich recht einfach lösen, indem man die Option innodb_large_prefix aktiviert, welche die Beschränkung auf 767 Bytes, die in der Fehlermeldung auftaucht, aufhebt. Um dies zu aktivieren, muss eine MySQL Shell gestartet werden und die Option aktiviert werden:

$ mysql -u root -p
> set global innodb_large_prefix = `ON`;
> exit;

Wird nun Gitea mittels sudo systemctl restart gitea.service neugestartet, schlägt die Migration nicht mehr fehl und der Service kann wieder verwendet werden.