Nasazování aplikace

Tato sekce popisuje možné způsoby nasazení aplikace WebAMČR, včetně předpokladů a specifik takových nasazení. Všechny následující postupy jsou založeny na použití docker kontejnerů, které jsou vytvářeny pomocí docker-compose souborů a to automaticky nebo manuálně. Primárně jsou docker obrazy vytvářeny v rámci běhu Gihub CI, tj. definované ve workflow ./.github/workflows/publish_aiscr_hub.yml spouštěné v rámci Github Actions. Uvedná worfklow se spouští jedině a tehdy pokud se vytvoří tag na větvi „dev“ a tento tag je ve formátu „v*.“ Další možnosti vytvoření docker obrazů jsou pomocí níže uvedených automatizačních skriptů, které dokáží tyto obrazy vytvořit lokálně na cílové stanici.

Vytváření docker obrazů

Jak bylo zmíněno výše, primární metodou vytváření docker obrazů je workflow ./.github/workflows/publish_aiscr_hub.yml, po jejím spuštění dojde k vytvoření těchto docker obrazů:

  • aiscr/webamcr (obraz s aplikací WebAMČR)

  • aiscr/webacmr-proxy (obraz s proxy serverem NGINX)

  • aiscr/webamcr-redis (chachovací server Redis s upravenou konfigurací)

Všechny tři vytvořené obrazy jsou poté nahrány do veřejně přístupného docker-hub repozitáře umístěného na adrese https://hub.docker.com/u/aiscr. Tento repozitář je spravovaný Archeologickým instituem Praha. Každý vytvořený obraz obsahuje soubour /version.txt, který zachycuje datum vytvoření a verzi daného obrazu (verze je odvozena od názvu tagu vytvořeného v rámci git repozitáře). Jméno verze je také zapsáno do proměnných prostředí (VERSION, TAG) každého docker obrazu, takže tyto systémové proměnné lze použít pro účely aplikace. Docker-hub repozitář pak slouží jako místo, kde se uchovávají všechny vytvořené verze aplikace WebAMČR a lze jej tak snadno použít pro nasazení aplikace v různých verzích, definovaných tagy.

Alternativně lze docker obrazy vytvořit manuálně, s pomocí předpřipravených Dockerfile souborů:

  • Dockerfile - definice docker obrazu pro aplikaci WebAMČR, produkční / testovací nasazení, nutná existence systémových proměnných VERSION_APP, TAG_APP, které popisují verzi vytvářeného obrazu (automaticky dodáváno při vytváření přes automatizační skripty)

  • Dockerfile-DEV - definice docker obrazu pro aplikaci WebAMČR pro vývojové nasazení, nutná existence parametrů –build-arg TAG_APP=<value> a –build-arg VERSION_APP=<value> při spuštění vytváření obrazu z příkazové řádky (automatizační skript toto dodává bez nutnosti zásahu uživatele)

  • Dockerfile-DB - definice docker obrazu databáze Postgresql pro lokální nasazení a vývojové účely

  • redis/Dockerfile - definice docker obrazu pro redis server s upravenou konfigurací

  • proxy/Dockerfile - definice docker obrazu pro proxy server NGINX

Poznámka

Pro detailní informace o architektuře a optimalizacích Dockerfile a Dockerfile-DEV, včetně multi-stage buildů a kompilace bytecode, viz Multi-stage Docker build.

Varianty nasazení aplikace WebAMČR

Existuje pět různých módů nasazení aplikace WebAMČR:

  1. Automatické nasazení v rámci Github Actions (použito pro nasazení do vývojového prostředí)

  2. Skriptované nasazení z docker-hubu (ostatní případě, včetně produkčního nasazení), ./scripts/prod_deploy.sh

  3. Skriptované nasazení z lokálního repozitáře (použito pro specifické účely, např. hotfix ve zdrojovém kódu, nezávisle na prostředí), ./scripts/git_prod_deploy.sh

  4. Skriptované nasazení pro vývojové účely (specifický deployment pro vývojové účely na lokálním vývojovém prostředí)

  5. Manuální nasazení pomocí docker-compose souborů (specifické případy), ovládání přes docker-compose není v tomto manuálu vysvětleno a lze využít oficiální dokumentaci Docker compose <https://docs.docker.com/compose/>

