Browse Source

Merge branch 'makefiles' into make_docs

pull/11/head
Pavel "LEdoian" Turinsky 2 years ago
parent
commit
55ffdf8941
  1. 1
      docs/index.rst
  2. 108
      docs/skripty.rst
  3. 9
      make/README.md
  4. 15
      make/deploy
  5. 10
      make/init_local
  6. 14
      make/lib.sh
  7. 2
      make/run
  8. 2
      make/schema
  9. 2
      make/sync_prod_flatpages
  10. 2
      make/sync_test_media
  11. 3
      make/test
  12. 1
      requirements.txt

1
docs/index.rst

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

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

9
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 <http://127.0.0.1:8000>
Pro detaily a nápovědu si prosím přečti dokumentaci v docs/vyvoj.rst.

15
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

10
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

14
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
}

2
make/run

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

2
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

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

2
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

3
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

1
requirements.txt

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

Loading…
Cancel
Save