.. _admin_deployment_scripts:

=====================================
Instalace pomocí deployment skriptů
=====================================

Pro instalaci a provoz aplikace Elza v prostředí Linux je k dispozici
sada deployment skriptů, která automatizuje instalaci, aktualizaci,
zálohování databáze a sledování stavu aplikace. Skripty jsou publikovány
na adrese `get.lightcomp.com/elza <https://get.lightcomp.com/elza/>`_.

Skripty jsou určeny pro provoz aplikace jako služby systemd s databází
PostgreSQL a doplňují postup popsaný v kapitole :ref:`admin_install`.

Požadavky:

 * Linux se systemd,
 * databáze PostgreSQL (včetně klientských nástrojů ``pg_dump``),
 * nástroje ``bash``, ``curl``,
 * oprávnění root pro instalaci (vlastní aplikace běží pod samostatným
   uživatelem).


---------
Instalace
---------

Instalace se provádí spuštěním bootstrap skriptu:

.. code-block:: bash

   curl -fsSL https://get.lightcomp.com/elza/elza-bootstrap.sh | bash -s -- --home /opt/elza

Bootstrap skript stáhne balík skriptů (ověřený kontrolním součtem) do
adresáře :file:`/opt/elza/scripts`, připraví konfigurační soubor
:file:`elza-env` a nainstaluje jednotky systemd.

Po instalaci je nutné upravit konfigurační soubor :file:`elza-env`
(zejména připojení k databázi) a spustit první nasazení příkazem
``elza-deploy``.


-----------------
Dostupné příkazy
-----------------

Po instalaci jsou k dispozici následující příkazy:

 * ``elza-deploy`` - instalace nebo aktualizace aplikace: zastavení
   služby, záloha databáze, stažení distribuce, atomické přepnutí na
   novou verzi (symbolický link ``current``), spuštění služby a ověření
   funkčnosti. Volba ``--auto`` nainstaluje verzi dle nastaveného
   kanálu.
 * ``elza-backup`` - záloha databáze pomocí ``pg_dump`` s automatickým
   mazáním starých záloh.
 * ``elza-health`` - kontrola stavu aplikace a volitelné hlášení stavu
   dohledovému systému (viz :ref:`admin_deployment_scripts_reporting`).
 * ``elza-update`` - bezobslužná aktualizace na novou verzi.

Všechny příkazy podporují volbu ``--show-config`` pro výpis výsledné
konfigurace.

Jednotky systemd
----------------

Skripty instalují následující jednotky systemd:

 * ``elza.service`` - vlastní aplikace Elza,
 * ``elza-backup.timer`` - pravidelná záloha databáze
   (výchozí: neděle 02:30),
 * ``elza-health.timer`` - pravidelná kontrola stavu
   (výchozí: každých 10 minut),
 * ``elza-update.timer`` - bezobslužná aktualizace (pokud je povolena,
   provádí se mimo nastavenou pracovní dobu).


-----------
Konfigurace
-----------