VAROVÁNÍ: pokud si vývojář není jist svými zásahy, nikdy by nemělo docházet k spuštění více různých způsobů nasazení na jedné stanici bez předchozího ukončení běžící aplikace WebAMČR nasazené jiným než aktuálně plánovaným způsobem. Např. skriptované nasazení z docker-hubu s následným spuštěním nasazení z lokálního repozitáře. V takových případech může docházet k neočekávaným chybám a konfliktům. Každý automatizační skript má volitelné parametry pro ukončení daného nasazení, které by tak mělo být vždy spuštěno před vyvoláním jiného nasazení. Docker kontejnery lze vždy ukončit standardními příkazy, pokud se vyskytnou problémy.

Stručný přehled

Metoda

Spuštění

Obrazy

Port

Secrets

Použití

Automatické Github Actions

worfklow .githubworkflowsdeployment.yml

Docker-hub

8080

docker secrets

Vývojová stanice ARUP

Skriptované z Docker-hub

./scripts/prod_deploy.sh

Docker-hub

8080

docker secrets

Testovací stanice ARUP

Skriptované z lokálního repozitáře

./scripts/git_prod_deploy.sh

lokální

8081

soubory se secrets

Hotfix, speciální případy

Skriptované pro vývojové účely

./scripts/dev_deploy.sh

lokální

8000

soubory secrets

Lokální vývoj

Manuální via docker-compose

docker-compose příkaz

Lokální nebo Docker-hub

[ 8080 | 8081 | 8000 ]

docker secrets nebo soubory se secrets

Speciální případy

Automatické nasazení probíhá při vytvoření tagu pojmenovaného dle formátu „v*“ v repozitáři Github. Po vytvoření takového tagu nejprve proběhne proces vytvoření docker obrazů (popsaný výše) a poté dojde ke spuštění další Github workflow s názvem .githubworkflowsdeployment.yml v rámci které dojde ke provedení následujících kroků:

  • inicializace VPN spojení na DEPLOYMENT_SERVER_DEV

  • ověření stability spojení pomocí dotazů na lokalní DNS server

  • přihlášení přes ssh na cílovou stanici

  • v místě nasazení dojde k otevření adresáře obsahujícího deployment skripty a následnému stashování git repozitáře a jeho aktualizaci (tzv. pull).

  • spuštění deployment skriptu (scripts/ci_deployment/deploy_server_dev.sh), který poté vyvolá:

  • spuštění vlastního nasazení WebAMČR přes skript scripts/prod_deploy.sh, tj. nasazení nejnovějších docker obrazů z docker-hubu pomocí swarm módu.

  • ověření správného spuštění docker kontejnerů ve swarm-mode.

Github Action worfklow .githubworkflowsdeployment.yml potřebuje ke správnému spuštění následující definice tzv. secrets v repozitáři Github, tyto je nutné definovat manuálně a jsou v gesci správce repozitáře:

  • VPN_CA_CRT - certifikát CA pro VPN

  • VPN_USER_CRT - certifikát uživatele pro VPN

  • VPN_USER_KEY - privátní klíč uživatele pro VPN

  • VPN_SECRET_USERNAME_PASSWORD - uživatelské heslo pro VPN

  • DEPLOYMENT_SERVER_DEV - IP adresa cílové stanice pro nasazení

  • DNS_RESOLVER - IP adresa DNS serveru pro ověření stability spojení

  • SSH_KNOWN_HOST_DEV - fingerprint cílové stanice SSH připojení

  • SSH_PRIVATE_KEY_SERVER_DEV - privátní klíč pro SSH připojení na cílovou stanici

Skriptované nasazení z docker-hubu

Pro nasazování na testovací prostředí byl vytvořen automatizační skript scripts/prod_deploy.sh, který zjednodušuje nasazení, provádí logování celého průběhu do adresáře logs/prod_deploy/, aktualizaci docker obrazů, ověřování prostředí, a nasazení aplikace WebAMČR. Tento skript má několik možných parametrů, nápověda přístupná spuštěním příkazu ./scripts/prod_deploy.sh -h.. V základním módu se tento skript spouští bez jakéhokoliv volitelného parametru, tzn. ./scripts/prod_deploy.sh. Po úspěšném vykonání je aplikace WebAMČR dostupná na ip adrese dané stanice a portu 8080.

Skript pro nasazení z Docker Hubu do Docker Swarm podporuje několik parametrů, každý s určitým účelem a příkladem použití. Zde je seznam možných parametrů s popisem a příklady v češtině:

