mamweb/docs/skripty.rst

Skripty pro práci s repozitářem
===================

Máme dvě hlavní sady skriptů/příkazů na ovládání webu a repozitáře. Skripty pro
práci s webem psané v Pythonu jsou uložené ve složkách
``<aplikace>/management/commands/``, případně vestavěné, a volají se pomocí
``./manage.py <příkaz>``. Oproti tomu skripty pro práci s repozitářem a pro
úpravy databáze a souborů „zvenčí“ se nejčastěji nacházejí ve složce ``make/``
a volají se pomocí cesty: ``make/<příkaz>``.

Občas existují i nějaké další skripty na různých jiných místech. Všechny by
měly být ideálně popsány asi tady.

Make skripty
----

Skripty v ``make/`` se označují jako „Make skripty“. Slouží často k velkým
úkonům s repozitářem, jako je nasazení celého webu, zprovoznění lokálního webu
a podobně.

.. note:: Označení pro tyto skripty je dáno tím, že byly původně volány pomocí
   make (tj. z Makefile). Ve skutečnosti je lze stále volat i jako ``make
   <skript>``, ale pak není možné předávat parametry a obecně je tato cesta
   zastaralá a existuje jen pro zpětnou kompatibilitu se svalovou pamětí.

Tyto skripty jsou samonosné, dají se spustit rovnou a v případě problémů si
budou hlasitě stěžovat. Pro účely debugování různých věcí jsou ale (bohužel?)
hlasité i při normálním spuštění, konkrétně vypisují všechny příkazy, které se
spouštějí (\ ``set -x``). Tyto příkazy jsou vidět za jedním či více plusky (\ ``+``).

.. tip:: Pokud některý make skript selže, tak by na konci měl vypsat, že se něco nepovedlo.


Knihovna ``make/lib.sh``
^^^^^^

Pro pohodlí při psaní velká část z nich využívá knihovnu uloženou
v ``make/lib.sh``. Jsou zde definované užitečné proměnné, kontroly a společný
kód. Kromě toho při inicializaci otestuje, že je skript spuštěn z kořene
repozitáře (takže to pak není potřeba zkoumat v ostatních skriptech).

Proměnné
"""""

Popsány jsou jen užitečné proměnné, ve skutečnosti jich je definovaných víc,
ale jsou triviální a samopopisné.

``VENV_PATH`` :
  Cesta virtuálního prostředí. Též lze přepsat.
``REPO`` :
  Cesta ke gitovému repozitáři na serveru, rovnou použitelná v ``git clone``
``GIMLI_LOGIN`` :
  Přihlašovací údaje ke Gimlimu
``PRODWEB`` a ``TESTWEB`` :
  Cesty ke složkám s produkčním a testovacím webem

Funkce a další zkratky
""""""

``ensure_venv`` :
  Zajistí, že se zbytek skriptu spustí ve virtuálním prostředí, a pokud neexistuje, tak jej založí.
``ensure_web_installed`` :
  Vyzkouší, že je web (django) aspoň elementárně zprovozněno a pokud ne, tak vyzve uživatele, aby to spravil.
``gimli_only`` :
  Otestuje, že je příkaz spuštěn na Gimlim, pokud tomu tak není, zeptá se, jestli si uživatel skutečně přeje zbytek skriptu vykonat
``only_in_directory <složka>`` :
  Otestuje, že skript běží z konkrétní složky. Zejména použitelné s ``gimli_only`` a ``$TESTWEB``
``safe_checkout_branch <větev>`` :
  Bezpečně přepne repozitář na jinou větev. Pokud by mělo dojít k přepsání
  knihovny nebo volajícího make skriptu, vyzve uživatele, aby přepnul ručně.
``install_everything`` :
  Společná část kódu pro nasazování produkce a testwebu.

Skripty pro lokální vývoj
^^^^^^^

``make/install_web`` (nebo ekvivalentně ``make/install``) :
  Vytvoří virtualenv a nainstaluje do něj závislosti webu podle ``requirements.txt``. Následně popíše, jak vyrobit zbytek lokálního webu.
``make/run`` :
  Spustí lokální web (ekvivalentní s ``./manage.py runserver``)
``make/schema`` :
  Vykreslí závislosti a atributy modelů
``make/sync_prod_flatpages`` :
  Stáhne z produkce aktuální statické stránky a uloží je do složky ``data/``
``make/test`` :
  Spustí testy (ekvivalentní s ``./manage.py test -v2``)
``make/init_local`` :
  Zkratka za posloupnost ``make/install_web``, ``./manage.py testdata``, ``./manage.py loaddata data/*``, ``make/sync_prod_flatpages``

Práce s testwebem
^^^^^^^

``make/deploy`` :
  Nasadí testweb. Volitelně bere jako parametr jméno větve, kterou má nasadit.
  Rovnou nastaví přihlašování a vygeneruje příslušnou verzi dokumentace `sem <https://mam-test.ks.matfyz.cz/docs>`_.
``make/push_compiled_vue_to_test`` :
  **Neotestováno** Nahraje Vue z lokálního počítače na testweb. (Gimli často má moc starou verzi Node.js, takže nejde zkompilovat tam)
``make/sync_test_db_aggressive`` :
  Zkopíruje databázi z produkčního webu.
``make/sync_test_media`` :
  Zkopíruje média (obrázky, nahrané soubory) z produkčního webu.
``make/sync_test`` :
  Zkratka za ``make/sync_test_db_aggressive`` + ``make/sync_test_media``.

Nasazení produkce
^^^^

``make/deploy_prod``. Před samotným nasazením zálohuje databázi a zkontroluje, že se nasazuje větev ``master``.