Content
Dateianzeige für gogs (3.4.0)
usr/share/doc/gogs/gogs.txt
Gogs
Gogs ist ein Service, mit dem es moeglich ist, einen mit GitHub ver-
gleichbaren Git Service lokal anzubieten. Der Dienst kann ueber
HTTP und ueber SSH erreicht werden.
Einrichtung
-----------
Das Paket kann vollstaendig ueber die eisfair-Konfiguration einge-
richtet werden. Ueber das Gogs-Web-Frontend ist es dagegen lediglich
moeglich, die aktuelle Konfiguration einzusehen, nicht aber zu ver-
aendern.
Nach der Installation ist der Dienst vorerst inaktiv. Ueber die
eisfair-Konfiguration kann dieser anschliessend konfiguriert und
aktiviert werden. Erst danach ist der Zugriff auf das Web-Frontend
moeglich.
Mittlerweile erlaubt das Paket neben dem Zugriff auf SQLite3 Daten-
banken auch die Verwendung dedizierter Datenbankserver wie MySQL
oder PostgreSQL. Die Datenbank, sowie der Datenbankbenutzer muessen
jedoch vor der Einrichtung des gogs manuell angelegt werden (siehe
Dokumentation GOGS_DB_SERVER_xx fuer zusaetzliche Hinweise). Diese
Art der Installation richtet sich an erfahrene Anwender, waehrend
die Verwendung des internen SQLite Datenbanktreibers auch fuer den
Laien kein Problem darstellen sollte.
Der erste Anwender, der sich nach einer Erstinstallation beim Gogs-
Dienst registriert erhaelt automatisch Administratorrechte. Mittels
dieses Kontos koennen anschiessend alle uebrigen Benutzerrechte ein-
gestellt werden.
Um die Konfiguration des Mailer-Dienstes testen zu koennen gibt es
im Administratormenue des Web-Frontends (unter Konfiguration) die
Moeglichkeit eine Test-E-Mail zu senden. Weitere wertvolle Infor-
mationen erhaelt man aus der Protokolldatei, die der Dienst unter
'/var/log/gogs' anlegt.
Konfiguration
-------------
START_GOGS
Schaltet den Dienst frei. Sobald der Wert auf 'yes' gesetzt wird,
wird gogs beim Aktivieren der Konfiguration und bei jedem
Neustart des Systems automatisch gestartet.
Gueltige Werte: yes, no
Standardwert: START_GOGS='no'
GOGS_APPLICATION_NAME
Name der Gogs-Installation, der beispielsweise einen Firmen-
oder Projektnamen enthalten kann. Dieser Name wird in E-Mails
verwendet, die vom Gogs-Service versandt werden.
Beispiel: GOGS_APPLICATION_NAME='Meine Projekte'
GOGS_REPOSITORY_ROOT
Dies ist das Wurzelverzeichnis, in dem Gogs Dateien ablegt.
In der Hauptsache sind damit die Git-Repositories gemeint, die
mit dem Dienst verwaltet werden. Darueber hinaus werden jedoch
auch noch Avatar-Bilder und Anhaenge von Fehlermeldungen unter-
halb des hier angegebenen Pfades abgelegt.
Beispiel: GOGS_REPOSITORY_ROOT='/srv/gogs'
GOGS_HTTP_PORT
Dies ist der TCP/IP Port, auf dem der eingebaute HTTP-Server
Verbindungsanfragen annimmt. Der Standardwert liegt auf 3000,
kann jedoch auf jeden anderen Port (Beispiel 80) gesetzt werden,
solange keine Kollision mit einem anderen Dienst auftritt.
Beispiel: GOGS_HTTP_PORT='3000'
GOGS_HTTP_ROOT_URL
Hiermit wird die Basis-URL des HTTP-Dienstes eingestellt. Diese
wird beim Klonen von URLs z.B. nach einer Anmeldung verwendet
und sollte die URL darstellen, ueber die Gogs ueber das Netz-
werk erreichbar ist.
Beispiel: GOGS_HTTP_ROOT_URL='http://code.lan.local:3000'
GOGS_USE_DB_SERVER
Es besteht die Moeglichkeit, entweder die in den GOGS-Dienst
integrierte Datenbankimplementierung zu verwenden (SQLite3) oder
einen dedizierten Datenbankserver (MySQL/PostgreSQL) zu verwenden.
Waehrend die Verwendung des integrierten Treibers den Vorteil bietet,
keine weitere Einrichtung zu erfordern, erlaubt die Verwendung eines
Datenbankservers eine Lastverteilung auf verschiedene Server-Instanzen.
Zudem ist im allgemeinen die Effizienz beim Datenzugriff hoeher, wenn
ein dedizierter Datenbankserver verwendet wird.
Zu beachten ist allerdings, dass die Einrichtung einer Installation
mit einem separaten Datenbankserver eine Reihe von Fehlerquellen mit
sich bringt, die es bei der Verwendung der SQLite3 Datenbank nicht
gibt. Im Fall von Problemen kann die Datei '/var/log/gogs/gogs.log'
wertvolle Hinweise liefern.
Beispiel: GOGS_USE_DB_SERVER='no'
GOGS_DB_SERVER_TYPE
Hier wird festgelegt, welcher Datenbankserver verwendet werden soll.
Zur Auswahl stehen 'mysql', 'postgres' und 'mssql' (ungetestet).
Diese Option ist nur dann relevant, wenn GOGS_USE_DB_SERVER auf 'yes'
gesetzt wurde.
Beispiel: GOGS_DB_SERVER_TYPE='postgres'
GOGS_DB_SERVER_DBNAME
Hier wird der Name der Datenbank angegeben, die auf dem Datenbankserver
verwendet werden soll. Diese Datenbank muss zuvor manuell eingerichtet
worden sein. Zudem muss der unter GOGS_DB_SERVER_USER angegebene An-
wender ueber ausreichende Berechtigungen verfuegen, um Datenbankobjekte
wie Tabellen, Indices oder Sequenzen anlegen zu koennen.
Fuer MySQL wird das Datenbank-Backend INNODB benoetigt. Zudem muss die
Zeichenkodierung 'utf8mb4' sein. PostgreSQL wurde mit einer UTF-8
Kodierung erfolgreich getestet.
Diese Option ist nur dann relevant, wenn GOGS_USE_DB_SERVER auf 'yes'
gesetzt wurde.
Beispiel: GOGS_DB_SERVER_DBNAME='gogs'
GOGS_DB_SERVER_HOST
Dies ist der Host-Name der Maschine, auf der der Datenbankserver aus
gefuerht wird. Handelt es sich um eine lokale Installation, ist
'localhost' anzugeben.
Diese Option ist nur dann relevant, wenn GOGS_USE_DB_SERVER auf 'yes'
gesetzt wurde.
Beispiel: GOGS_DB_SERVER_HOST='localhost'
GOGS_DB_SERVER_PORT
Dies ist die Port-Nummer, unter der der Datenbankserver erreichbar
ist. Fuer MySQL ist der Standardwert '3306', PostgreSQL dagegen
verwendet ueblicherweise '5432'.
Diese Option ist nur dann relevant, wenn GOGS_USE_DB_SERVER auf 'yes'
gesetzt wurde.
Beispiel: GOGS_DB_SERVER_PORT='5432'
GOGS_DB_SERVER_USER
Hier wird der login-Name des Anwenders angegeben, der fuer den Zugriff
auf den Datenbankserver verwendet werden soll. Da die Datenbank manuell
einzurichten ist, benoetigt der Anwender keine hoeheren Berechtigungen,
wie beispielsweise das Recht, Datenbanken oder Benutzerkonten anlegen
zu koennen. Es muessen aber ausreichende Berechtigungen vorhanden sein
um innerhalb der unter GOGS_DB_SERVER_DBNAME angegebenen Datenbank
Tabellen, Indices oder andere Datenbankobjekte anlegen zu koennen.
Diese Option ist nur dann relevant, wenn GOGS_USE_DB_SERVER auf 'yes'
gesetzt wurde.
Beispiel: GOGS_DB_SERVER_USER='gogs'
GOGS_DB_SERVER_PASSWD
Mit dieser Option wird das Kennwort angegeben, dass fuer die Anmel-
dung beim Datenbankserver verwendet werden soll.
Diese Option ist nur dann relevant, wenn GOGS_USE_DB_SERVER auf 'yes'
gesetzt wurde.
Beispiel: GOGS_DB_SERVER_PASSWD='geheim'
GOGS_ENABLE_MAILER
Gogs besitzt einen eingebauten Mailer-Dienst, der zum Versand
von E-Mails verwendet werden kann. Hiermit wird festgelegt, ob
dieser Dienst aktiviert werden soll oder nicht.
Beispiel: GOGS_ENABLE_MAILER='yes'
GOGS_MAILER_HOST
Hier wird der Namen und die Port-Nummer des SMTP-Servers ange-
geben, ueber den E-Mails versandt werden sollen. Es ist dabei zu
beachten, dass Gogs lediglich SMTP mit STARTTLS unterstuetzt.
Beispiel: GOGS_MAILER_HOST='securesmtp.t-online.de:587'
GOGS_MAILER_USER
Anmeldenamen, mit dem sich der Mailer beim SMTP-Server zu authen-
tifizieren hat. Haeufig ist dies eine E-Mail-Adresse.
Beispiel: GOGS_MAILER_USER='my_name@provider.de'
GOGS_MAILER_PASSWD
Hier wird das Kennwort hinterlegt, das zur Anmeldung am SMTP-
Server verwendet werden soll.
Beispiel: GOGS_MAILER_PASSWD='geheim'
GOGS_MAILER_VERIFY
Beim Versand von E-Mails kann es insbesondere bei der Pruefung
selbstsignierten Zertifikaten zu Problemen fuehren. Wird diese
Option auf 'no' gestellt, wird die Zertifikatspruefung ausgelassen.
Beispiel: GOGS_MAILER_VERIFY='no'
GOGS_MAILER_SUBJECT_PREFIX
Das hier angegebene Praefix wird dem eigentlichen E-Mail Subject
vorangestellt und kann dazu verwendet werden, E-Mails, die vom
Gogs Service versandt wurden, einfacher identifizieren, suchen und
filtern zu koennen.
Beispiel: GOGS_MAILER_SUBJECT_PREFIX='[GOGS]'
GOGS_MAILER_FROM
Hier wird die E-Mail-Adresse angegeben, die beim Verstand von
E-Mails in die 'From:'-Zeile eingetragen werden soll. Diese
Adresse muss kompatibel zu dem in RFC 5322 festgelegten Format
sein.
Beispiel: GOGS_MAILER_FROM='John Doe '
GOGS_ENABLE_REGISTRATION
Diese Option legt fest, ob es Anwendern erlaubt sein soll, sich
selbst beim Gogs-Dienst als Benutzer zu registrieren. Ist die
Option auf 'no' gesetzt, dann koennen Benutzerkonten nur durch
den Administrator angelegt werden.
Hieweis: Unmittelbar nach der Installation solte die Option
auf 'yes' gesetzt werden, damit sich der Administrator einmalig
registrieren kann. Anschliessend besteht dann die Moeglichkeit
die Einstellung zu aendern.
Beispiel: GOGS_ENABLE_REGISTRATION='yes'
GOGS_REQUIRE_LOGIN
Ist diese Option auf 'yes' gesetzt, dann ist eine Benutzeran-
meldung zwingend erforderlich, um auf andere Seiten des Dienstes
zuzugreifen. Der Anwender wird automatisch auf die Anmeldeseite
umgeleitet, solange keine korrekte Anmeldung durchgeführt wurde.
Ist die Option auf 'no' gesetzt, sind die Daten, die von Gogs an-
geboten werden, auch fuer nicht angemeldete Personen sichtbar.
Beispiel: GOGS_REQUIRE_LOGIN='no'
GOGS_EMAIL_CONFIRM
Hiermit kann eingestellt werden, dass fuer eine erfolgreiche
Benutzerregistrierung eine Bestaetigung per E-Mail erforderlich
sein soll. Dies ist jedoch nur dann moeglich, wenn zuvor der
Mailer-Dienst aktiviert und korrekt konfiguriert wurde.
Beispiel: GOGS_EMAIL_CONFIRM='no'
GOGS_EMAIL_NOTIFY
Sollen Beobachter von Projekten per E-Mail ueber Aenderungen
oder neue Fehlerberichte benachrichtigt werden, dann kann diese
Option auf 'yes' gestellt werden. Dies ist nur dann moeglich,
wenn zuvor der Mailer-Dienst aktiviert und korrekt konfiguriert
wurde.
Beispiel: GOGS_EMAIL_NOTIFY='no'
GOGS_PROXY_APACHE2_SUB_URL
Diese Option aktiviert eine Reverse-Proxy-Konfiguration fuer den
Webserver 'apache2', die ueber eine sub-URL erreicht werden kann.
Es ist dabei zu beachten, dass die erforderlichen Informationen
der Konfigurationsoption GOGS_HTTP_ROOT_URL entnommen werden.
Diese muss das folgende Format besitzen und darf keine Port-
Angabe enthalten:
OGS_HTTP_ROOT_URL='http:///'
=========
Beispiel: GOGS_PROXY_APACHE2_SUB_URL='no'
GOGS_PROXY_APACHE2_VHOST
Diese Option aktiviert eine Reverse-Proxy-Konfiguration fuer den
Webserver 'apache2', die ueber eine vhost-Adresse erreicht werden
kann.
Es ist dabei zu beachten, dass die erforderlichen Informationen
der Konfigurationsoption GOGS_HTTP_ROOT_URL entnommen werden.
Diese muss das folgende Format besitzen und darf keine Port-
Angabe enthalten:
OGS_HTTP_ROOT_URL='http://'
===============
Beispiel: GOGS_PROXY_APACHE2_VHOST='no'
GOGS_GIT_CONFIG_SSLVERIFY
Falls gogs dazu verwendet werden soll, ein entferntes Respitory
als Mirror ueber HTTPS zu synchronisieren, kann es erforderlich
sein, die SSL Pruefung von git zu deaktivieren. Das ist insbesondere
dann er Fall, wenn der entfernte Server ein selbstsigniertes
Zertifikat verwendet.
Beispiel: GOGS_GIT_CONFIG_SSLVERIFY='yes'
Weiterfuehrendes
----------------
Gegenwaertig kann man entweder eine einfache Reverse-Proxy Konfiguration
auf der Basis einer Sub-URL bzw. auf der Basis eines virtuellen Hostein-
trags für den Web-Server Apache2 zu erstellen. Falls diese Anwendungs-
faelle nicht passend sind, muss die Aenderung an der Konfiguration des
Web-Servers manuell vorgenommen werden. Die folgende Seite gibt Auskunft
darueber, wie das fuer den jeweiligen Web-Server zu bewerkstellingen
ist:
https://gogs.io/docs/intro/faqs