Merge branch 'makefiles' into make_docs

docs/index.rst

@@ -13,6 +13,7 @@ Vítejte v dokumentaci M&Mího webu!
    vyvoj
    sphinx
    dalsi_soubory
+   skripty
    modules/modules
    zapisy/zapisy
 

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
+``<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``.

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
+	make/init_local
-	. env/bin/activate
-	./manage.py testdata
-	./manage.py loaddata data/*
 	make/run
 a web potom najdeš na <http://127.0.0.1:8000>
 
-Pro detaily a nápovědu si prosím přečti dokumentaci v docs/vyvoj.rst.

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

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

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
 }

make/run

@@ -3,6 +3,6 @@
 set -exuo pipefail
 . make/lib.sh
 
-ensure_venv
+ensure_web_installed
 
 ./manage.py runserver "$@"

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

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" "

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

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

requirements.txt

@@ -62,3 +62,4 @@ lorem
 
 sphinx
 sphinx_rtd_theme
+myst_parser