Browse Source
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 :-)pull/11/head
Pavel "LEdoian" Turinsky
2 years ago
2 changed files with 179 additions and 50 deletions
@ -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. |
|||
|
|||
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 <https://git-scm.com>`_ |
|||
- `Python <https://python.org>`_ |
|||
|
|||
- 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 <https://gitea.ks.matfyz.cz>`_, 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 <https://editorconfig.org/>`_ |
|||
- Uživatelská zkušenost s `produkční verzí webu <https://mam.matfyz.cz>`_ |
|||
- Účet v `Kanci <https://kanboard.ledoian.cz>`_ |
|||
|
|||
.. 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 |
|||
<https://gitea.ks.matfyz.cz/mam/mamweb>`_.) 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 `<http://127.0.0.1:8000>`_. |
|||
|
|||
Časté problémy |
|||
^^^^^^ |
|||
|
|||
- ``make/install_web`` vypíše ``Error: pg_config executable not found.``: |
|||
Chybí ``libpq-dev`` |
|||
- Chybová hláška obsahuje ``#include <Python.h>``: 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 <soubor/y>`` nahraje data ze souborů do databáze |
|||
- ``./manage.py dumpdata <model>`` 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 |
|||
<https://docs.djangoproject.com/en/3.2/ref/django-admin/#available-commands>`_ |
|||
|
|||
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, …) |
|||
|
|||
|
|||
Loading…
Reference in new issue