diff --git a/Makefile b/Makefile index 94a377c4..fb967112 100644 --- a/Makefile +++ b/Makefile @@ -1,154 +1,9 @@ -PYTHON ?= python3 -VENV ?= ${PYTHON} -m venv -# Všechny flagy, které se s venvem/virtualenvem/... mají volat patří sem. Volá se "${VENV} cesta" -VENV_PATH ?= env -# Musí být definovaná, i kdyby to měla být "." +# Existence tohohle Makefile je tu jen proto, aby fungovala svalová paměť. Pokud můžete, použijte rovnou `make/…` +%: + # Používání make jako příkazu je zastaralé, prosím používej radši skripty ze složky make. Spouštím následující příkaz: + make/$* -.PHONY: all venv_check clean install install_web install_venv clean_venv clean_schema run test deploy_test deploy_prod sync_test_media sync_test_db sync_test sync_local_media sync_local_db sync_local +default: + @cat make/README.md -# activate by mělo být předpokladem ke všemu, co volá webový python (i.e. python nasazený do ${VENV}u kvůli webu, např. manage.py) -all: - @# Just echo: - # Install je trochu magický: - # Spusť následující posloupnost příkazů: - # make install_venv - # . ${VENV_PATH}/bin/activate - # make install_web - # - # Pokud install_web říká Error: pg_config executable not found. nainstaluj si libpq-dev - # Pokud chybová hláška obsahuje #include , nainstaluj si python3-dev - # - # Až skončíš s vývojem webu, spusť "deactivate". Tím zmizí '(${VENV_PATH})' ze začátku promptu. - -venv_check: - @# Pokud org nemá zapnutý venv, poradíme mu, aby si ho zapnul a spadneme. Jinak nic. - @expr $$PATH : ".*:*$(shell pwd)/${VENV_PATH}/bin" > /dev/null && exit 0 || echo 'Není zapnutý venv, spusť ". ${VENV_PATH}/bin/activate".\nPokud není venv nainstalovaný, spusť "make install_venv"' && false - -clean: clean_venv clean_schema - -install: install_web - -install_web: venv_check - @# venv může být příšerně starý, takže nejdříve upgradujeme venvové věci - pip install --upgrade pip - pip install --upgrade setuptools - # Instalace závislostí webu - pip install -r requirements.txt --upgrade - # Pro vygenerování tesdat spusť ./manage.py testdata - # Po vygenerování testdat spusť ./manage.py loaddata data/*, ať máš menu a další modely - # Pro synchronizaci flatpages spusť make sync_prod_flatpages - -install_venv: - ${VENV} ${VENV_PATH} - -clean_venv: - # Možná není 100% foolproof... - @test ! ${VENV_PATH} = . || ! echo "Smaž si prosím venv sám, nebudu mazat celý web" - rm -rfv ${VENV_PATH} - rm -f pip-selfcheck.json -clean_schema: - rm -f schema_seminar.pdf schema_all.pdf - -run: venv_check - ./manage.py runserver - -test: venv_check - ./manage.py test -v2 seminar mamweb - -# DB schemata - -schema: schema_seminar.pdf schema_all.pdf - -schema_seminar.pdf: venv_check - ./manage.py graph_models seminar | dot -Tpdf > schema_seminar.pdf - -schema_all.pdf: venv_check - ./manage.py graph_models -a -g | dot -Tpdf > schema_all.pdf - -# Deploy to current *mamweb-test* directory -deploy_test: venv_check - @if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi - @if [ `readlink -f .` != "/aux/akce/mam/www/mamweb-test" ]; then echo "Only possible in directory mamweb-test"; exit 1; fi - @echo "Installing version from origin/test ..." - git pull origin test - git clean -f - make install - ./manage.py migrate - ./manage.py collectstatic --noinput - (chown -R :mam . || true ) - (chmod -R g+rX,go-w . || true ) - @echo Restarting systemd unit - systemctl --user restart mamweb-test.service - @echo Done. - -# Deploy to current *mamweb-prod* directory -deploy_prod: venv_check - @if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi - @if [ `readlink -f .` != "/aux/akce/mam/www/mamweb-prod" ]; then echo "Only possible in directory mamweb-prod"; exit 1; fi - @echo "Backing up production DB ..." - ( cd -P .. && ./backup_prod_db.sh ) - @echo "Installing version from origin/master ..." - git pull origin master - git clean -f - make install - ./manage.py migrate - ./manage.py collectstatic --noinput - (chown -R :mam . || true ) - (chmod -R g+rX,go-w . || true ) - @echo Restarting systemd user unit for MaM web - systemctl --user restart mamweb-prod.service - @echo Done. - - -sync_prod_flatpages: venv_check - @echo Downloading current version of flatpages from mamweb-prod. - ssh mam-web@gimli.ms.mff.cuni.cz \ - "cd /akce/mam/www/mamweb-prod; . env/bin/activate; ./manage.py dumpdata flatpages --indent=2 > flat.json; ./fix_json.py flat.json flat_fixed.json" - rsync -ave ssh mam-web@gimli.ms.mff.cuni.cz:/akce/mam/www/mamweb-prod/flat_fixed.json data/flat.json - @echo "Applying downloaded flatpages." - ./manage.py loaddata data/flat.json - @echo "Done." - -# Sync test media directory with production -sync_test_media: - @if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi - @if [ `readlink -f .` != "/aux/akce/mam/www/mamweb-test" ]; then echo "Only possible in /akce/mam/www/mamweb-test"; exit 1; fi - rsync -av --delete /akce/mam/www/mamweb-prod/media/ ./media - -# Sync (with drop) test database with production database -sync_test_db_aggressive: - @if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi - pg_dump mam_test > dump-test-`date +"%Y%m%d_%H%M"`.sql - pg_dump -Fc mam_prod > dump-prod.sql - @# I am not sure which shell is used, so I am calling bash to make sure - psql mam_test -c 'DROP OWNED BY "mam-web";' - pg_restore -c --if-exists -d mam_test dump-prod.sql - rm dump-prod.sql - psql mam_test -c "UPDATE django_site SET name='MaMweb (test)', domain='mam-test.ks.matfyz.cz' WHERE id=1" - @echo Done. - -# Sync test with production -# HACK ALERT: using aggressive variant, due to the schemas being too different. -sync_test: sync_test_media sync_test_db_aggressive - - -# Sync media directory with atrey. Useful for local development with production database -# Does not sync Galerie and CACHE (too huge). -sync_local_media: - rsync -ave ssh --exclude Galerie --exclude CACHE\ - mam-web@gimli.ms.mff.cuni.cz:/akce/mam/www/mamweb-prod/media/ ./media/ -# Downloads and restores production database to local database. PostgreSQL only. -sync_local_db: - scp mam-web@gimli.ms.mff.cuni.cz:`ssh mam-web@gimli.ms.mff.cuni.cz 'ls -v /akce/mam/www/backups/mam_prod-*\.pgdump.xz | tail -n 1'` \ - ./last.pgdump.xz - xz -fd last.pgdump.xz - pg_restore -c -d mam-prod last.pgdump - -# Sync database and media. See above lines -sync_local: sync_local_media sync_local_db - -# Push local compiled Vue to gimli test site -push_compiled_vue_to_test: - scp vue_frontend/webpack-stats.json mam-web@gimli:/akce/mam/www/mamweb-test/vue_frontend/ - rsync -ave ssh seminar/static/seminar/vue mam-web@gimli:/akce/mam/www/mamweb-test/seminar/static/seminar/ - ssh mam-web@gimli.ms.mff.cuni.cz 'cd /akce/mam/www/mamweb-test/ && . env/bin/activate && ./manage.py collectstatic --noinput' +.PHONY: default diff --git a/README.md b/README.md index 369dd30e..94b8cf2d 100644 --- a/README.md +++ b/README.md @@ -1,77 +1,58 @@ -Basic commands for web development -================================== - -After you clone this repository, run `make`. It will download, locally install -and setup virtualenv and pip, and then locally install all required packages -from `requirements.txt`. - -When working with the code, always use the binaries in `./bin/`, such as -`bin/pip`, `bin/python`, ... never the global python, pip, ... -Use `make` and `./manage.py` for most things. - -Use git :-) - -Quickstart ----------- -Run the following commands: - make install_venv - . env/bin/activate - make install_web - -Pokud install_web říká Error: pg_config executable not found. nainstaluj si libpq-dev -Pokud chybová hláška obsahuje #include , nainstaluj si python3-dev - -After finishing development, run "deactivate". - -Make commands -------------- - -* `make install` (or `make`) - locally install and setup virtualpy, install - required packages. Ran again installs missing packages. Run after changing - `requirements.txt`. - -* `make clean` - remove local python packages. - -* `make veryclean` - remove local packages and virtualpy enviroment and - binaries. - -* `make run` - runs "./manage.py runserver_plus" - -* `make push_test` - pushes the last commited version to test location. - Only git-commited changes are pushed! Rest is re-generated from scratch. - At test server, the media data and database are kept the same. - Everything else not in .gitignore is deleted/overwritten on the test server. - -* `make schema` - generates graph of seminar and all schemas as PDF. Supercool! - -* `make sync_prod_flatpages` - downloads and applies static/flat pages from mamweb-prod - -./manage.py commands --------------------- - -* `./manage.py migrate` - update the database schema, initialise the database. - You need to run this in the beginning. - -* `./manage.py runserver_plus` - run a debugging server for the web. Slightly - enhanced compared to `./manage.py runserver`. - Open [127.0.0.1:8000](127.0.0.1:8000). - -* `./manage.py testdata` - create pseudo-random seminar data and admin/admin - user. - -* `./manage.py test` - run the tests. - -* `./manage.py shell` - run commands, list elemements of database, check syntax - by importing files, etc. - -Configurations --------------- - -* `mamweb/settings_common.py` contains most configuration options. -* `mamweb/settings.py` is used only for local development. -* `mamweb/settings_test.py` is used for testing on atrey. -* `mamweb/settings_prod.py` is used in production deployment. - -These are automatically switched by `make`. - - +Web M&M +====== + +Tohle je repozitář s kódem M&Mího webu. Pokud zde hledáte web samotný nebo +informace o semináři, najdete je na (a upřímně nechápu, +jak jste se dostali k tomuhle textu :-D) + +Pokud jste tu zůstali, tak vás beztak zajímá vývoj webu (a jestli ne, tak +budeme rádi, když začne :-)). + +Co je M&Mweb uvnitř +------ +Celý náš web je napsaný v [Pythonu](https://www.python.org) ve frameworku +[Django](https://www.djangoproject.com/). Web běží na serveru zvaném Gimli, +jako databázi používá PostgreSQL (pro lokální vývoj naopak SQLite) a všechen +náš kód je uložený v [Gitu](https://git-scm.com/) na [téhle +gitee](https://gitea.ks.matfyz.cz/). Pro dokumentaci používáme +[Sphinx](https://www.sphinx-doc.org). + + + +Jak si web pořídit +------ +Prosím přečti si podrobnější návod v (tady by bylo zbytečné +ho duplikovat). + +Jak web vyvíjet +---- + + +Na webu je mnoho věcí k dělání, některé ani nevyžadují kódění (třeba uhánění +orgů, aby si psali medailonky, aktualizace fotek, …), některé se naopak týkají +infrastruktury pod kódem (Gitea, Gimli, …). Je proto těžké mít na to úplně +obecný návod, tak tady je zhruba návod na úpravy kódu a pokud se něco z toho +nedá aplikovat, tak to prostě zkus nějak udělat jinak, po svém. (Omlouvám se +neinformatikům, ale líp to teď nesepíšu :-)) + +1. Nejprve si stáhni repozitář a rozběhni si lokální web u sebe (viz ). +1. Najdi si problém v Kanboardu (klikni na „Issues“ na Gitee) a/nebo se domluv + s webaři, na čem bys tak mohl/a pracovat. +1. Najdi místo, kde se to dá opravit a zkus to tam opravit. Uznávám, že tenhle + bod je otravně obecný, pokud tápeš, zkus se zeptat zkušenějších webařů nebo + podívat do dokumentace. +1. Vyzkoušej, že ti to lokálně funguje tak, jak má. +1. Zvládneš-li a máš-li čas, zkus to i zdokumentovat a/nebo napsat testy (TODO: chybí návod) +1. Po dohodě s webaři to vyzkoušej na testwebu +1. Pošli pull-request a případně zkus reagovat na komentáře +1. Až se změna začlení do hlavní větve (`master`) a nasadí se web na produkci, + můžeš mít radost, že se web bude používat lépe Tobě i ostatním orgům :-) + +### Proč pull-requesty? + + +Účelů pull-requestů je několik. Jednak doufáme, že pomůže webařům se orientovat +v kódu, jednak tím umožňujeme dělat experimenty a dávat si zpětnou vazbu. V +neposlední řadě pomáhají držet aspoň trochu konzistentní kód, což má pomoci +pohodě při programování… (A asi jsem na něco zapomněl :-)) 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/docs/tabulka_prerekvizit.rst b/docs/tabulka_prerekvizit.rst new file mode 100644 index 00000000..9dcce4c5 --- /dev/null +++ b/docs/tabulka_prerekvizit.rst @@ -0,0 +1,25 @@ +.. Není odkázaná z menu, je to záměr + +Tabulka prerekvizit v různých distribucích +========= + +.. admonition:: Metodika + + Na čistém repozitáři (``git clean -fxd``) a čistém systému spouštíme + ``make/init_local``. Když to spadne, tak do tabulky zapíšeme, co jsme + přiinstalovali. Protože větev ``makefiles`` aktuálně není mergenutá do + masteru, nefunguje synchronizace flatpages (a stejně nemáme SSH klíč), takže + tam ``make/init_local`` sestřelíme a vyzkoušíme, že ``make/test`` spustí + testy. + +.. Grafické tabulky (grid-tables, simple-tables) jsou strašný porod vyrábět, dlabu na to a cpu to do CSV… + +.. csv-table:: Prerekvizity v jednotlivých distribucích + :header: Distribuce / OS, Repozitář s Py3.9, venv, py knihovny, PostgreSQL knihovna, poznámky + + Ubuntu 22.10, ??, ``python3-venv``, ``python3-dev``, ``libpq-dev``, "Je potřeba zapnout zdroj ``universe`` a nainstalovat kompilátor C (``gcc``)?" + Linux Mint 21, ??, ``python3-venv``, ``python3-dev``, ``libpq-dev``, "" + Archlinux 2022.11.01, AUR, vestavěný, vestavěné, ``postgresql-libs``, "Je potřeba céčkový kompilátor (``gcc``)" + openSUSE Leap 15.4, oficiální (``python39``), předinstalovaný?, ``python39-devel``, ??FIXME!!, "Výchozí verze pythonu je 3.6 a ta je moc stará, potřeba instalovat ``gcc``. Nevím jak sehnat pg_config." + Debian 11, "oficiální, výchozí", ??, ??, ??, "Určitě to tam rozběhat jde, protože Gimli. Nejspíš bude relativně podobné Ubuntu." + diff --git a/docs/vyvoj.rst b/docs/vyvoj.rst index 438e8199..0d23972a 100644 --- a/docs/vyvoj.rst +++ b/docs/vyvoj.rst @@ -1,20 +1,184 @@ Lokální vývoj mamwebu ===================== -Stačí spustit:: - - ## Nahradte svym gimli username - git clone USER@gimli.ms.mff.cuni.cz:/akce/mam/git/mamweb.git mamweb - cd mamweb - ## Instalace je trochu magická, spusť následující posloupnost příkazů: - make install_venv - . env/bin/activate - make install_web - - ## Vygeneruje nejaka testovaci data (spis chuda) - ./manage.py testdata - ## Nahraje statické stránky, menu a obrázky v pozadí menu - ./manage.py loaddata data/* - ## Spusti testovaci server na http://127.0.0.1:8000/ - ./manage.py runserver - -Když si lokálně spustíte web, běží na http://127.0.0.1:8000/, admin najdete na http://127.0.0.1:8000/admin/ (admin/admin) Až skončíš s vývojem webu, spusť “deactivate”. Tím zmizí ‘(env)’ ze začátku promptu. \ No newline at end of file + +Asi hlavní část vývoje většiny webu probíhá lokálně. Každý tak může pracovat na +vlastních úpravách nezávisle na ostatních. + +Potřebné vybavení +------- + +Tento soupis cílí na Linuxáky. Jistě je +spousta dalších možností, které zde nejsou postihnuty – poraď se s webaři, +pokud si nejsi jistý. (Speciálně lze nějak vyvíjet na Windows, leč lze často +narazit na odlišné chování od Linuxu.) + +Motivace cílení na Linux je to, že Gimli je Linuxový stroj, takže je vývojové +prostředí pak podobné produkci a zmenšuje to množství odlišného chování. + +.. TODO: Na dokumentaci odlišného chování (Postgres vs. SQLite, Win vs. Linux, …) + by to asi chtělo výhledově separátní stránku, ale teď píšu tuhle :-) + +Nutné +^^^^ + +- `Git `_ +- `Python `_ + + - Ideálně ve verzi 3.9 (to je to, co je aktuálně (2022) na Gimlim) + - Včetně pip-u (na Ubuntu balíček ``python3-pip``), venvu (``python3-venv``) a knihoven pro kompilaci + Cčkových rozšíření (``python3-dev``) +- Knihovna pro práci s PostgreSQL (``libpq-dev``, protože jsou potřeba všechny db backendy) +- Webový prohlížeč +- \*NIXový shell (typicky ``bash``) + +.. TODO: Pokud tu něco chybí, tak to dopiš :-) + +Kromě toho je potřeba mít účet na `Gitee `_, kde +bydlí gitový repozitář s kódem. + +.. tip:: Potřebné balíčky v různých distribucích jsou sepsané v :ref:`tabulce + prerekvizit `. + +Doporučené +^^^^^^^^^^ + +- Python wheel (možná řeší problémy s potřebou ``-dev`` balíčků…) +- Editor / IDE podporující `Editorconfig `_ +- Uživatelská zkušenost s `produkční verzí webu `_ +- Účet v `Kanci `_ + +.. TODO: A nejspíš další věci, na které jsem si teď nevzpomněl. + + +Zprovoznění +------- + +Nejprve je potřeba stáhnout si repozitář. To se provede příkazem ``git clone +https://gitea.ks.matfyz.cz/mam/mamweb.git``, případně ``git clone +git@gitea.ks.matfyz.cz:mam/mamweb.git``, pokud už máš nahraný SSH klíč na +Giteu. (Obě adresy se dají zkopírovat ze `stránky repozitáře +`_.) To vyrobí složku ``mamweb``, přepni +se do ní (``cd mamweb``) + +O zprovoznění webu se stará skript ``make/install_web``, stačí ho spustit. Ten +vytvoří virtualenv (neexistuje-li) a nainstaluje do něj závislosti webu (podle +souboru ``requirements.txt``). + +.. FIXME: Novowebaři zmínka o requirements.txt tady moc nepomůže, to má být na + stránce o celkové stavbě repozitáře a stacku… + +Následně je potřeba nahrát další data do databáze, což uděláš pomocí příkazů +``./manage.py testdata`` a ``./manage.py loaddata data/*``. Skript +``make/install_web`` to kdyžtak na konci připomene. + +.. caution:: Zatímco skripty v ``make/`` to nepotřebují, pro použití skriptu + ``./manage.py`` (a dalších) se potřebuješ přepnout do virtuálního prostředí. + To uděláš velmi pravděpodobně spuštěním ``source env/bin/activate``, před + začátkem *promptu* by se mělo objevit ``(env)``. Pro opuštění spusť + ``deactivate``. + +Samotný web se spustí třeba pomocí ``make/run``, nebo ekvivalentně +``./manage.py runserver`` a pak je vidět na ``_. + +Časté problémy +^^^^^^ + +- ``make/install_web`` vypíše ``Error: pg_config executable not found.``: + Chybí ``libpq-dev`` +- Chybová hláška obsahuje ``#include ``: chybí ``python3-dev`` +- Na webu není vidět meníčko: spusť ``./manage.py loaddata data/*`` +- ``locale.Error: unsupported locale setting``: Chybí podpora pro příslušný + jazyk ve tvém systému. Odkomentuj příslušnou lokalizaci v ``/etc/locale.gen`` + a spusť ``locale-gen`` jako root, tím se to spraví. + +S dalšími problémy se zkus obrátit na další webaře, třeba někdo bude vědět :-) + +Příkazy pro ovládání webu +------- + +Příkazy se dělí do několika skupin. Některé souvisí přímo s webem, Djangem, +databází a podobně, ty typicky používají ``./manage.py``. Skripty pro +obhospodařování repozitáře a webu „zvenku“ typicky bydlí ve složce ``make/``. +Ostatní skripty jsou na náhodných místech :-) + +Tady jsou rozebrány jen příkazy relevantní pro lokální web a univerzálně +užitečné, ostatní najdeš v :ref:`Skripty pro práci s repozitářem`. + +Make skripty +^^^^^^^ + +- ``make/install_web`` nainstaluje závislosti webu +- ``make/run`` spustí web (ekvivalentní s ``./manage.py runserver``) +- ``make/schema`` nakreslí schéma vazeb modelů (může se hodit pro referenci a představu) +- ``make/test`` spustí testy (ale moc jich zatím není; ekvivalentní s ``./manage.py test``) +- ``make/sync_prod_flatpages`` stáhne statické stránky z produkčního webu a + uloží je do souboru v gitu, což umožňuje jejich verzování + +Manage.py skripty +^^^^^ + +.. note:: Je potřeba je spouštět ve virtuálním prostředí, viz výše. + +Všechny skripty kdyžtak mají ``--help``, dá se tak zjistit, co všechno umějí. + +- ``./manage.py testdata`` vygeneruje spíše chudá testovací data, aby bylo na + čem testovat web. +- ``./manage.py loaddata `` nahraje data ze souborů do databáze +- ``./manage.py dumpdata `` naopak z databáze vyrobí textovou reprezentaci +- ``./manage.py shell`` spustí interaktivní pythoní shell, ze kterého lze + interagovat s webem / Djangem. +- ``./manage.py dbshell`` spustí databázový shell (typicky používá SQL) + +- ``./manage.py makemigrations`` vyrobí popis migrací, ``./manage.py migrate`` + je spustí, ``showmigrations`` ukáže, které migrace jsou aplikované a které + ne. +- ``./manage.py runserver_plus`` spouští o něco lepší vývojový server (ale + nikdy jsem asi ty lepší featury nepoužil) + +Může se hodit vědět, že spuštění ``./manage.py`` bez parametrů vypíše seznam +všech příkazů, které lze spustit. + +Dokumentace djangových příkazů je v `dokumentaci Djanga +`_ + +Ostatní užitečné příkazy +^^^^^ + +- ``git status`` je univerzální nápověda na aktuální stav repozitáře a co s tím + lze dělat. +- ``git clean -fxd`` smaže všechny soubory, které nejsou uložené v gitu (včetně + ignorovaných). **Nebezpečný příkaz**, zamysli se, než ho spustíš + +Specifika lokálního webu +------- + +Lokální uživatelé +^^^^^^^ + +Přihlašovací údaje jsou psány jako ``login:heslo`` + +- Superuživatel: ``admin:admin`` +- Orgovské účty: ``o:o``, ``o1:o`` až ``o3:o`` +- Řešitelské účty: ``r:r``, ``r1:r`` až ``r3:r`` + +Všechny tyto účty jsou (?) svázané s nějakými fiktivními osobami, není ale zřejmé se +kterými, budeš to muset vyzkoušet a pak tady zdokumentovat :-) + +E-maily +^^^^^ + +Posílání e-mailů se lokálně dá zkoušet, e-mail se vypíše do terminálu, kde je +web spuštěn (e.g. pomocí ``make/run``). + +Pruhy +^^^^ + +To, že má lokální web po stranách zelené pruhy je normální a správně, slouží to +k vizuálnímu odlišení lokálního webu. + +.. TODO: Mít někde popis všech tří instancí a tady na něj pak odkázat. +.. - Tahák k používání gitových větví: do workflow, ne sem… +.. - Užitečné odkazy – kam se kouknout + (dohledávání views podle URL, settings_*, ) +.. - Zpříjemnění práce (ssh-klíče, tea, --help, …) + diff --git a/make/README.md b/make/README.md new file mode 100644 index 00000000..16b77901 --- /dev/null +++ b/make/README.md @@ -0,0 +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/init_local + make/run +a web potom najdeš na + diff --git a/make/deploy b/make/deploy new file mode 100755 index 00000000..b615f73f --- /dev/null +++ b/make/deploy @@ -0,0 +1,31 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +gimli_only +only_in_directory "$TESTWEB" + +CURRENT_BRANCH="$(git branch --show-current)" +BRANCH="${1:-$CURRENT_BRANCH}" + +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/deploy_prod b/make/deploy_prod new file mode 100755 index 00000000..ec3110c6 --- /dev/null +++ b/make/deploy_prod @@ -0,0 +1,25 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +gimli_only +only_in_directory "$PRODWEB" + +CURRENT_BRANCH="$(git branch --show-current)" +BRANCH="${1:-$CURRENT_BRANCH}" + +if test "$BRANCH" != master +then + echo "Pozor, nasazuješ na produkci větev, která není master ($BRANCH), chceš pokračovat? Pokud ne, sestřel tento skript." + read +fi + +# Záloha DB +( cd -P .. && ./backup_prod_db.sh ) + +safe_checkout_branch "$BRANCH" + +# Teď máme správnou větev, jdeme vše nainstalovat +install_everything +systemctl --user restart mamweb-prod.service 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/install b/make/install new file mode 120000 index 00000000..53e51b50 --- /dev/null +++ b/make/install @@ -0,0 +1 @@ +install_web \ No newline at end of file diff --git a/make/install_web b/make/install_web new file mode 100755 index 00000000..5ebf963d --- /dev/null +++ b/make/install_web @@ -0,0 +1,16 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +ensure_venv + +# Aktualizace toolchainu +pip install --upgrade pip setuptools +# Instalace závislostí webu +pip install -r requirements.txt --upgrade + +# XXX: Připomínka z původního Makefile: +echo 'Pro vygenerování tesdat spusť ./manage.py testdata +Po vygenerování testdat spusť ./manage.py loaddata data/*, ať máš menu a další modely +Pro synchronizaci flatpages spusť make/sync_prod_flatpages' diff --git a/make/lib.sh b/make/lib.sh new file mode 100644 index 00000000..9dc3d6c5 --- /dev/null +++ b/make/lib.sh @@ -0,0 +1,104 @@ +#!/bin/false Tohle je knihovna, nemá se spouštět, ale načítat pomocí source(1) nebo '.' + +PYTHON="${PYTHON:-python3}" +VENV="${VENV:-${PYTHON} -m venv}" +VENV_PATH="${VENV_PATH:-env}" +BRANCH="${BRANCH:-master}" + +REPO="${REPO:-git@gitea.ks.matfyz.cz:mam/mamweb.git}" +GIMLI='gimli.ms.mff.cuni.cz' +GIMLI_LOGIN="mam-web@$GIMLI" +# Skutečné cesty, jak je vrátí `realpath` +PRODWEB="/aux/akce/mam/www/mamweb-prod" +TESTWEB="/aux/akce/mam/www/mamweb-test" + +function die { + echo "$@" >&2 + exit 1 +} + +trap 'echo Něco se nepovedlo :-/' ERR + +# Vždycky chceme zajistit, že běžíme z rootu repozitáře +# TODO: chceme? Nechceme naopak umět to spouštět odkudkoliv, aspoň u většiny targetů? +test -e '.git' || die "Make skript spuštěn ve špatné složce, spusť ho z kořenového adresáře repozitáře." + +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 "$VENV_PATH/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 { + # Rovnou zkontrolujeme i uživatele + if test "$HOSTNAME" != gimli -o "$USER" != mam-web + then + echo "Tento příkaz se má spouštět na gimlim, chceš pokračovat? Pokud ne, sestřel tento skript." + read + fi +} + +function only_in_directory { + local DIR="$1" + local CURRENT="$(readlink -f .)" + if test "$CURRENT" != "$DIR" + then + echo "Tento příkaz se má spouštět ve složce $DIR, chceš pokračovat? Pokud ne, sestřel tento skript." + read + fi +} + +function safe_checkout_branch { + if test "$#" -ne 1 + then + echo >&2 "Použití: $0 " + return 1 + fi + + local BRANCH="$1" + local SCRIPT="$0" + + git fetch --all + # Od teď si musíme dát pozor, abychom nezměnili kód, který právě běží. + # Zkontrolujeme, že se nemění tahle knihovna a skript, který běží. + # `git rev-parse` dává SHA-1 hashe objektů, vizte manuálovou stránku pro pochopení. + # Pozor: tohle porovnává jen verze commitnuté do gitu. Lokální změny udělají něco náhodného… + if test "$(git rev-parse @:make/lib.sh)" != "$(git rev-parse "$BRANCH@{u}":make/lib.sh)" + then + echo >&2 "Změna v make/lib.sh, prosím pullni manuálně" + exit 1 + fi + if test "$(git rev-parse @:"$SCRIPT")" != "$(git rev-parse "$BRANCH@{u}":"$SCRIPT")" + then + echo >&2 "Změna v $SCRIPT, prosím pullni manuálně" + exit 1 + fi + git checkout "$BRANCH" + git pull + git clean -f +} + +function install_everything { + # Skoro celé nasazení webu je stejné pro testweb i pro produkci, tak je to tady dohromady + gimli_only + ensure_venv + 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/push_compiled_vue_to_test b/make/push_compiled_vue_to_test new file mode 100755 index 00000000..99495a7b --- /dev/null +++ b/make/push_compiled_vue_to_test @@ -0,0 +1,14 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +scp vue_frontend/webpack-stats.json "$GIMLI_LOGIN:$TESTWEB/vue_frontend/" +rsync -ave ssh seminar/static/seminar/vue "$GIMLI_LOGIN:$TESTWEB/seminar/static/seminar/" +ssh "$GIMLI_LOGIN" " + set -euxo pipefail + cd $TESTWEB + . make/lib.sh + ensure_venv + ./manage.py collectstatic --noinput + " diff --git a/make/run b/make/run new file mode 100755 index 00000000..c3caf58d --- /dev/null +++ b/make/run @@ -0,0 +1,8 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +ensure_web_installed + +./manage.py runserver "$@" diff --git a/make/schema b/make/schema new file mode 100755 index 00000000..05e84b61 --- /dev/null +++ b/make/schema @@ -0,0 +1,9 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +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 new file mode 100755 index 00000000..ca32c95b --- /dev/null +++ b/make/sync_prod_flatpages @@ -0,0 +1,20 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +ensure_web_installed + +# TODO: This is very ugly, will fix in a future PR (hopefully) +ssh "$GIMLI_LOGIN" " + set -euxo pipefail + cd $PRODWEB + . make/lib.sh + ensure_venv + ./manage.py dumpdata flatpages --indent=2 > flat.json + ./fix_json.py flat.json flat_fixed.json + " +rsync -ave ssh "$GIMLI_LOGIN:$PRODWEB/flat_fixed.json" data/flat.json + +./manage.py loaddata data/flat.json + diff --git a/make/sync_test b/make/sync_test new file mode 100755 index 00000000..68c6020d --- /dev/null +++ b/make/sync_test @@ -0,0 +1,11 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +# Prerekvizity nekontrolujeme, dokud voláme další make skripty, tak by akorát +# vedly k víc dotazům na stejnou věc a bylo by to otravné. Pokud tu někdy bude +# něco jiného, tak pak ať tu prerekvizity zmíněné jsou. + +make/sync_test_db_aggressive +make/sync_test_media diff --git a/make/sync_test_db_aggressive b/make/sync_test_db_aggressive new file mode 100755 index 00000000..9acce93b --- /dev/null +++ b/make/sync_test_db_aggressive @@ -0,0 +1,18 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +gimli_only +# Teoreticky není potřeba, ale stejně jinde make skripty nejsou a pouštět to z +# produkce nezní jako běžný stav, kromě toho to aktuálně vyrábí pomocné soubory +# v aktuální složce (FIXME do budoucna) a to na produkci nechceme +only_in_directory "$TESTWEB" + +pg_dump mam_test > "dump-test-$(date +"%Y%m%d_%H%M").sql" +pg_dump -Fc mam_prod > dump-prod.sql +psql mam_test -c 'DROP OWNED BY "mam-web";' +pg_restore -c --if-exists -d mam_test dump-prod.sql +rm dump-prod.sql +psql mam_test -c "UPDATE django_site SET name='MaMweb (test)', domain='mam-test.ks.matfyz.cz' WHERE id=1" + diff --git a/make/sync_test_media b/make/sync_test_media new file mode 100755 index 00000000..44b0e830 --- /dev/null +++ b/make/sync_test_media @@ -0,0 +1,9 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +gimli_only +only_in_directory "$TESTWEB" + +rsync -av --delete "$PRODWEB/media/" ./media diff --git a/make/test b/make/test new file mode 100755 index 00000000..155d03fa --- /dev/null +++ b/make/test @@ -0,0 +1,9 @@ +#!/bin/bash + +set -exuo pipefail +. make/lib.sh + +ensure_web_installed + +trap - ERR # Testy nejspíš selžou, ale nechceme kolem toho dělat další chybovou hlášku. +./manage.py test -v2