Browse Source

Merge branch 'makefiles'

pull/18/head
Jonas Havelka 2 years ago
parent
commit
1200d77dbc
  1. 159
      Makefile
  2. 135
      README.md
  3. 1
      docs/index.rst
  4. 108
      docs/skripty.rst
  5. 25
      docs/tabulka_prerekvizit.rst
  6. 200
      docs/vyvoj.rst
  7. 8
      make/README.md
  8. 31
      make/deploy
  9. 25
      make/deploy_prod
  10. 10
      make/init_local
  11. 1
      make/install
  12. 16
      make/install_web
  13. 104
      make/lib.sh
  14. 14
      make/push_compiled_vue_to_test
  15. 8
      make/run
  16. 9
      make/schema
  17. 20
      make/sync_prod_flatpages
  18. 11
      make/sync_test
  19. 18
      make/sync_test_db_aggressive
  20. 9
      make/sync_test_media
  21. 9
      make/test

159
Makefile

@ -1,154 +1,9 @@
PYTHON ?= python3
VENV ?= ${PYTHON} -m venv
# Všechny flagy, které se s venvem/virtualenvem/... mají volat patří sem. Volá se "${VENV} cesta"
VENV_PATH ?= env
# Musí být definovaná, i kdyby to měla být "."
# Existence tohohle Makefile je tu jen proto, aby fungovala svalová paměť. Pokud můžete, použijte rovnou `make/…`
%:
# Používání make jako příkazu je zastaralé, prosím používej radši skripty ze složky make. Spouštím následující příkaz:
make/$*
.PHONY: all venv_check clean install install_web install_venv clean_venv clean_schema run test deploy_test deploy_prod sync_test_media sync_test_db sync_test sync_local_media sync_local_db sync_local
default:
@cat make/README.md
# activate by mělo být předpokladem ke všemu, co volá webový python (i.e. python nasazený do ${VENV}u kvůli webu, např. manage.py)
all:
@# Just echo:
# Install je trochu magický:
# Spusť následující posloupnost příkazů:
# make install_venv
# . ${VENV_PATH}/bin/activate
# make install_web
#
# Pokud install_web říká Error: pg_config executable not found. nainstaluj si libpq-dev
# Pokud chybová hláška obsahuje #include <Python.h>, nainstaluj si python3-dev
#
# Až skončíš s vývojem webu, spusť "deactivate". Tím zmizí '(${VENV_PATH})' ze začátku promptu.
venv_check:
@# Pokud org nemá zapnutý venv, poradíme mu, aby si ho zapnul a spadneme. Jinak nic.
@expr $$PATH : ".*:*$(shell pwd)/${VENV_PATH}/bin" > /dev/null && exit 0 || echo 'Není zapnutý venv, spusť ". ${VENV_PATH}/bin/activate".\nPokud není venv nainstalovaný, spusť "make install_venv"' && false
clean: clean_venv clean_schema
install: install_web
install_web: venv_check
@# venv může být příšerně starý, takže nejdříve upgradujeme venvové věci
pip install --upgrade pip
pip install --upgrade setuptools
# Instalace závislostí webu
pip install -r requirements.txt --upgrade
# Pro vygenerování tesdat spusť ./manage.py testdata
# Po vygenerování testdat spusť ./manage.py loaddata data/*, ať máš menu a další modely
# Pro synchronizaci flatpages spusť make sync_prod_flatpages
install_venv:
${VENV} ${VENV_PATH}
clean_venv:
# Možná není 100% foolproof...
@test ! ${VENV_PATH} = . || ! echo "Smaž si prosím venv sám, nebudu mazat celý web"
rm -rfv ${VENV_PATH}
rm -f pip-selfcheck.json
clean_schema:
rm -f schema_seminar.pdf schema_all.pdf
run: venv_check
./manage.py runserver
test: venv_check
./manage.py test -v2 seminar mamweb
# DB schemata
schema: schema_seminar.pdf schema_all.pdf
schema_seminar.pdf: venv_check
./manage.py graph_models seminar | dot -Tpdf > schema_seminar.pdf
schema_all.pdf: venv_check
./manage.py graph_models -a -g | dot -Tpdf > schema_all.pdf
# Deploy to current *mamweb-test* directory
deploy_test: venv_check
@if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi
@if [ `readlink -f .` != "/aux/akce/mam/www/mamweb-test" ]; then echo "Only possible in directory mamweb-test"; exit 1; fi
@echo "Installing version from origin/test ..."
git pull origin test
git clean -f
make install
./manage.py migrate
./manage.py collectstatic --noinput
(chown -R :mam . || true )
(chmod -R g+rX,go-w . || true )
@echo Restarting systemd unit
systemctl --user restart mamweb-test.service
@echo Done.
# Deploy to current *mamweb-prod* directory
deploy_prod: venv_check
@if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi
@if [ `readlink -f .` != "/aux/akce/mam/www/mamweb-prod" ]; then echo "Only possible in directory mamweb-prod"; exit 1; fi
@echo "Backing up production DB ..."
( cd -P .. && ./backup_prod_db.sh )
@echo "Installing version from origin/master ..."
git pull origin master
git clean -f
make install
./manage.py migrate
./manage.py collectstatic --noinput
(chown -R :mam . || true )
(chmod -R g+rX,go-w . || true )
@echo Restarting systemd user unit for MaM web
systemctl --user restart mamweb-prod.service
@echo Done.
sync_prod_flatpages: venv_check
@echo Downloading current version of flatpages from mamweb-prod.
ssh mam-web@gimli.ms.mff.cuni.cz \
"cd /akce/mam/www/mamweb-prod; . env/bin/activate; ./manage.py dumpdata flatpages --indent=2 > flat.json; ./fix_json.py flat.json flat_fixed.json"
rsync -ave ssh mam-web@gimli.ms.mff.cuni.cz:/akce/mam/www/mamweb-prod/flat_fixed.json data/flat.json
@echo "Applying downloaded flatpages."
./manage.py loaddata data/flat.json
@echo "Done."
# Sync test media directory with production
sync_test_media:
@if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi
@if [ `readlink -f .` != "/aux/akce/mam/www/mamweb-test" ]; then echo "Only possible in /akce/mam/www/mamweb-test"; exit 1; fi
rsync -av --delete /akce/mam/www/mamweb-prod/media/ ./media
# Sync (with drop) test database with production database
sync_test_db_aggressive:
@if [ ${USER} != "mam-web" ]; then echo "Only possible by user mam-web"; exit 1; fi
pg_dump mam_test > dump-test-`date +"%Y%m%d_%H%M"`.sql
pg_dump -Fc mam_prod > dump-prod.sql
@# I am not sure which shell is used, so I am calling bash to make sure
psql mam_test -c 'DROP OWNED BY "mam-web";'
pg_restore -c --if-exists -d mam_test dump-prod.sql
rm dump-prod.sql
psql mam_test -c "UPDATE django_site SET name='MaMweb (test)', domain='mam-test.ks.matfyz.cz' WHERE id=1"
@echo Done.
# Sync test with production
# HACK ALERT: using aggressive variant, due to the schemas being too different.
sync_test: sync_test_media sync_test_db_aggressive
# Sync media directory with atrey. Useful for local development with production database
# Does not sync Galerie and CACHE (too huge).
sync_local_media:
rsync -ave ssh --exclude Galerie --exclude CACHE\
mam-web@gimli.ms.mff.cuni.cz:/akce/mam/www/mamweb-prod/media/ ./media/
# Downloads and restores production database to local database. PostgreSQL only.
sync_local_db:
scp mam-web@gimli.ms.mff.cuni.cz:`ssh mam-web@gimli.ms.mff.cuni.cz 'ls -v /akce/mam/www/backups/mam_prod-*\.pgdump.xz | tail -n 1'` \
./last.pgdump.xz
xz -fd last.pgdump.xz
pg_restore -c -d mam-prod last.pgdump
# Sync database and media. See above lines
sync_local: sync_local_media sync_local_db
# Push local compiled Vue to gimli test site
push_compiled_vue_to_test:
scp vue_frontend/webpack-stats.json mam-web@gimli:/akce/mam/www/mamweb-test/vue_frontend/
rsync -ave ssh seminar/static/seminar/vue mam-web@gimli:/akce/mam/www/mamweb-test/seminar/static/seminar/
ssh mam-web@gimli.ms.mff.cuni.cz 'cd /akce/mam/www/mamweb-test/ && . env/bin/activate && ./manage.py collectstatic --noinput'
.PHONY: default

