diff --git a/docs/index.rst b/docs/index.rst index 10d6016f..92d27c50 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Vítejte v dokumentaci M&Mího webu! vyvoj sphinx dalsi_soubory + skripty modules/modules zapisy/zapisy diff --git a/docs/skripty.rst b/docs/skripty.rst new file mode 100644 index 00000000..8f9e1064 --- /dev/null +++ b/docs/skripty.rst @@ -0,0 +1,108 @@ +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 +``/management/commands/``, případně vestavěné, a volají se pomocí +``./manage.py ``. 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/``. + +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 + ``, 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 `` + Otestuje, že skript běží z konkrétní složky. Zejména použitelné s ``gimli_only`` a ``$TESTWEB`` +``safe_checkout_branch `` + 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 `_. +``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``. diff --git a/make/README.md b/make/README.md index 0597a96b..16b77901 100644 --- a/make/README.md +++ b/make/README.md @@ -1,9 +1,8 @@ +Milý člověče, M&Mí web tě vítá. Prosím, neděs se, zkusím tě provést lokálním zprovozněním webu. +Pro detaily a nápovědu si prosím přečti dokumentaci v docs/vyvoj.rst. + TL;DR: Web vyrobíš pomocí následující posloupnosti příkazů: - make/install_web - . env/bin/activate - ./manage.py testdata - ./manage.py loaddata data/* + make/init_local make/run a web potom najdeš na -Pro detaily a nápovědu si prosím přečti dokumentaci v docs/vyvoj.rst. diff --git a/make/deploy b/make/deploy index 24ade165..b615f73f 100755 --- a/make/deploy +++ b/make/deploy @@ -14,3 +14,18 @@ safe_checkout_branch "$BRANCH" # Teď máme správnou větev, jdeme vše nainstalovat install_everything systemctl --user restart mamweb-test.service + +# Přihlášení +htpasswd -bc .htpasswd test lisakjelisak +setfacl -m u:www-data:r .htpasswd + +# Build dokumentace +ensure_venv +( + cd docs + make html +) +# Oprava práv k dokumentaci +setfacl -m u:www-data:x . docs docs/_build +setfacl -R -m u:www-data:rX docs/_build/html +setfacl -R -m default:u:www-data:rX docs/_build/html diff --git a/make/init_local b/make/init_local new file mode 100755 index 00000000..75ee1ccf --- /dev/null +++ b/make/init_local @@ -0,0 +1,10 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +make/install_web +ensure_venv +./manage.py testdata +./manage.py loaddata data/* +make/sync_prod_flatpages diff --git a/make/lib.sh b/make/lib.sh index 135f859e..65f19e47 100644 --- a/make/lib.sh +++ b/make/lib.sh @@ -26,6 +26,18 @@ test -e '.git' || die "Make skript spuštěn ve špatné složce, spusť ho z ko function ensure_venv { test -f "$VENV_PATH/bin/activate" || $VENV "$VENV_PATH" . "$VENV_PATH/bin/activate" + # To ale není všechno Horste – ten venv nemusí fungovat, chceme to ověřit a případně spadnout. + local SPRAVNA_CESTA="$(readlink -f "$env/bin/python")" + local SKUTECNA_CESTA="$(readlink -f "$(which python)")" + test "$SPRAVNA_CESTA" != "$SKUTECNA_CESTA" || die "Venv asi nefunguje. Prosím smaž si ho a zkus to znovu." + python -c 'print()' > /dev/null || die "Python ve venvu je rozbitý. Prosím smaž venv a zkus to znovu." +} + +function ensure_web_installed { + ensure_venv + python -c 'import django; print(django.__version__)' > /dev/null && return + echo >&2 "POZOR: Web nevypadá nainstalovaně, instaluji." + make/install_web } function gimli_only { @@ -84,6 +96,8 @@ function install_everything { make/install ./manage.py migrate ./manage.py collectstatic --noinput + setfacl -R -m default:u:www-data:rX media static + setfacl -R -m u:www-data:rX media static chown -R :mam . || true chmod -R g+rX,go-w . || true } diff --git a/make/run b/make/run index c601593a..c3caf58d 100755 --- a/make/run +++ b/make/run @@ -3,6 +3,6 @@ set -exuo pipefail . make/lib.sh -ensure_venv +ensure_web_installed ./manage.py runserver "$@" diff --git a/make/schema b/make/schema index 9688e49a..05e84b61 100755 --- a/make/schema +++ b/make/schema @@ -3,7 +3,7 @@ set -exuo pipefail . make/lib.sh -ensure_venv +ensure_web_installed ./manage.py graph_models seminar | dot -Tpdf > schema_seminar.pdf ./manage.py graph_models -a -g | dot -Tpdf > schema_all.pdf diff --git a/make/sync_prod_flatpages b/make/sync_prod_flatpages index 4d9d8e1f..ca32c95b 100755 --- a/make/sync_prod_flatpages +++ b/make/sync_prod_flatpages @@ -3,7 +3,7 @@ set -exuo pipefail . make/lib.sh -ensure_venv +ensure_web_installed # TODO: This is very ugly, will fix in a future PR (hopefully) ssh "$GIMLI_LOGIN" " diff --git a/make/sync_test_media b/make/sync_test_media index d7991b65..44b0e830 100755 --- a/make/sync_test_media +++ b/make/sync_test_media @@ -4,6 +4,6 @@ set -exuo pipefail . make/lib.sh gimli_only -only_in_dir "$TESTWEB" +only_in_directory "$TESTWEB" rsync -av --delete "$PRODWEB/media/" ./media diff --git a/make/test b/make/test index bdf9f12b..155d03fa 100755 --- a/make/test +++ b/make/test @@ -3,6 +3,7 @@ set -exuo pipefail . make/lib.sh -ensure_venv +ensure_web_installed +trap - ERR # Testy nejspíš selžou, ale nechceme kolem toho dělat další chybovou hlášku. ./manage.py test -v2 diff --git a/requirements.txt b/requirements.txt index 9ad24a7f..d4713d76 100644 --- a/requirements.txt +++ b/requirements.txt @@ -62,3 +62,4 @@ lorem sphinx sphinx_rtd_theme +myst_parser