mamweb/docs/vyvoj.rst

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 <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/*``
- ``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é, 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: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, …)