GitLab FI

GitLab Pages

GitLab Pages je služba, která umožňuje uživatelům generovat statické stránky přímo z repozitáře. Představuje ideální řešení pro

V této službě lze provozovat pouze statické stránky. Neumožňuje žádným standardním způsobem spouštět na straně serveru skripty nebo programy. Proto není vhodná pro aplikace, které vyžadují dynamické generování obsahu, zpracovávání formulářů nebo asynchronní dotazování.

Pro tyto účely doporučujeme provozování webu na uživatelských stránkách na serveru Aisa nebo ve virtuálním prostředí Stratus.FI.

Jak na to

Zprovoznění jednoduchého webu vyžaduje nastavení repozitáře v GitLabu a konfiguraci CI tak, aby tento web generoval.

  • Vyberte vhodný jmenný prostor a název projektu

    Název projektu se deterministicky mapuje na název stránky, kde se projekt objeví. Obecně, projekt v GitLabu s cestou
      https://gitlab.fi.muni.cz/namespace/[subns/…/]project.git
    bude dostupný na URL
      https://namespace.pages.fi.muni.cz/[subns/…/]project

    Jmenný prostor uživatelských projektů má namespace shodné s fakultním loginem, a subns/…/ je prázdné, protože uživatelský jmenný prostor nemá podskupiny. Proto pro stránky související s projektem předmětu nebo výzkumné skupiny doporučujeme použít spíš jmenný prostor skupiny.

    Speciálním případem jsou stránky v kořeni domény. Pokud si jako uživatel (nebo ve skupině) vytvoříte projekt s názvem shodným s názvem subdomény, tedy tvaru
      https://gitlab.fi.muni.cz/namespace/namespace.pages.fi.muni.cz.git
    pak bude vygenerovaný web umístěn do kořene subdomény
      https://namespace.pages.fi.muni.cz/

    Tip: Chci požádat o vytvoření skupiny

  • Nastavte viditelnost

    Fakultní GitLab má pro Pages povolenou funkci Access Control, která umožňuje uživatelům nastavit přístup k webovým stránkám.

    V části Settings → General → Visibility, … → Pages můžete v závislosti od viditelnosti projektu zvolit některou z těchto možností pro omezení přístupu na tyto uživatele:

    Private Internal Public
    Only project members členové projektu členové projektu členové projektu
    Everyone with access nelze zvolit uživatele přihlášení v GitLab FI kdokoliv i bez přihlášení
    Everyone kdokoliv i bez přihlášení kdokoliv i bez přihlášení nelze zvolit

  • Obsah webu

    Struktura stránek, použitý jazyk atd. závisí na zvoleném generátoru, tedy programu, který vytvoří výsledný statický web. Většina podporuje Markdown nebo AsciiDoc, lze však najít i specifické generátory, např. pro generování dokumentace ze zdrojových kódů. Můžete si napsat i vlastní generátor.

    Inspirujte se ukázkami

    Podívejte se na oficiální ukázky repozitářů. Většinu z nich lze použít jako kostru pro vlastní projekt.

    Dejte si pozor na konfigurační soubory, v šablonách je často potřebné upravit více než jednu konfiguraci. Pokud má šablona README.md nebo podobnou nápovědu, pečlivě si ji přečtěte.

    Otestuje konfiguraci
    Doporučujeme nejdřív začít s velmi malým počtem stránek, abyste zjistili, zda generátor vůbec funguje.
    Vlastní generátor
    Pro generování obsahu můžete použít i vlastní generátor. Generování probíhá jako každý jiný úkol pro GitLab CI. Požadavky na nastavení úkolu a kde se očekává výsledek, naleznete v oficiální dokumentaci.

  • Nastavení CI/CD

    Pro generování webu můžete použít fakultní instanci GitLab Runneru nebo vlastní instanci.

    Pro použití fakultní instance nezapomeňte nastavit pro úkoly značku shared-fi v .gitlab-ci.yml.

Další informace

Web bude automaticky dostupný protokolem https s certifikátem podepsaným autoritou Let's Encrypt.

