Forgejo anpassen

Seit der letzten Blog-Serie zu Gitea vor über 5 Jahren ist einiges an Zeit vergangen.¹ Inzwischen hat Gitea mit Forgejo einen leistungsstärkeren Fork erhalten,² der längst Einzug in meine Praxis gefunden hat. Da ich unlängst meine Gitea Instanz als Jail auf der TrueNAS stilllegte,³ beschreibe ich heute, wie ich stattdessen eine Forgejo-Instanz an die eigenen Bedürfnisse angepasst habe.

Nur informatorisch der Hinweis: Aus Einfachheit schreibe ich nur von Forgejo. Mir ist bekannt, dass vieles bei Forgejo und Gitea (noch) identisch ist. Es sollte aber klar sein, dass seit der Forgejo Version 10 diese kein Soft-Fork mehr ist.⁴ Langfristig entwickeln sich beide immer weiter auseinander.

Das grundlegende Anpassungskonzept

Forgejo verfolgt ein klares Konzept. Viele Funktionen, die ich früher in Gitea nur über CSS- oder JavaScript Hacks lösen konnte, wie beispielsweise eine Mermaid Integration⁵ oder eine offline CSP,⁶ sind inzwischen integriert.

Alles, was vom Standard abweicht, landet von der Go Single-Binary unabhängig im Custom-Unterverzeichnis im WORK_PATH in /var/lib/forgejo/custom. Das erleichtert Updates erheblich, ohne etwas selbstkompilieren zu müssen. Ein weiterer Vorteil: Die Inhalte des Custom-Verzeichnisses können ihrerseits komplett in ein Git-Repo wandern.

Wer den Static-Page-Generator Hugo⁷ kennt, dem werden die TOML⁸-Templates und das Go-Scripting vertraut vorkommen. Auch das Konzept aus mehrere Templates und Seiten-Komponenten am Ende eine Website zu bilden ist nahezu identisch. Fast wie vor 30 Jahren die häufig eingesetzten Server Side Includes (SSI).⁹

Die APP.INI als erste Schicht

Forgejo bringt in der APP.INI eine Menge Schalter mit, die für ein UI-Grundanpassung ausreichend sind. Logos austauschen, Links anpassen, Registrierungsoptionen verändern, das alles ist bestens dokumentiert.¹⁰

Interessant wird es, sobald man über die Einstellungen in der APP.INI hinaus möchte: Eine komplett leere Startseite zum Beispiel, ein Footer nur mit Impressum und Sprachauswahl, eigenen Logos und Themes im Corporate-Design ohne sichtbare Forgejo- oder Gitea-Eigenwerbung.

Custom- und Public-Verzeichnis als zweite Schicht

Forgejo lädt bei Programmstart automatisch alle Vorlagen im Custom-Verzeichnis und überschreibt mit diesen seine Defaults. Das eröffnet sehr viel mehr Freiheiten als die festen Einstellungen der APP.INI.

Eine Sonderrolle spielt der Ordner /custom/public. Das ist der Bereich für statische Dateien, die von Forgejo wie von einem Webserver ausgeliefert werden. Alles an Bildern, CSS und JavaScripts aber auch die SECURITY.TXT¹¹ oder das RFC 8615 .well-known Verzeichnis¹² gehören hierhin, sofern nicht zuvor von einem Reverse Proxy behandelt.

Spannender wird es im /custom/templates Verzeichnis. Hier kommen die TOML-Templates zur Steuerung der kompletten UI. Abhängig vom Unterordner/Dateinamen referenziert man so einzelne Ansichten.¹³

Beispiel

Obwohl ich auf Codeberg einige meiner Projekte veröffentliche,¹⁴ befindet sich nach wie vor die Mehrzahl in der geschützten, eigenen Instanz.¹⁵ Diese soll möglichst minimalistisch ohne den Forgejo Hero-Banner und der Eigenwerbung auf der Startseite sein:

Das erreicht man mit der Datei home.tmpl im Custom-Unterordner, wo ich nur den Header und den Footer einblende:

{{template "base/head" .}}
{{template "base/footer" .}}

Den Footer selbst wollte ich ohne technische Infos wie Ladezeit, Versionsnumer und Swagger-API Link haben. Dafür aber mit einer Verlinkung zum eigenen Impressum. Das erreicht man mit der Datei footer_content.tmpl im Unterordner templates/base. Wichtig ist, dass man die identischen CSS-Klassen und Platzhalter-Abfragen sowie die Spracheinstellungen beibehält. In meinem Fall habe ich das Standard-Template aus dem Codeberg-Repo von Forgejo genommen, aus diesem die Lizenz- und Swagger-API Links entfernt und in mein Custom-Verzeichnis eingefügt.¹⁶

Fazit

Forgejo ist für mich ein unverzichtbarer Bestandteil für jede Softwareentwicklung, Dokumentation und Automatisierung im Operations. Die Nutzung von Git ist zentrale Heuristik der Digitalisierung.¹⁷

Und es gibt im Jahr 2025 erschreckend viele, die ohne Versionsverwaltung Software- und Digitalisierungsprojekte versuchen zu stemmen.

In diesem Sinne,
Euer Tomas Jakobs