184 lines
7.4 KiB
ReStructuredText
184 lines
7.4 KiB
ReStructuredText
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, …)
|
||
|