135
README.md

@ -1,77 +1,58 @@
Basic commands for web development
==================================
After you clone this repository, run `make`. It will download, locally install
and setup virtualenv and pip, and then locally install all required packages
from `requirements.txt`.
When working with the code, always use the binaries in `./bin/`, such as
`bin/pip`, `bin/python`, ... never the global python, pip, ...
Use `make` and `./manage.py` for most things.
Use git :-)
Quickstart
----------
Run the following commands:
make install_venv
. env/bin/activate
make install_web
Pokud install_web říká Error: pg_config executable not found. nainstaluj si libpq-dev
Pokud chybová hláška obsahuje #include <Python.h>, nainstaluj si python3-dev
After finishing development, run "deactivate".
Make commands
-------------
* `make install` (or `make`) - locally install and setup virtualpy, install
required packages. Ran again installs missing packages. Run after changing
`requirements.txt`.
* `make clean` - remove local python packages.
* `make veryclean` - remove local packages and virtualpy enviroment and
binaries.
* `make run` - runs "./manage.py runserver_plus"
* `make push_test` - pushes the last commited version to test location.
Only git-commited changes are pushed! Rest is re-generated from scratch.
At test server, the media data and database are kept the same.
Everything else not in .gitignore is deleted/overwritten on the test server.
* `make schema` - generates graph of seminar and all schemas as PDF. Supercool!
* `make sync_prod_flatpages` - downloads and applies static/flat pages from mamweb-prod
./manage.py commands
--------------------
* `./manage.py migrate` - update the database schema, initialise the database.
You need to run this in the beginning.
* `./manage.py runserver_plus` - run a debugging server for the web. Slightly
enhanced compared to `./manage.py runserver`.
Open [127.0.0.1:8000](127.0.0.1:8000).
* `./manage.py testdata` - create pseudo-random seminar data and admin/admin
user.
* `./manage.py test` - run the tests.
* `./manage.py shell` - run commands, list elemements of database, check syntax
by importing files, etc.
Configurations
--------------
* `mamweb/settings_common.py` contains most configuration options.
* `mamweb/settings.py` is used only for local development.
* `mamweb/settings_test.py` is used for testing on atrey.
* `mamweb/settings_prod.py` is used in production deployment.
These are automatically switched by `make`.
Web M&M
======
Tohle je repozitář s kódem M&Mího webu. Pokud zde hledáte web samotný nebo
informace o semináři, najdete je na <https://mam.matfyz.cz> (a upřímně nechápu,
jak jste se dostali k tomuhle textu :-D)
Pokud jste tu zůstali, tak vás beztak zajímá vývoj webu (a jestli ne, tak
budeme rádi, když začne :-)).
Co je M&Mweb uvnitř
------
Celý náš web je napsaný v [Pythonu](https://www.python.org) ve frameworku
[Django](https://www.djangoproject.com/). Web běží na serveru zvaném Gimli,
jako databázi používá PostgreSQL (pro lokální vývoj naopak SQLite) a všechen
náš kód je uložený v [Gitu](https://git-scm.com/) na [téhle
gitee](https://gitea.ks.matfyz.cz/). Pro dokumentaci používáme
[Sphinx](https://www.sphinx-doc.org).
<!--TODO: Z odstavce výše by ideálně měla být zachována jen první věta a zbytek
by měl být někde v docs s podrobnějším popisem…-->
Jak si web pořídit
------
Prosím přečti si podrobnější návod v <docs/vyvoj.rst> (tady by bylo zbytečné
ho duplikovat).
Jak web vyvíjet
----
<!--TODO: Napsat obšírněji, asi zase do docs/-->
Na webu je mnoho věcí k dělání, některé ani nevyžadují kódění (třeba uhánění
orgů, aby si psali medailonky, aktualizace fotek, …), některé se naopak týkají
infrastruktury pod kódem (Gitea, Gimli, …). Je proto těžké mít na to úplně
obecný návod, tak tady je zhruba návod na úpravy kódu a pokud se něco z toho
nedá aplikovat, tak to prostě zkus nějak udělat jinak, po svém. (Omlouvám se
neinformatikům, ale líp to teď nesepíšu :-))
1. Nejprve si stáhni repozitář a rozběhni si lokální web u sebe (viz <docs/vyvoj.rst>).
1. Najdi si problém v Kanboardu (klikni na „Issues“ na Gitee) a/nebo se domluv
s webaři, na čem bys tak mohl/a pracovat.
1. Najdi místo, kde se to dá opravit a zkus to tam opravit. Uznávám, že tenhle
bod je otravně obecný, pokud tápeš, zkus se zeptat zkušenějších webařů nebo
podívat do dokumentace.
1. Vyzkoušej, že ti to lokálně funguje tak, jak má.
1. Zvládneš-li a máš-li čas, zkus to i zdokumentovat a/nebo napsat testy (TODO: chybí návod)
1. Po dohodě s webaři to vyzkoušej na testwebu
1. Pošli pull-request a případně zkus reagovat na komentáře
1. Až se změna začlení do hlavní větve (`master`) a nasadí se web na produkci,
můžeš mít radost, že se web bude používat lépe Tobě i ostatním orgům :-)
### Proč pull-requesty?
<!--FIXME: Tohle ale už úplně patří do docs a ne sem, jen je zatím nemám prozkoumané…-->
Účelů pull-requestů je několik. Jednak doufáme, že pomůže webařům se orientovat
v kódu, jednak tím umožňujeme dělat experimenty a dávat si zpětnou vazbu. V
neposlední řadě pomáhají držet aspoň trochu konzistentní kód, což má pomoci
pohodě při programování… (A asi jsem na něco zapomněl :-))

1
docs/index.rst

@ -13,6 +13,7 @@ Vítejte v dokumentaci M&Mího webu!
vyvoj
sphinx
dalsi_soubory
skripty
modules/modules
zapisy/zapisy

108
docs/skripty.rst

@ -0,0 +1,108 @@
Skripty pro práci s repozitářem
===================
Máme dvě hlavní sady skriptů/příkazů na ovládání webu a repozitáře. Skripty pro
práci s webem psané v Pythonu jsou uložené ve složkách
``<aplikace>/management/commands/``, případně vestavěné, a volají se pomocí
``./manage.py <příkaz>``. Oproti tomu skripty pro práci s repozitářem a pro
úpravy databáze a souborů „zvenčí“ se nejčastěji nacházejí ve složce ``make/``
a volají se pomocí cesty: ``make/<příkaz>``.
Občas existují i nějaké další skripty na různých jiných místech. Všechny by
měly být ideálně popsány asi tady.
Make skripty
----
Skripty v ``make/`` se označují jako „Make skripty“. Slouží často k velkým
úkonům s repozitářem, jako je nasazení celého webu, zprovoznění lokálního webu
a podobně.
.. note:: Označení pro tyto skripty je dáno tím, že byly původně volány pomocí
make (tj. z Makefile). Ve skutečnosti je lze stále volat i jako ``make
<skript>``, ale pak není možné předávat parametry a obecně je tato cesta
zastaralá a existuje jen pro zpětnou kompatibilitu se svalovou pamětí.
Tyto skripty jsou samonosné, dají se spustit rovnou a v případě problémů si
budou hlasitě stěžovat. Pro účely debugování různých věcí jsou ale (bohužel?)
hlasité i při normálním spuštění, konkrétně vypisují všechny příkazy, které se
spouštějí (\ ``set -x``). Tyto příkazy jsou vidět za jedním či více plusky (\ ``+``).
.. tip:: Pokud některý make skript selže, tak by na konci měl vypsat, že se něco nepovedlo.
Knihovna ``make/lib.sh``
^^^^^^
Pro pohodlí při psaní velká část z nich využívá knihovnu uloženou
v ``make/lib.sh``. Jsou zde definované užitečné proměnné, kontroly a společný
kód. Kromě toho při inicializaci otestuje, že je skript spuštěn z kořene
repozitáře (takže to pak není potřeba zkoumat v ostatních skriptech).
Proměnné
"""""
Popsány jsou jen užitečné proměnné, ve skutečnosti jich je definovaných víc,
ale jsou triviální a samopopisné.
``VENV_PATH``
Cesta virtuálního prostředí. Též lze přepsat.
``REPO``
Cesta ke gitovému repozitáři na serveru, rovnou použitelná v ``git clone``
``GIMLI_LOGIN``
Přihlašovací údaje ke Gimlimu
``PRODWEB`` a ``TESTWEB``
Cesty ke složkám s produkčním a testovacím webem
Funkce a další zkratky
""""""
``ensure_venv``
Zajistí, že se zbytek skriptu spustí ve virtuálním prostředí, a pokud neexistuje, tak jej založí.
``ensure_web_installed``
Vyzkouší, že je web (django) aspoň elementárně zprovozněno a pokud ne, tak vyzve uživatele, aby to spravil.
``gimli_only``
Otestuje, že je příkaz spuštěn na Gimlim, pokud tomu tak není, zeptá se, jestli si uživatel skutečně přeje zbytek skriptu vykonat
``only_in_directory <složka>``
Otestuje, že skript běží z konkrétní složky. Zejména použitelné s ``gimli_only`` a ``$TESTWEB``
``safe_checkout_branch <větev>``
Bezpečně přepne repozitář na jinou větev. Pokud by mělo dojít k přepsání
knihovny nebo volajícího make skriptu, vyzve uživatele, aby přepnul ručně.
``install_everything``
Společná část kódu pro nasazování produkce a testwebu.
Skripty pro lokální vývoj
^^^^^^^
``make/install_web`` (nebo ekvivalentně ``make/install``)
Vytvoří virtualenv a nainstaluje do něj závislosti webu podle ``requirements.txt``. Následně popíše, jak vyrobit zbytek lokálního webu.
``make/run``
Spustí lokální web (ekvivalentní s ``./manage.py runserver``)
``make/schema``
Vykreslí závislosti a atributy modelů
``make/sync_prod_flatpages``
Stáhne z produkce aktuální statické stránky a uloží je do složky ``data/``
``make/test``
Spustí testy (ekvivalentní s ``./manage.py test -v2``)
``make/init_local``
Zkratka za posloupnost ``make/install_web``, ``./manage.py testdata``, ``./manage.py loaddata data/*``, ``make/sync_prod_flatpages``
Práce s testwebem
^^^^^^^
``make/deploy``
Nasadí testweb. Volitelně bere jako parametr jméno větve, kterou má nasadit.
Rovnou nastaví přihlašování a vygeneruje příslušnou verzi dokumentace `sem <https://mam-test.ks.matfyz.cz/docs>`_.
``make/push_compiled_vue_to_test``
**Neotestováno** Nahraje Vue z lokálního počítače na testweb. (Gimli často má moc starou verzi Node.js, takže nejde zkompilovat tam)
``make/sync_test_db_aggressive``
Zkopíruje databázi z produkčního webu.
``make/sync_test_media``
Zkopíruje média (obrázky, nahrané soubory) z produkčního webu.
``make/sync_test``
Zkratka za ``make/sync_test_db_aggressive`` + ``make/sync_test_media``.
Nasazení produkce
^^^^
``make/deploy_prod``. Před samotným nasazením zálohuje databázi a zkontroluje, že se nasazuje větev ``master``.

25
docs/tabulka_prerekvizit.rst

@ -0,0 +1,25 @@
.. Není odkázaná z menu, je to záměr
Tabulka prerekvizit v různých distribucích
=========
.. admonition:: Metodika
Na čistém repozitáři (``git clean -fxd``) a čistém systému spouštíme
``make/init_local``. Když to spadne, tak do tabulky zapíšeme, co jsme
přiinstalovali. Protože větev ``makefiles`` aktuálně není mergenutá do
masteru, nefunguje synchronizace flatpages (a stejně nemáme SSH klíč), takže
tam ``make/init_local`` sestřelíme a vyzkoušíme, že ``make/test`` spustí
testy.
.. Grafické tabulky (grid-tables, simple-tables) jsou strašný porod vyrábět, dlabu na to a cpu to do CSV…
.. csv-table:: Prerekvizity v jednotlivých distribucích
:header: Distribuce / OS, Repozitář s Py3.9, venv, py knihovny, PostgreSQL knihovna, poznámky
Ubuntu 22.10, ??, ``python3-venv``, ``python3-dev``, ``libpq-dev``, "Je potřeba zapnout zdroj ``universe`` a nainstalovat kompilátor C (``gcc``)?"
Linux Mint 21, ??, ``python3-venv``, ``python3-dev``, ``libpq-dev``, ""
Archlinux 2022.11.01, AUR, vestavěný, vestavěné, ``postgresql-libs``, "Je potřeba céčkový kompilátor (``gcc``)"
openSUSE Leap 15.4, oficiální (``python39``), předinstalovaný?, ``python39-devel``, ??FIXME!!, "Výchozí verze pythonu je 3.6 a ta je moc stará, potřeba instalovat ``gcc``. Nevím jak sehnat pg_config."
Debian 11, "oficiální, výchozí", ??, ??, ??, "Určitě to tam rozběhat jde, protože Gimli. Nejspíš bude relativně podobné Ubuntu."

200
docs/vyvoj.rst

@ -1,20 +1,184 @@
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 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 <Tabulka prerekvizit v různých distribucích>`.
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````o3:o``
- Řešitelské účty: ``r:r``, ``r1:r````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, …)

8
make/README.md

@ -0,0 +1,8 @@
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.
Pro detaily a nápovědu si prosím přečti dokumentaci v docs/vyvoj.rst.
TL;DR: Web vyrobíš pomocí následující posloupnosti příkazů:
make/init_local
make/run
a web potom najdeš na <http://127.0.0.1:8000>

31
make/deploy

@ -0,0 +1,31 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
gimli_only
only_in_directory "$TESTWEB"
CURRENT_BRANCH="$(git branch --show-current)"
BRANCH="${1:-$CURRENT_BRANCH}"
safe_checkout_branch "$BRANCH"
# Teď máme správnou větev, jdeme vše nainstalovat
install_everything
systemctl --user restart mamweb-test.service
# Přihlášení
htpasswd -bc .htpasswd test lisakjelisak
setfacl -m u:www-data:r .htpasswd
# Build dokumentace
ensure_venv
(
cd docs
make html
)
# Oprava práv k dokumentaci
setfacl -m u:www-data:x . docs docs/_build
setfacl -R -m u:www-data:rX docs/_build/html
setfacl -R -m default:u:www-data:rX docs/_build/html

25
make/deploy_prod

@ -0,0 +1,25 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
gimli_only
only_in_directory "$PRODWEB"
CURRENT_BRANCH="$(git branch --show-current)"
BRANCH="${1:-$CURRENT_BRANCH}"
if test "$BRANCH" != master
then
echo "Pozor, nasazuješ na produkci větev, která není master ($BRANCH), chceš pokračovat? Pokud ne, sestřel tento skript."
read
fi
# Záloha DB
( cd -P .. && ./backup_prod_db.sh )
safe_checkout_branch "$BRANCH"
# Teď máme správnou větev, jdeme vše nainstalovat
install_everything
systemctl --user restart mamweb-prod.service

10
make/init_local

@ -0,0 +1,10 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
make/install_web
ensure_venv
./manage.py testdata
./manage.py loaddata data/*
make/sync_prod_flatpages

1
make/install

@ -0,0 +1 @@
install_web

16
make/install_web

@ -0,0 +1,16 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
ensure_venv
# Aktualizace toolchainu
pip install --upgrade pip setuptools
# Instalace závislostí webu
pip install -r requirements.txt --upgrade
# XXX: Připomínka z původního Makefile:
echo 'Pro vygenerování tesdat spusť ./manage.py testdata
Po vygenerování testdat spusť ./manage.py loaddata data/*, ať máš menu a další modely
Pro synchronizaci flatpages spusť make/sync_prod_flatpages'

104
make/lib.sh

@ -0,0 +1,104 @@
#!/bin/false Tohle je knihovna, nemá se spouštět, ale načítat pomocí source(1) nebo '.'
PYTHON="${PYTHON:-python3}"
VENV="${VENV:-${PYTHON} -m venv}"
VENV_PATH="${VENV_PATH:-env}"
BRANCH="${BRANCH:-master}"
REPO="${REPO:-git@gitea.ks.matfyz.cz:mam/mamweb.git}"
GIMLI='gimli.ms.mff.cuni.cz'
GIMLI_LOGIN="mam-web@$GIMLI"
# Skutečné cesty, jak je vrátí `realpath`
PRODWEB="/aux/akce/mam/www/mamweb-prod"
TESTWEB="/aux/akce/mam/www/mamweb-test"
function die {
echo "$@" >&2
exit 1
}
trap 'echo Něco se nepovedlo :-/' ERR
# Vždycky chceme zajistit, že běžíme z rootu repozitáře
# TODO: chceme? Nechceme naopak umět to spouštět odkudkoliv, aspoň u většiny targetů?
test -e '.git' || die "Make skript spuštěn ve špatné složce, spusť ho z kořenového adresáře repozitáře."
function ensure_venv {
test -f "$VENV_PATH/bin/activate" || $VENV "$VENV_PATH"
. "$VENV_PATH/bin/activate"
# To ale není všechno Horste – ten venv nemusí fungovat, chceme to ověřit a případně spadnout.
local SPRAVNA_CESTA="$(readlink -f "$VENV_PATH/bin/python")"
local SKUTECNA_CESTA="$(readlink -f "$(which python)")"
test "$SPRAVNA_CESTA" == "$SKUTECNA_CESTA" || die "Venv asi nefunguje. Prosím smaž si ho a zkus to znovu."
python -c 'print()' > /dev/null || die "Python ve venvu je rozbitý. Prosím smaž venv a zkus to znovu."
}
function ensure_web_installed {
ensure_venv
python -c 'import django; print(django.__version__)' > /dev/null && return
echo >&2 "POZOR: Web nevypadá nainstalovaně, instaluji."
make/install_web
}
function gimli_only {
# Rovnou zkontrolujeme i uživatele
if test "$HOSTNAME" != gimli -o "$USER" != mam-web
then
echo "Tento příkaz se má spouštět na gimlim, chceš pokračovat? Pokud ne, sestřel tento skript."
read
fi
}
function only_in_directory {
local DIR="$1"
local CURRENT="$(readlink -f .)"
if test "$CURRENT" != "$DIR"
then
echo "Tento příkaz se má spouštět ve složce $DIR, chceš pokračovat? Pokud ne, sestřel tento skript."
read
fi
}
function safe_checkout_branch {
if test "$#" -ne 1
then
echo >&2 "Použití: $0 <branch>"
return 1
fi
local BRANCH="$1"
local SCRIPT="$0"
git fetch --all
# Od teď si musíme dát pozor, abychom nezměnili kód, který právě běží.
# Zkontrolujeme, že se nemění tahle knihovna a skript, který běží.
# `git rev-parse` dává SHA-1 hashe objektů, vizte manuálovou stránku pro pochopení.
# Pozor: tohle porovnává jen verze commitnuté do gitu. Lokální změny udělají něco náhodného…
if test "$(git rev-parse @:make/lib.sh)" != "$(git rev-parse "$BRANCH@{u}":make/lib.sh)"
then
echo >&2 "Změna v make/lib.sh, prosím pullni manuálně"
exit 1
fi
if test "$(git rev-parse @:"$SCRIPT")" != "$(git rev-parse "$BRANCH@{u}":"$SCRIPT")"
then
echo >&2 "Změna v $SCRIPT, prosím pullni manuálně"
exit 1
fi
git checkout "$BRANCH"
git pull
git clean -f
}
function install_everything {
# Skoro celé nasazení webu je stejné pro testweb i pro produkci, tak je to tady dohromady
gimli_only
ensure_venv
make/install
./manage.py migrate
./manage.py collectstatic --noinput
setfacl -R -m default:u:www-data:rX media static
setfacl -R -m u:www-data:rX media static
chown -R :mam . || true
chmod -R g+rX,go-w . || true
}

14
make/push_compiled_vue_to_test

@ -0,0 +1,14 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
scp vue_frontend/webpack-stats.json "$GIMLI_LOGIN:$TESTWEB/vue_frontend/"
rsync -ave ssh seminar/static/seminar/vue "$GIMLI_LOGIN:$TESTWEB/seminar/static/seminar/"
ssh "$GIMLI_LOGIN" "
set -euxo pipefail
cd $TESTWEB
. make/lib.sh
ensure_venv
./manage.py collectstatic --noinput
"

8
make/run

@ -0,0 +1,8 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
ensure_web_installed
./manage.py runserver "$@"

9
make/schema

@ -0,0 +1,9 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
ensure_web_installed
./manage.py graph_models seminar | dot -Tpdf > schema_seminar.pdf
./manage.py graph_models -a -g | dot -Tpdf > schema_all.pdf

20
make/sync_prod_flatpages

@ -0,0 +1,20 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
ensure_web_installed
# TODO: This is very ugly, will fix in a future PR (hopefully)
ssh "$GIMLI_LOGIN" "
set -euxo pipefail
cd $PRODWEB
. make/lib.sh
ensure_venv
./manage.py dumpdata flatpages --indent=2 > flat.json
./fix_json.py flat.json flat_fixed.json
"
rsync -ave ssh "$GIMLI_LOGIN:$PRODWEB/flat_fixed.json" data/flat.json
./manage.py loaddata data/flat.json

11
make/sync_test

@ -0,0 +1,11 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
# Prerekvizity nekontrolujeme, dokud voláme další make skripty, tak by akorát
# vedly k víc dotazům na stejnou věc a bylo by to otravné. Pokud tu někdy bude
# něco jiného, tak pak ať tu prerekvizity zmíněné jsou.
make/sync_test_db_aggressive
make/sync_test_media

18
make/sync_test_db_aggressive

@ -0,0 +1,18 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
gimli_only
# Teoreticky není potřeba, ale stejně jinde make skripty nejsou a pouštět to z
# produkce nezní jako běžný stav, kromě toho to aktuálně vyrábí pomocné soubory
# v aktuální složce (FIXME do budoucna) a to na produkci nechceme
only_in_directory "$TESTWEB"
pg_dump mam_test > "dump-test-$(date +"%Y%m%d_%H%M").sql"
pg_dump -Fc mam_prod > dump-prod.sql
psql mam_test -c 'DROP OWNED BY "mam-web";'
pg_restore -c --if-exists -d mam_test dump-prod.sql
rm dump-prod.sql
psql mam_test -c "UPDATE django_site SET name='MaMweb (test)', domain='mam-test.ks.matfyz.cz' WHERE id=1"

9
make/sync_test_media

@ -0,0 +1,9 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
gimli_only
only_in_directory "$TESTWEB"
rsync -av --delete "$PRODWEB/media/" ./media

9
make/test

@ -0,0 +1,9 @@
#!/bin/bash
set -exuo pipefail
. make/lib.sh
ensure_web_installed
trap - ERR # Testy nejspíš selžou, ale nechceme kolem toho dělat další chybovou hlášku.
./manage.py test -v2
Loading…
Cancel
Save