Dokumentace lokálního vývoje
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 :-)
This commit is contained in:
Pavel "LEdoian" Turinsky
parent
50eaaf9eb7
commit
bac44b41f8
2 changed files with 176 additions and 47 deletions
191
docs/vyvoj.rst
191
docs/vyvoj.rst
|
|
@ -1,20 +1,181 @@
|
||||||
Lokální vývoj mamwebu
|
Lokální vývoj mamwebu
|
||||||
=====================
|
=====================
|
||||||
Stačí spustit::
|
|
||||||
|
|
||||||
## Nahradte svym gimli username
|
Asi hlavní část vývoje většiny webu probíhá lokálně. Každý tak může pracovat na
|
||||||
git clone USER@gimli.ms.mff.cuni.cz:/akce/mam/git/mamweb.git mamweb
|
vlastních úpravách nezávisle na ostatních.
|
||||||
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)
|
Potřebné vybavení
|
||||||
./manage.py testdata
|
-------
|
||||||
## Nahraje statické stránky, menu a obrázky v pozadí menu
|
|
||||||
./manage.py loaddata data/*
|
Tento soupis cílí na nějakého typického vývojáře webu – Linuxáka. Jistě je
|
||||||
## Spusti testovaci server na http://127.0.0.1:8000/
|
spousta dalších možností, které zde nejsou postihnuty – poraď se s webaři,
|
||||||
./manage.py runserver
|
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, …)
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
@ -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.
|
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 <Python.h>`: nainstaluj si `python3-dev`
|
|
||||||
|
|
||||||
|
|
||||||
<!--
|
|
||||||
FIXME: Protože tento soubor vypisujeme, tak nemůžeme zobrazit aktuální cestu
|
|
||||||
venvu, takže tu kvůli tomu jsou hardcodované cesty. Asi by se mohl nějak
|
|
||||||
generovat ze šablony, která má přístup k make/lib.sh, ale zatím to není implementované.
|
|
||||||
-->
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue