GitWeb - Instalacja i podstawy konfiguracji

Popularne usługi, z których korzysta wielu programistów, takie jak GitHub czy GitLab zawierają niezliczoną ilość skomplikowanych funkcji, które mają być przydatne przy obcowaniu z kodem. Często nauka obsługi samego interfejsu czy specyficznych sposobów logowania chwilę zajmuje. Niewielu deweloperów zdaje sobie jednak sprawę, że sam w sobie Git zawiera wbudowany interfejs webowy, który może posłużyć jako minimalistyczny zamiennik, jeśli chcesz po prostu udostępniać kod innym ludziom z własnego serwera w prosty i minimalistyczny sposób.

W tym poradniku pokażę proces instalacji i konfiguracji serwera Git z interfejsem webowym GitWeb. Będę starał się wyjaśniać każdy krok, jaki podejmuję, żebyś zrozumiał, co i dlaczego robię. Zachęcam do przeczytania całego tekstu, zamiast bezmyślnego kopiowania kodu. Jeśli nie jesteś zainteresowany interfejsem, możesz swobodnie zatrzymać się w pewnym momencie poradnika i korzystać z Gita przez terminal. Będę pracował na świeżej instalacji systemu operacyjnego Debian 12 na VPSie. Wybór dostawcy, uruchomienie i zalogowanie się na VPSa przez ssh oraz ustawienie rekordów A (i potencjalnie AAAA) pozostawiam Tobie. Zakładam też, że znasz podstawy obsługi systemu Linux przez terminal i potrafisz obsługiwać między innymi edytor tekstu, ssh, sudo, cd, ls;

Instalacja serwera Git

Zacznijmy od instalacji wszystkich pakietów, które będą nam potrzebne:

apt install git gitweb apache2 certbot python3-certbot-apache

Git jest oczywiście systemem kontroli wersji, a gitweb pakietem, który zawiera sam w sobie interfejs webowy. apache2 jest serwerem webowym, który będzie odpowiadał za (w uproszczeniu) wysyłanie interfejsu użytkownikom przeglądarek, kiedy odwiedzą twoją stronę. Certbot jest skryptem organizacji LetsEncrypt, która wystawia darmowe certyfikaty SSL. Pozwolą one na szyfrowanie ruchu do twojego interfejsu webowego. python3-certbot-apache jest z kolei rozwinięciem certbot, które automatycznie konfiguruje Apache pod wystawiony certyfikat.

Następnie stwórzmy użytkownika git:

useradd -m git -d /var/git -s /bin/bash

Parametry polecenia useradd oznaczają kolejno:

-m, stwórz katalog domowy dla użytkownika

-d, wskaż ścieżkę katalogu domowego

-s, shell wykorzystywany przez użytkownika

Jeśli jesteś zalogowany na swoim serwerze jako root, możesz stać się użytkownikiem git wpisując:

su -l git

Jeśli nie jesteś akurat zalogowany na konto administratora (root), możesz najpierw się nim stać wpisując:

# Stań się administratorem
sudo su

# Stań się użytkownikiem git bez konieczności wpisywania hasła
su -l git

Możesz także ustawić oddzielne hasło dla użytkownika git i po prostu zalogować się na jego konto. Pamiętaj, że hasło każdego użytkownika na twoim serwerze powinno być różne i wygenerowane przez twój menadżer haseł.

# Ustaw hasło dla użytkownika git (spowoduje konieczność wpisania hasła)
sudo passwd git

# Zaloguj się na konto użytkownika git (spowoduje konieczność wpisania tego samego hasła)
su -l git

Opcja -l powinna przenieść nas do katalogu domowego użytkownika. Można też skorzystać z komendy cd /var/git.

Tworzenie repozytoriów

Możemy wygenerować puste repozytorium korzystając z polecenia poniżej:

git init --bare repo.git

Zamień repo na własną nazwę i powtórz to polecenie dla każdego repozytorium, które chcesz przesłać na swój serwer Git. Dodawanie końcówki “.git” jest tradycją, a nie koniecznością.

Git korzysta z ssh, aby nawiązać połączenie, dlatego bardzo dobrym pomysłem jest korzystanie z kluczy ssh. Dzięki temu wpisywanie hasła użytkownika git nie będzie konieczne za każdym razem, kiedy będziesz chciał zsynchronizować lokalne zmiany z serwerem. Jeśli nie posiadasz kluczy ssh i nie chcesz ich generować, przejdź do następnej sekcji. Jeśli posiadasz już własny klucz (ich generacja jest poza zakresem tego poradnika), skopiuj go na swój serwer Git wykonując następujące polecenie na własnym komputerze:

ssh-copy-id user@git.janilowski.pl

Zamień oczywiście user na własną nazwę użytkownika na serwerze i git.janilowski.pl na domenę bądź adres IP, z którego korzystasz.

Zaloguj się teraz na serwer. Skopiujemy sygnatury autoryzowanych kluczy do katalogu użytkownika git.

ssh user@git.janilowski.pl 			# Zaloguj się na serwer.
cd 						# Przejdź do swojego katalogu domowego.
sudo mkdir /var/git/.ssh			# Stwórz ukryty katalog .ssh.
sudo cp ~/.ssh/authorized_keys /var/git/.ssh/	# Skopiuj autoryzowane klucze.
sudo chown git:git -R /var/git/.ssh		# Zaktualizuj uprawnienia, aby użytkownik git był właścicielem katalogu.

Synchronizacja repozytoriów

Możemy teraz zająć się przesyłaniem plików z twojego komputera na nowo skonfigurowany serwer. Przejdź do katalogu na swoim komputerze, w którym trzymasz repozytoria git korzystając z polecenia cd. Następnie zapisz adres swojego serwera git:

git remote add extra git@git.janilowski.pl:janilowski.pl.git

extra jest tylko nazwą, którą możesz zmienić. Większość repozytoriów używa origin dla swojego głównego serwera. git.janilowski.pl jest adresem serwera git. janilowski.pl.git jest nazwą pustego repozytorium, które wcześniej tworzyliśmy na serwerze.

Teraz możemy wykonać polecenie push i wysłać pliki repozytorium na serwer:

git push extra master

To w zasadzie wszystko. Teraz twoje pliki są zsynchronizowane z serwerem git na twoim własnym serwerze.

Możesz pobrać swoje repozytorium na inny komputer (bądź do innego katalogu, jeśli chcesz przetestować działanie serwera) tym poleceniem:

git clone git@git.janilowski.pl:janilowski.pl.git

Do zmiany pozostaje oczywiście adres serwera i nazwa repozytorium.

Jeśli nie jesteś zainteresowany udostępnianiem swojego kodu publicznie, ani interfejsem webowym, możesz zatrzymać się w tym punkcie.

GitWeb

GitWeb jest tylko interfejsem webowym, który pozwoli na przeglądanie repozytorium korzystając z przeglądarki. Wpierw konieczne jest uruchomienie potrzebnych modułów w serwerze webowym:

sudo a2enmod cgi alias env	# Uruchomienie trzech modułów.

sudo systemctl restart apache2	# Restart serwera Apache, aby uruchomienie modułów miało pożądany efekt

alias i env prawdopodobnie już są włączone, ale nie zaboli się upewnić.

Apache działa jako użytkownik www-data, aby ograniczyć swoje uprawnienia. Stąd wszystko, do czego ma uprawnienia ten użytkownik trzeba traktować jako dostępne publicznie. Nie mniej, żeby umożliwić wyświetlenie danej strony internetowej, trzeba nadać www-data uprawnienia do jego odczytu. Stąd zmienimy uprawnienia katalogu, /var/git aby umożliwić jego wyświetlanie w Internecie.

⚠️UWAGA⚠️ W tym momencie udostępniasz innym ludziom możliwość wglądu do wszystkich twoich repozytoriów. Jeżeli chcesz ograniczyć możliwość oglądania plików wewnątrz katalogu /var/git, możesz zaznaczyć konkretne repozytoria, dodając je do ostatniej części komendy (np. /var/git/janilowski.pl.git udostępni tylko jedno repozytorium).

sudo chgrp -R www-data /var/git/

Następnie musimy przystąpić do edycji pliku zawierającego konfigurację GitWeb - /etc/gitweb.conf. Konieczna jest zmiana drugiej linijki pliku, w której znajduje się ścieżka do repozytoriów git. Należy ją zaktualizować w taki sposób, aby odzwierciedlała lokalizację repozytoriów na naszym serwerze. Jeśli trzymałeś się tego poradnika, pierwsze dwie linijki gitweb.conf powinny wyglądać w ten sposób:

# path to git projects (<project>.git)
$projectroot = "/var/git";

Następnie skonfigurujmy serwer HTTP Apache. Wejdź do katalogu /etc/apache2/sites-available/ (cd /etc/apache2/sites-available) i stwórz plik git.conf (sudoedit git.conf). Plik powinien zawierać następujące linijki:

<VirtualHost *:80>
        ServerName git.janilowski.pl

        DocumentRoot /usr/share/gitweb

        #Redirect "/" "https://git.janilowski.pl"
</VirtualHost>

<VirtualHost *:443>
        ServerName git.janilowski.pl
        DocumentRoot /usr/share/gitweb

        SetEnv GITWEB_CONFIG    /etc/gitweb.conf
        SetEnv GIT_PROJECT_ROOT /var/git

        <Directory /usr/share/gitweb>
                Options +ExecCGI +FollowSymLinks +SymLinksIfOwnerMatch

                AllowOverride All
                order allow,deny
                Allow from all
                AddHandler cgi-script cgi
                DirectoryIndex gitweb.cgi
        </Directory>
</VirtualHost>

Zamień wszystkie trzy wzmianki git.janilowski.pl na własną domenę. Zapisz zmiany i zamknij edytor tekstu.

Konfiguracja Apache jest zbyt skomplikowana, żeby wyjaśnić wszystkie linijki w tym poradniku. W pewnym skrócie, wskazujemy, aby serwer prowadził nasłuch na porcie 80 oraz 443. W obu przypadkach kierujemy użytkowników do katalogu /usr/share/gitweb, do którego domyślnie instalowany jest gitweb w systemie Debian.

Sprawdźmy szybko, czy konfiguracja jest w pełni prawidłowa:

sudo apache2ctl -t

Jeśli na ekranie pojawi się Syntax OK, możemy przejść dalej. Włączmy stronę, którą właśnie skonfigurowaliśmy i przeładujmy Apache, aby zmiany w konfiguracji zostały wzięte pod uwagę:

sudo a2ensite git

sudo systemctl restart apache2

W niektórych przypadkach na serwerze może być domyślnie włączony firewall. Możesz to sprawdzić:

sudo ufw status

Jeśli nie zobaczysz portów 80 i 443, będziesz musiał je odblokować:

sudo ufw enable "WWW Full"	# Odblokowanie portów 80 i 443, które wykorzystywane są przy stronach internetowych
sudo ufw enable			# Uruchomienie firewalla. Upewnij się najpierw, że w poleceniu status pojawia się port 22;

Od tego momentu twoja strona internetowa powinna być widoczna w internecie. Możesz wpisać jej adres w przeglądarce i sprawdzić, czy się wyświetla. Niestety możesz ujrzeć błędy bezpieczeństwa, ponieważ twoja strona nie szyfruje ruchu. Zmieńmy to generując darmowy certyfikat i umieszczając go na stronie:

sudo certbot --apache

Po wpisaniu tej komendy otrzymasz serię pytań związanych z twoją konfiguracją. Najpierw wybierz domenę, na której będziesz udostępniał swój interfejs, podaj swój adres mailowy i wyraź zgodę na regulamin. Nie musisz zgadzać się na newsletter. Adres mailowy jest jednak potrzebny do przesyłania powiadomień, na wypadek gdyby np. certyfikat nie odnawiał się automatycznie.

Jeśli certbot poprawnie wygenerował Ci certyfikat, wprowadźmy ostatnie zmiany w konfiguracji. Wróćmy najpierw do katalogu /etc/apache2/sites-available (cd /etc/apache2/sites-available). Otwórz plik git.conf (sudoedit git.conf). Powinieneś ujrzeć w pierwszej sekcji następujące linijki:

RewriteEngine on
RewriteCond %{SERVER_NAME} =git.janilowski.pl
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]

Są one zupełnie niepotrzebne. Możesz je bez problemu usunąć. Potrzebna jest za to usunięcie znaku # z początku jednej z linijek w pierwszej sekcji. Poprawnie skonfigurowana pierwsza sekcja powinna wyglądać w ten sposób:

<VirtualHost *:80>
        ServerName git.janilowski.pl

        Redirect "/" "https://git.janilowski.pl"
</VirtualHost>

To w zasadzie wszystko. Gratuluję, postawiłeś własny serwer Git z interfejsem webowym. Efektywnie zbudowałeś własnego GitHuba. 😉

Dodatkowe opcje konfiguracji

Dodawanie opisów

Możesz zauważyć, że każde repozytorium prawdopodobnie zgłasza w tym momencie brak opisu w interfejsie webowym. Możesz napisać zdanie o każdym z nich korzystając z poniższej komendy. Zamień oczywiście treść samego opisu oraz nazwę repozytorium (janilowski.pl.git):

su -l git
echo "Osobista strona internetowa Jana Iłowskiego" > janilowski.pl.git/description

Kolumna z opisami jest wyjątkowo wąska. Całe szczęście ten serwer jest twoim terenem prywatnym, więc nie musisz prosić nikogo o zmiany w jego interfejsie, ale po prostu dodać jedną linijkę do pliku /etc/gitweb.conf:

$projects_list_description_width = 100;

Kolorowanie składni

Kiedy zaczniesz przeglądać drzewko plików, możesz zauważyć, że ich treść wyświetlana jest w całości na czarno. Można to zmienić dodając kolorowanie składni:

sudo apt install highlight	# Zainstaluj malutki program `highlight`
sudoedit /etc/gitweb.conf	# Przejdź do edycji konfiguracji GitWeb

Dodaj następującą linijkę na końcu pliku:

$feature{'highlight'}{'default'} = [1];

Zapisz i zamknij plik. Zrestartuj Apache, aby zmiany faktycznie nastąpiły:

sudo systemctl restart apache2

Od teraz składnia jest kolorowana, więc i bardziej czytelna.

Własne logo

Możesz zamienić domyślne logo na swoje własne po prostu podmieniając plik /usr/share/gitweb/static/git-logo.png. Najpierw prześlij swój plik na serwer korzystając z sftp:

sftp janek@git.janilowski.pl
put ./Documents/git-logo.png

Następnie zaloguj się na serwer i podmień pliki:

ssh janek@git.janilowski.pl
sudo rm /usr/share/gitweb/static/git-logo.png
sudo mv ./git-logo.png /usr/share/gitweb/static

Wiadomość powitalna w HTML

Możesz dodać własną wiadomość powitalną w HTML do strony głównej swojego interfejsu webowego. Wystarczy napisać wiadomość w HTML w odpowiednim miejscu. Zaloguj się na swój serwer korzystając z ssh i stwórz odpowiedni plik:

ssh janek@git.janilowski.pl
sudoedit /usr/share/gitweb/indextext.html

Wpisz jakiegoś rodzaju opis:

<h1>Serwer Git Jana Iłowskiego</h1>
<p>Zapraszam do korzystania z kodu na moim serwerze.</p>

Zapisz i zamknij plik. Jeśli opis się nie wyświetla po odświeżeniu strony, uruchom ponownie Apache:

sudo systemctl restart apache2

Więcej

Dalsze parametry konfiguracji można znaleźć w dokumentacji GitWeb. Polecam ją przeczytać przy dłuższym użytkowaniu. Prawie każdy element strony może zostać łatwo zmieniony według twoich preferencji.