Lokální vývoj mamwebu ===================== 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 nějakého typického vývojáře webu – Linuxáka. 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``) a knihoven pro kompilaci Cčkových rozšíření (``python3-dev``) - Knihovna pro práci s PostgreSQL (``libpq-dev``) - 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. 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/*`` 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é, všechny by chtěly být sepsané jinde (ale zatím nejsou :-/) 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í - ``make/push_compiled_vue_to_test`` nahraje lokálně zkompilované části frontendu ve Vue na testweb (Gimli má typicky moc starou verzi nodejs, takže nejde kompilovat tam.) 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:o1`` až ``o3:o3`` - Řešitelské účty: ``r:r``, ``r1:r1`` až ``r3:r3`` 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, …)