URL webu lze změnit pouze přesunutím projektu. Jinak cestu upravit nelze, a to ani administrativně.

Obsah webu z vlastní domény

Obsah stránek z pages.fi.muni.cz lze servírovat i z jiných domén. Na výběr je několik možností.

Vlastní doména mimo fi.muni.cz

Předpoklady

  1. Zajistěte si doménu. CVT registraci nezajišťuje.
  2. Registrátor domény musí umět nastavit záznamy typu A, AAAA a TXT pro verifikaci.
  3. Volitelně můžete mít i vlastní certifikát. Ve výchozím stavu GitLab požádá o certifikát autority Let's Encrypt a bude ho sám udržovat.

Nastavení

  • Otevřete nastavení GitLab Pages V projektu na levém panelu najděte Deploy → Pages.
    Pokud tuto možnost nevidíte, ujistěte se, že je v projektu tato vlastnost povolena: Settings → General → Visibility, project features, permissions.
  • Nastavte novou doménu
    1. Klikněte na New Domain.
    2. Do pole Domain vepište jméno domény.
    3. Pokud máte vlastní certifikát, zrušte Automatic certificate management a vložte vlastní certifikát a klíč v PEM formátu.
      Pokud bude GitLab hlásit chyby, zkuste vložit i mezilehlý certifikát.
    4. Klikněte na Create New Domain.
  • Uložte si ověřovací kód Po vytvoření domény vám GitLab dá kód tvaru
    _gitlab-pages-verification-code.$DOMAIN TXT gitlab-pages-verification-code=$TOKEN
  • Nastavte novou doménu
    U registrátora domény pak požádejte o nastavení těchto záznamů (třetí řádek je kód z předchozího kroku): 
    $DOMAIN in A    147.251.58.89
        in AAAA 2001:718:801:23a::59
_gitlab-pages-verification-code.$DOMAIN TXT gitlab-pages-verification-code=$TOKEN
  • Ověrte doménu Po potvrzení nastavení od registrátora klikněte v GitLabu na tlačítko obnovení v sekci Verification Status. Pokud GitLab doménu úspěšně ověří, vygeneruje pro ní certifikát a začne ji obsluhovat.
  • Hotovo Obsah stránky byste teď měli vidět i na nové doméně.

Vlastní doména mimo fi.muni.cz (alternativa)

Pokud registrátor domény neumožňuje zavést TXT záznam, nejdříve zvažte jiného registrátora.

Alternativně lze zavést doménu s proxy. V tomto případě musí registrátor umět alespoň záznamy A a AAAA. Doména bude používat certifikát autority Let's Encrypt spravovaný CVT. Jiné certifikáty používat nelze.

Přesné nastavení pro registrátora Vám sdělí správci. Kontaktujte gitlab@fi.muni.cz.

Stránky v doméně fi.muni.cz

CVT, jakožto registrátor pro doménu fi.muni.cz, umí zavést záznamy tvaru example.fi.muni.cz, nebo taky example.lab.fi.muni.cz.

Nejdříve si domluvte rezervaci domény na adrese gitlab@fi.muni.cz. V žádosti uveďte, o který projekt jde, a zda chcete používat vlastní certifikát. Pokud je vše v pořádku, správci doménu pro stránky nastaví.

Pokud jsi nejste jistí nebo se chcete zeptat, kontaktujte správce na adrese gitlab@fi.muni.cz.

Ukázková instance

Repozitář
Zdrojový repozitář v GitLab FI, což je mírně upravená šablona pro Jekyll z oficiálního zdroje.
Výsledek
Vygenerovaná ukázka ze stejného repozitáře.

Pokud si nevíte rady s vlastní stránkou:

Zkontrolujte nastavení pro GitLab CI
Projekt → Settings → CI/CD.
Podívejte se na .gitlab-ci.yml v ukázkovém řešení
Tento soubor obsahuje definice úkolů pro vygenerování webu ve fakultním prostředí.
Zkontrolujte výstup selhávajícího úkolu
Hlavní stránka projektu v GitLabu → CI/CD.

Užitečné odkazy

Oficiální uživatelská dokumentace GitLab

Fakultní technické informace