Konfigurace se provádí v souboru :file:`elza-env` v adresáři skriptů.
Přehled hlavních voleb:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Volba
     - Význam
   * - :token:`APP_HOME`
     - Domovský adresář instalace (např. :file:`/opt/elza`).
   * - :token:`DB_NAME`, :token:`DB_USER`, :token:`DB_HOST`, :token:`DB_PORT`
     - Připojení k databázi PostgreSQL.
   * - :token:`HEAP`
     - Velikost paměti JVM (výchozí: 4G).
   * - :token:`CHANNEL`
     - Kanál aktualizací: ``stable`` nebo ``testing``.
   * - :token:`AUTOUPDATE`, :token:`AUTOUPDATE_WORKHOURS`
     - Povolení bezobslužné aktualizace a vymezení pracovní doby,
       ve které se aktualizace neprovádí.
   * - :token:`BACKUP_KEEP_DAYS`, :token:`BACKUP_KEEP_PREUPDATE`
     - Doba uchování pravidelných záloh a záloh před aktualizací.
   * - :token:`IMPORT_PACKAGES`
     - Automatický import balíčků pravidel při nasazení
       (viz :ref:`admin_install_dpkg`).
   * - :token:`HEALTH_URL`
     - Volitelná URL pro lokální HTTP kontrolu, že aplikace skutečně
       odpovídá, např. ``http://127.0.0.1:8081/actuator/health``
       (viz :ref:`admin_monitoring`).
   * - :token:`HEARTBEAT_INTERVAL`
     - Interval hlášení stavu dohledovému systému (výchozí: 10m).
   * - :token:`CUSTOMER_ID`, :token:`CUSTOMER_SERVICE_SECRET`, :token:`INSTANCE_NAME`
     - Přístupové údaje a název instance pro hlášení stavu dohledovému
       systému. Bez jejich nastavení se žádná hlášení neodesílají.
   * - :token:`CSC_METRICS_URL`
     - URL lokálního endpointu s metrikami Prometheus (výchozí:
       ``http://127.0.0.1:8081/actuator/prometheus``). Nastavením
       prázdné hodnoty se předávání metrik vypne.


.. _admin_deployment_scripts_reporting:

---------------------------------------
Hlášení stavu dohledovému systému
---------------------------------------

Skript ``elza-health`` umí pravidelně hlásit stav instance vzdálenému
dohledovému systému provozovanému dodavatelem podpory. LightComp v.o.s.
nabízí tuto službu jako součást podpory pod názvem Customer
Service Center (CSC); hlášení lze směřovat i do jiného systému
implementujícího stejné rozhraní.

Hlášení je aktivní pouze tehdy, jsou-li nastaveny přístupové údaje
(:token:`CUSTOMER_ID` a :token:`CUSTOMER_SERVICE_SECRET`). Bez jejich
nastavení skripty žádná data neodesílají a provádí pouze lokální
kontrolu stavu.

Komunikace probíhá výhradně směrem od instance k dohledovému systému
(push) protokolem HTTPS a jednotlivá hlášení jsou podepsána klíčem
zákazníka (HMAC). Dohledový systém se nikdy nepřipojuje do
infrastruktury zákazníka.

Odesílané údaje
---------------

Následující přehled je umožňuje mimo jiné IT oddělení vidět, 
jaké údaje jsou předávány straně zajišťující dohled. V každém
hlášení (výchozí interval 10 minut) se odesílá:

 * celkový stav instance (``up`` / ``degraded`` / ``down``),
 * výsledky dílčích kontrol (stav služby systemd, výsledek HTTP
   kontroly),
 * verze aplikace a čas jejího spuštění,
 * jméno počítače (hostname),
 * vybrané metriky dle níže uvedeného seznamu.

Metriky se získávají z lokálního endpointu Prometheus
(viz :ref:`admin_monitoring_metrics`) a odesílají se pouze metriky
výslovně uvedené v seznamu (allow-list). Odesílají se výhradně číselné
hodnoty vybraných metrik - neodesílá se žádný archivní obsah, osobní
údaje ani kompletní výpis metrik.

.. list-table::
   :header-rows: 1
   :widths: 34 10 32 24

   * - Předávaná metrika
     - Jednotka
     - Význam
     - Výchozí práh upozornění
   * - ``elza.cam.last_success_age_seconds``
     - sekundy
     - Stáří posledního úspěšného dotazu na externí systém (CAM).
     - nad 7200 (2 hodiny)
   * - ``elza.cam.error_count``
     - počet
     - Počet položek fronty zpracování ve stavu chyba.
     - nad 0
   * - ``elza.cam.oldest_error_age_seconds``
     - sekundy
     - Stáří nejstarší položky ve stavu chyba.
     - nad 3600 (1 hodina)
   * - ``elza.cam.deferred_oldest_age_seconds``
     - sekundy
     - Stáří nejstarší odložené položky fronty zpracování.
     - nad 86400 (24 hodin)
   * - ``elza.users.connected``
     - počet
     - Počet aktuálně připojených uživatelů.
     - nesledováno (informativní)

Prahové hodnoty jsou výchozí a strana zajišťující dohled je může pro
konkrétní instalaci upravit. Autoritativní strojově čitelný seznam
předávaných metrik je součástí distribuce Elza v souboru
:file:`config/csc-metrics.json`.

Vypnutí předávání údajů:

 * úplné vypnutí hlášení - nenastavovat (odebrat) :token:`CUSTOMER_ID`
   a :token:`CUSTOMER_SERVICE_SECRET`,
 * vypnutí předávání metrik při zachování hlášení stavu - nastavit
   :token:`CSC_METRICS_URL` na prázdnou hodnotu.
