Jak se v Tour de Cloud orientovat

Tour de Cloud (dále jen „TdC“) najdeš na adrese https://tourde.cloud/. Přihlas se pomocí údajů, které jsi použil při registraci účtu (tu dokončíš tak, že klikneš na odkaz v e-mailu, který ti přišel od tourde.cloud domény).

Po přihlášení se dostaneš do samotného TdC. Zatím nás bude zajímat boční panel, Sekce, které jsou pro nás aktuálně relevantní:

Aktivní deployment
Konfigurace
Testy (automatické testy)
Přístupové klíče

Postupně si popíšeme, co která sekce znamená a kdy je budeš potřebovat použít.

Úvodní obrazovka

Na úvodní stránce se nachází obecný přehled, najdeš zde náhled tvé aplikace a stav tvých kontejnerů. Tato stránka slouží výhradně informačně, nic zde nenastavuješ. Každý z kontejnerů můžeš rozkliknout, abys viděl více detailů, jako proměnné prostředí atp. Na záložce „logs“ můžeš vidět živě logy z tvé aplikace.

Konfigurace

V sekci „Konfigurace“, najdeš detaily o konfiguracích (jednotlivé verze tourdeapp.yaml souboru), které jsou uloženy na našem serveru. Tyto konfigurace můžeš zpětně nasadit tlačítkem „Deploy“. O samotném konfiguračním souboru si řekneme něco více později.

Automatické testy

V sekci „Testy“ můžeš spouštět automatické testy, ze kterých získáváš body do finálního hodnocení.. Víc se o nich dozvíš v samotném zadání.
Kromě samotného spuštění se můžeš podívat i na jejich stav (popř. logy).

Přístupové klíče

Do téhle sekce se pravděpodobně podíváš tak jednou. Zde si vygeneruješ přístupový klíč pro tvoji GitHub akci, abys mohl úspěšně nahrát aplikaci na náš server. Jak ho správně použít se dozvíš později.

Nahrání aplikace na náš server

Když už víme co TdC obsahuje, můžeme se vrhnout na nahrání samotné aplikace na náš server. Pokud bys při jakémkoliv kroku měl/a potíže, můžeš se připojit na náš Discord server a v kanálu Support si vytvořit vlákno, ve kterém ti s tvým problémem pomůžeme.

Co musíš znát

Tento článek částečně počítá s tím, že znáš následující technologie:

Git – Nástroj pro verzování softwaru
GitHub – Služba, která ti umožní vzdáleně ukládat verzované projekty
Docker – Docker je program pro kontejnerizaci tvé aplikace, zlepší to její přenositelnost
Docker image (obraz) vs kontejner – Docker obraz je tvoje aplikace zabalená do jednoho souboru. Docker kontejner je jedna instance běžícího docker obrazu
Reverzní proxy – slouží k rozdělní dotazůna správné služy (např.: /api na backend server a zbytek na frontend server)

Příprava projektu na GitHubu

Zaregistruj se na GitHubu.

TIP! Jako student si můžeš zažádat o GitHub Student Developer Pack, díky kterému získáš přístup k vývojovým nástrojům od JetBrains, vzdělávacím kurzům na Educative, vlastní server na DigitalOcean a mnoho dalších výhod (není potřeba k odevzdání).

Použití šablon

Pro zjednodušení jsme vytvořili několik šablon, které rovnou můžeš použít pro svůj projekt. Pokud žádná z šablon neodpovídá technologiím, které chceš použít, můžeš využít naší generic šablony. Ta je univerzální a lze aplikovat na jakýkoliv projekt, obsahuje totiž pouze samotnou GitHub akci, budeš si však muset sepsat vlastníDockerfile a tourdeapp.yaml.

TIP! Pokud bys potřeboval/a pomoct vytvořit strukturu pro tvůj projekt, můžeš se opět ozvat na Discordu.

Pokud se i přes to rozhodneš použít univerzální šablonu, budeš muset sám nakonfigurovat tourdeapp.yaml, ale více o tom později.

Vygenerování `TDC_TOKEN`

Dalším krokem bude vygenerování přístupového klíče pro nahrávání aplikace. To uděláš ve zmíněné záložce „Přístupové klíče“ v TdC.

Po zadání údajů ti vyskočí dialogové okno, kde si zkopíruješ klíč.

Následně ho vlož do secretů ve tvém repozitáři. Jako název zadej TDC_TOKEN. Na obrázku je vidět postup jak to udělat.

Úprava souboru a spuštění akce

Předtím, než se pustíš k samotnému nasazení aplikace, nesmíš zapomenout na to, že v šabloně v souboru tourdeapp.yaml musíš změnit <slug> na slug tvého týmu, který najdeš v TdC (viz obrázek – kliknutím na něj ho zkopíruješ).

Pokud si nyní repozitář naklonuješ za pomocí Gitu, uděláš změnu a nahraješ změny zpět na GitHub, akce se spustí a nahraje tvůj projekt na TdC. To ale není vše, musíš jít do záložky „Konfigurace“, a zde vybrat soubor, který odpovídá tvému commitu.

Pokročilé: Soubor `tourdeapp.yaml`

Pokud jsi použil/a některou z předvytvořených šablon, možná sis všiml/a, že v kořenovém adresáři projektu se nachází soubor tourdeapp.yaml, tento soubor je využíván naší GitHub akcí, aby správně sestavila všechny Docker obrazy a správně je nahrála na server. Referenční příručku v angličtině najdeš zde.

Soubor má několik hlavních částí:

exposedPort – port, na kterém bude celá aplikace dostupná zvenku. Typicky budeš chtít otevřít port vedoucí na reverse proxy, která se postará o přesměrování dotazů na správný kontejner.
containers – seznam všech kontejnerů, které se mají spustit (např. web, server, databáze).
build – seznam instrukcí, jak se mají jednotlivé Docker image postavit.

Každý z těchto bloků má své specifické vlastnosti, které si musíš nastavit podle svého projektu.

Sekce `containers`

V této sekci definuješ všechny kontejnery, které se spustí na našem serveru.
Každý kontejner má obvykle tyto vlastnosti::

- name: server
  image: registry.tourde.cloud/<slug>/server
  port: 3000
  env:
    DATABASE_URL: mysql://root:password@localhost:3306/tda_app

Tento kontejner

běží z obrazu registry.tourde.cloud/<slug>/server
poslouchá na portu 3000 (toto není port, který bude vidět na doméně, od toho je exposedPort)
má v prostředí nastavenou proměnnou DATABASE_URL, která ukazuje na databázi

Pozor! Pokud odkazuješ na jiný kontejner, který ti běží, použij localhost, v příkladu to je vidět na DATABASE_URL proměnné.

Reverzní proxy (Caddy)

Caddy (nebo nginx) se často používá jako reverzní proxy — tedy jako brána, která směruje požadavky na správné kontejnery. Vzhledem k tomu, že umožňujeme tvé aplikaci přístup z internetu jen z jednoho portu, budeš ji pravděpodobně muset použít. Pro příklad se podívej do některé z šablon.

Sekce `build`

build:
  - name: web
    context: ./apps/web
    dockerfile: ./apps/web/Dockerfile

Tady definuješ, jak se mají postavit tvoje vlastní obrazy.
Každý blok obsahuje:

name – odpovídá názvu obrazu
context – cesta ke složce, kde je zdrojový kód
dockerfile – cesta k Dockerfile, který určuje, jak obraz vytvořit

Když pak spustíš sestavení, systém podle těchto informací vytvoří Docker image pro každý z uvedených komponent (web, server, caddy atd.). Tento obraz pak najdeš na již výše uvedeném registry.tourde.cloud/<slug>/<name>

Jak nasadit aplikaci na Tour de Cloud