From bac44b41f8a489b0ac2a3d6af449632c9b264539 Mon Sep 17 00:00:00 2001 From: "Pavel \"LEdoian\" Turinsky" Date: Sun, 20 Nov 2022 15:39:20 +0100 Subject: [PATCH] =?UTF-8?q?Dokumentace=20lok=C3=A1ln=C3=ADho=20v=C3=BDvoje?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Obsahuje tipy z Readme, obsahuje velkou část make/README.md. Zatím nevím, co provedu s make/README.md, ale na něco třeba přijdu :-) --- docs/vyvoj.rst | 197 ++++++++++++++++++++++++++++++++++++++++++++----- make/README.md | 32 -------- 2 files changed, 179 insertions(+), 50 deletions(-) diff --git a/docs/vyvoj.rst b/docs/vyvoj.rst index 438e8199..3bfdace8 100644 --- a/docs/vyvoj.rst +++ b/docs/vyvoj.rst @@ -1,20 +1,181 @@ 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 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, …) + diff --git a/make/README.md b/make/README.md index 1d1baa47..f7e873f1 100644 --- a/make/README.md +++ b/make/README.md @@ -1,34 +1,2 @@ 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. -Předně: většina příkazů bude asi vypisovat spoustu detailů, takže ti doporučuji -si tento text otevřít někde separátně. Nachází se v repozitáři v -`make/README.md`, případně si jej můžeš zobrazit hezčeji vykreslený na -[Gitee](https://gitea.ks.matfyz.cz/mam/mamweb/src/branch/master/make/README.md). - -O zprovoznění webu se stará hlavně skript `make/install_web`. Ten vytvoří -virtualenv (neexistuje-li) a nainstaluje do něj závislosti webu. Pak ovšem -budeš potřebovat 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` ti to kdyžtak připomene. - -Samotný web spustíš třeba pomocí `make/run`, nebo ekvivalentně `./manage.py runserver`. - -Pozor: zatímco skripty v `make/` to nepotřebují, pro použití skriptu -`./manage.py` 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`. - -Časté problémy ------ -Je možné, že nemáš všechny potřebné závislosti v systému. Proto je možné, že -`make/install_web` vyhodí nějakou chybovou hlášku: - -- `Error: pg_config executable not found.`: nainstaluj si `libpq-dev` (na Ubuntu/Debianu, jinde se příslušný balíček může jmenovat jinak) -- Chybová hláška obsahuje `#include `: nainstaluj si `python3-dev` - - -