Niže je přehled dostupných parametrů.

  • -h: Zobrazení nápovědy.

    • Použití: scripts/prod_deploy.sh -h

  • -x: Odstranění celého Docker stacku, tedy všech službeb.

    • Použití: scripts/prod_deploy.sh -x

    • Popis: Použití tohoto parametru způsobí odstranění celého Docker stacku, což zahrnuje všechny běžící služby definované v Docker Compose souboru.

  • -u <tag_name>: Aktualizuje všechny služby novými verzeme images.

    • Příklad: scripts/prod_deploy.sh -u

    • Popis: Použitím tohoto parametru dojde k aktualizaci všech služeb.

  • -t <tag_name>: Umožňuje specifikovat konkrétní tag image pro nasazení.

    • Příklad: scripts/prod_deploy.sh -t my-custom-tag

    • Popis: Tento parametr se používa pro nasazení specifické verze nebo konfigurace obrazu.

  • -i: Zobrazí aktuální dostupné verze k nasazení.

Předpoklady: existující definice docker secrets, tyto secrets musejí být vytvořené přes příkaz docker secrets create <název secretu> <cesta k souboru s obsahem ze kterého se secret má vytvořit>

  • db_conf - přihlašovací údaje a nastavení pro připojení k databázi

  • mail_conf - konfigurace pro odesílání emailů

  • redis_pass - heslo k redis serveru

  • grafana_admin_password - heslo pro rozhraní grafana

  • elastic_pass - heslo ke službě elasticsearch

  • logstash_elastic_pass - heslo ke službě logstash

  • prometheus_config - nastavení služby prometheus

  • postgresql_exporter - heslo k PostgreSQL databázi, která má být monitorována

  • postgresql_exporter_uri - adresa rozhraní databáze PostgreSQL, která má být monitorována

  • logstash_elastic_host - adresa elasticsearch databáze

Souhrn: ./scripts/prod_deploy.sh, docker swarm-mode, <ip_adresa_stanice:8080>, existující definice docker secrets.

Skriptované nasazení z lokálního repozitáře

V případech, kdy na docker-hubu nejsou k dispozici docker obrazy v požadované verzi (např. při hotfixech), je možno aktualizovat zdrojový kód přímo v lokální repozitáři a následně spustit automatizační skript ./logs/git_prod_deploy, který se postará o vytvoření docker obrazů lokálně na základě zdrojových souborů lokálního repozitáře. Tento skript loguje průběh do souboru logs/git_prod_deploy, vytváří lokálně docker obrazy, jež jsou následně nasazeny pomocí docker-compose, tj. NEPOUŽÍVÁ SE swarm-mode. Aplikace WebAMČR je v tomto případě přístupná na portu 8081. Základní spuštění probíhá bez jakéhokoliv volitelného parametru, tzn. ./scripts/git_prod_deploy.sh. Nápověda k dalším volbám je přístupná přes logs/git_prod_deploy.sh -h.

Předpoklady: existující a aktualizované soubory s tzv. secrets, které obsahují nezbytné autentizační a konfigurační údaje viz git_docker-compose.yml, kde se předpokládá existence těch souborů:

  • db_conf: secrets.json

  • mail_conf: secrets_mail_client.json

  • redis_pass: redis_pass.txt

  • grafana_admin_password: grafana_admin_password.txt

  • elastic_pass: elastic_password.txt

  • logstash_elastic_pass: logstash_elastic_password.txt

Souhrh: ./scripts/git_prod_deploy.sh, docker compose mode, <ip_adresa_stanice:8081>, existující soubory s definicí secrets.

Skriptované nasazení pro vývojové účely

V případě lokálního nasazení na vývojové stanici, lze využít speciální konfigurace spustitelné buď přes:

  • Automatizační skript scripts/dev_deploy.sh

  • Manuálně pomocí docker compose souboru docker-compose-dev-local-db.yml

Info o volitelných parametrech automatizačního skriptu je dostupné přes ./scripts/dev_deploy.sh -h. Při tomto nasazení je možné také zprovoznit lokální instanci databáze (nebo ponechat připojení ke vzdálené databázi - nastavení dáno souborem na který se odkazuje secret db_conf), včetně jejího naplnění vzorovými daty z připraveného souboru .tar. Oproti ostatním typům nasazení je zde místo tzv. docker volumes využíváno propojení docker kontejneru se souborovým systémem (bind-mount), tzn. docker kontejner má přímo napojené soubory z lokálního repozitáře a jakákoliv jejich editace se ihned projeví v aplikaci bez nutnosti znovu vytvářet příslušné docker kontejnery. Ve vývojovém nasazení také běží navíc tři další služby:

  • db - lokální databáze postgresql

  • pgadmin - webový správce databáze postgresql

  • livereload - služba zajišťující aktualizace aplikace WebAMČR při změně souborů v lokálním repozitáři

