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,
    • ověřit, že obraz kontejneru pro vámi zvolený generátor je pro fakultní GitLab CI dostupný, např. v aplikaci fakultní administrativy.

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

Pro výzkumné skupiny nebo významné projekty můžeme nastavit proxy z domény tvaru X.fi.muni.cz pro poskytování obsahu z GitLab Pages. Stejně tak můžeme zajistit poskytování obsahu z vlastní registrované domény. Stačí, když registrátor nastaví pro doménu jednu z těchto variant: 

  1. domain IN CNAME gitlab.fi.muni.cz.
  2. domain IN A 147.251.58.80
          AAAA 2001:718:801:23a::50

Pozor, CVT registraci domén mimo FI nezajišťuje.

Ohledně přesných podmínek nejdříve 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