Web M&M
https://mam.matfyz.cz
184 lines
7.4 KiB
184 lines
7.4 KiB
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 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 <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``), 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 <https://gitea.ks.matfyz.cz>`_, kde
|
|
bydlí gitový repozitář s kódem.
|
|
|
|
.. tip:: Potřebné balíčky v různých distribucích jsou sepsané v :ref:`tabulce
|
|
prerekvizit <Alternativní jména balíčků>`.
|
|
|
|
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/*``
|
|
- ``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 <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: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, …)
|
|
|
|
|