Souhrh: ./scripts\dev_deploy.sh, docker compose mode, <ip_adresa_stanice:8000>, existující soubory s definicí secrets, volitelně: soubor (.tar) s daty pro naplnění lokální databáze.

Skriptované nasazení pro testovací účely

Pro nasazení na vývojové stanici pro testovací účely, lze využít speciální konfigurace spustitelné přes:

Manuální nasazení pomocí docker-compose souborů

Při specifických způsobech nasazení, kdy výše uvedené automatizační skripty neodpovídají požadovanému scénáři, je možné využít existujících docker-compose souborů a celou akci provést manuálně.

  • ./docker-compose.yml - obsahuje služby potřebné pro běh aplikace WebAMČR, (nutnost existence systémové proměnné IMAGE_TAG, která definuje požadovanou verzi aplikace WebAMČR, která má být stažena z docker-hub repozitáře, tj. latest, nebo v0.3.0 apod.)

  • web - aplikace WebAMČR

  • memcached - cachovací server

  • sidecar - pomocná služba pro zálohování locale na lokální úložiště

  • redis - chachovací server

  • celery_worker - worker pro asynchronní úlohy

  • celery_beat - beat pro asynchronní úlohy

  • grafana - grafické prostředí pro monitorování

  • prometheus - monitorovací služba

  • logstash - logovací služba

  • elasticsearch - databáze pro logovací službu

  • kibana - grafické prostředí pro logovací službu

  • selenium - testovací služba

  • ./docker-compose-proxy.yml - obsahuje služby potřebné pro běh proxy serveru NGINX, port je nastaven na 8080, služby:

  • proxy - proxy server NGINX

  • ./git_docker-compose.yml - obsahuje stejné služby jako ./docker-compose.yml, ale pro službu web využívá lokální build přes Dockerfile místo stažení obrazu z docker-hubu

  • ./git_docker-compose-proxy.yml - obsahuje stejné služby jako ./docker-compose-proxy.yml, ale pro službu proxy využívá lokální build přes proxy\Dockerfile a nastavuje port na 8081

  • ./git_docker-compose.override.yml - obsahuje alternativní secrets, samostatně nespustitelné, využívá se pouze nepřímo skrze rozhodovací strukturu v rámci skriptu ./scripts/git_prod_deploy.sh

Kontrola stavu aplikačních kontejnerů

Existuje sada tzv. healtcheck skriptů, které reportují stav služby běžící uvnitř příslušného kontejneru. Každý kontejner používá jinou sadu charakteristik k odvození příslušné metriky „health status“. Výsledky kontroly health status se dají pro každý kontejner nalézt po spuštění příkazu docker inspect -f „{{json .State.Health}}“. Tyto kontroly stavu zdraví aplikace se provádějí periodicky. Aktuálni hodnoty periody kontroly se dají odečíst v souboru docker-compose.yml.

  • Kontejner web (aplikace WebAMCR) má nejkomplexnější metriku implementovanou v run-healthcheck.sh, která se skládá z monitorování obsazenosti paměti diskového prostoru hostitelské stanice (musí být menší než 95 %), nadále dostupnost databáze (vytvořen skript db_connection_from_docker-web.py) a výsledek django checks reportovaný jako HTTP odpověď ve formátu JSON (musí být HTTP status code 200). V rámci této odpovědi zasílané na http-socketu 8001 se agreguje výsledek tzv. interních django checks (manage.py checks) a také (manage.py checks –database default). Pospojováním jednotlivých výsledků dílčích metrik pomocí operace AND pak vznikne souhrnný status code 0 (healthy) nebo 1 (not healthy)

  • Kontejner proxy, kontrola návratu HTTP status code 200 na http socketu 8080, implementováno ve skriptu run-healthcheck_proxy.sh.

  • Kontejner celery, metrika je odezva na příkaz celery ping, který musí mít nulový návratový kód, implemetováno ve skriptu run-healthcheck_celery.sh.

  • Kontejner redis metrika je odevzva na příkaz redis ping, očekáván nulový návratový kód, implementováno ve skriptu run-healthcheck_redis.sh.