Webová aplikace pro projekt Úspěšný prvňáček.
Read this in other languages: English, Czech.
-prettier-ff69b4.svg?style=flat-square){kind=icon}
-black-000000.svg?style=flat-square){kind=icon}
Sentry · Fly.io · Slack · DeepCode · Google Analytics
Webová aplikace pro projekt Úspěšný prvňáček (mrkněte na jeho stránky, také pochází z mé tvorby) – založená na technologiích React (TypeScript), Django (Python), REST API, Django REST Framework.
Aplikaci jsem vytvořil v roce 2018 jako bakalářskou práci na FIT ČVUT – vizte repozitář s textem bakalářské práce. Od té doby je v projektu Úspěšný prvňáček denně úspěšně používána a její rozšiřování a práce na ní stále pokračují ❤️. V roce 2020 jsem se také v diplomové práci na FIT ČVUT věnoval všem dosavadním rozšířením aplikace o nové funkce, technologie a nástroje – vizte repozitář s textem diplomové práce. A vývoj probíhá i nadále.
V následujícím seznamu jsou nejdůležitější funkce, která aplikace poskytuje (výčet není konečný):
- evidence klientů a skupin klientů docházejících na lekce kurzů,
- evidence lekcí klientů a skupin včetně předplacených – stav účasti, platba, datum, čas, zrušení, poznámky,
- evidence zájemců o kurzy,
- zobrazení lekcí ve 3 formách: v kartě klienta/skupiny, v diáři a na hlavní stránce v přehledu pro dnešní den,
- kontrola časových konfliktů lekcí,
- automatické rušení lekcí když nikdo nemá přijít,
- automatické vytváření předplacených náhrad lekcí při omluvě předem/zrušení ze strany lektorky,
- upozornění, že má klient příště platit,
- výpočet pořadového čísla lekce s ohledem na účast klientů,
- vyhledávání klientů (fuzzy vyhledávání)
- konfigurace kurzů a stavů účasti včetně např. intuitivního nastavení zvolené barvy pro kurz,
- propojení s API Fio banky – na hlavní stránce se přehledně zobrazují nedávné transakce z účtu,
- automatický odhad kurzu, data a času pro nově přidávané lekce,
- respektování a kontrola všech omezení daných danou doménou (např. duplicity),
- vedení aktivních a neaktivních klientů a skupin.
Aplikace je rozdělena na frontend a backend, ty spolu komunikují přes REST API zabezpečené JWT autentizací. Jako databáze se používá PostgreSQL 14.
ℹ️ Poznámka: součástí repozitáře je také diagram nasazení a logický datový model – viz
docs/README.md.
Obsahuje veškerou logiku a pro klienta vystavuje REST API, postaven na těchto technologiích:
V Djangu jsou pro mnohonásobné zrychlení pokročile optimalizované komplexní SQL dotazy (viz články [1], [2]). Aplikace umožňuje pokročilé debugování na lokálním i vzdáleném prostředí díky Django Debug Toolbar a jeho doplňku Django Debug Toolbar Request History.
Pro statickou typovou kontrolu se napříč celým kódem používají typové anotace s použitím modulu typing, pro kontrolu typů se používá mypy a Pycharm. Pro eliminaci mrtvého kódu se také používá vulture.
Responzivní JS (TypeScript) webová aplikace typu SPA (Single-Page-App) postavená na těchto technologiích:
- React 17,
- TypeScript 5,
- Bootstrap 4 (s Reactstrapem),
- React Router 5,
- FontAwesome 5 PRO (publikované do privátních Github Package Registry)
- a další...
Vývoj frontendu je postaven především na:
- Webpack 5 s vlastní konfigurací (lokální i produkční) + Webpack DevServer,
- Babel 7,
- Typescript 5 – pro statickou typovou kontrolu,
- ESlint 8 a stylelint – lintery pro statickou analýzu kódu,
- husky a lint-staged – pre-commit kontroly (eslint, stylelint)
- a React Hot Loader – pro HMR.
Aplikace je odolná proti pádům JS díky
React Error Boundaries. Pro zrychlení
načítání celé aplikace se používá lazy loading
React.lazy + React Suspense.
Webpack DevServer je při vývoji propojený s
Django dev serverem a umožňuje tak jednoduchý vývoj bez kompromisů
včetně HMR. Globální stav aplikace je
spravován přes React Context. Část codebase využívá
také výhod React Hooks.
Aplikace je nasazena do 2 prostředí na PaaS Fly.io, které se liší příslušnou nasazenou verzí aplikace, konkrétní instancí databáze a umožňují různé úrovně debugování. Mimo to lze samozřejmě aplikaci spustit i v prostředí lokálním u vývojáře. Typ prostředí je také zvýrazněn barevným štítkem v horním menu (kromě produkce).
Seznam prostředí:
- lokální – pro lokální vývoj,
- testing – stejná konfigurace jako na produkci, deploy při každém commitu; umožňuje zapnout debugování,
- produkce – produkční verze používaná zákazníkem, deploy při release,
- Nasazené aplikace jsou HTTPS-only (+ pokročilé zabezpečení, viz [1], [2]).
- Pro automatické formátování kódů se používá Black (Python) a Prettier (TS, TSX, JS, CSS, HTML, JSON, YAML, TOML, MD), oba nástroje jsou napojené na IDE a provádějí automatické úpravy.
- Aplikace jsou napojené na další služby:
- CI a CD má na starost GitHub Actions – automatizovaný build, testování i nasazení na různá prostředí, automaticky prováděné pokročilejší skripty např. pro automatické zapsání verze do aplikace, práci s tokeny, nahrání sestaveného frontendu do assetů k releasu na GitHubu, napojení na služby pro výpočet pokrytí kódu a další.
- Automatickou průběžnou analýzu a kontrolu kódu včetně hodnocení kvality kódu, hledání potenciálních chyb a zranitelností má na starost GitHub CodeQL, SonarCloud a DeepScan.
- Odchytávání chyb na backendu i frontendu včetně následné evidence, notifikací a propojení s repozitářem zařizuje Sentry (tříděné podle typu prostředí, aktivní na všech nasazených aplikacích). Při chybě na frontendu je možné poslat zpětnou vazbu vázanou ke konkrétní chybě díky propojení Sentry a React Error Boundaries.
- Sledování toku uživatelů umožňuje napojení na Google Analytics (přes modul react-ga).
- Slack
- audit-ci se používá pro automatizovanou kontrolu zranitelných závislostí projektu na CI.
- Aplikace respektuje standardy PEP 8, 12-Factor App, ROCA.
- Kompletní vývoj aplikace probíhá v IDE Pycharm (Professional Edition) (řeší automatickou optimalizaci importů, automatické formátování kódů apod.).
- Rozsáhlé testy API i UI (E2E) jsou důležitou částí aplikace, automaticky se spouští na CI a
lze je spustit i na lokálním prostředí. Část frontendu je navíc pokryta unit testy.
- E2E testování je postaveno na BDD frameworku behave – testové scénáře jsou psány přirozeným jazykem (Gherkin), podle nich se spouští konkrétní testy.
- Unit testy jsou postaveny na frameworku Jest a nástrojích React Testing Library (jednoduché utility pro testování Reactu), jest-dom (custom DOM element matchers pro Jest) a MSW (mockování API).
- Pro testování UI (E2E) se používá Selenium.
- Podrobné informace o testech jsou v
tests/README.md.
├── .github ...... GitHub Actions konfigurace
├── .idea ........ nastavení pro IDE (Pycharm od Jetbrains)
├── admin ........ Django aplikace pro webovou aplikaci
├── api .......... Django aplikace pro REST API
├── db ........... Dockerfily pro PostgreSQL
├── docs ......... další dokumentace a soubory k aplikaci včetně diagramů
├── frontend ..... klientská část webové aplikace
├── scripts ...... skripty pro CI/CD/PaaS/instalaci
├── staticfiles .. složka pro statické soubory (prázdná, přesun až na CI)
├── tests ........ testy API i UI (e2e)
└── up ........... celý Django projektAplikaci lze spustit na lokálním prostředí ve dvou režimech. Výchozí režim je klasický vývojový – ten obsahuje pokročilé debugovací nástroje, spouští se Django vývojový server a také webpack-dev-server pro frontend. Vzhledem k práci s privátními GitHub Package registry (viz níže) nelze samozřejmě bez příslušných tokenů sestavovat frontend, proto zde budu popisovat postup spuštění ve druhém režimu – manuální produkční verze aplikace, tedy ta, která je nejblíže verzi u zákazníka.
Minimální požadavky jsou:
-
Nejdříve naklonujte repozitář, otevřete jeho složku a nahrajte si poslední produkční verzi repozitáře:
git clone "https://github.com/rodlukas/UP-admin.git" && cd UP-admin git checkout $(git describe --tags `git rev-list --tags --max-count=1`)
-
Vytvořte vaší lokální konfigurační prostředí ze vzorové konfigurace
.env.template:cp .env.template .env
-
Použijte Docker Compose V2 pro spuštění všech kontejnerů 🚀:
docker compose up
-
A když kontejnery běží, ve vedlejším CLI si založte uživatelský účet:
docker compose run web python manage.py createsuperuser
-
Aplikace je nyní dostupná na adrese http://localhost:8000/ ✅.
⚠️ Upozornění: Docker Compose soubor používá Django dev server (ne Gunicorn), je pouze pro lokální testovací účely, nasazená prostředí používají Gunicorn server.
ℹ️ Poznámka: otevření aplikace na jiném zařízení v síti – aplikace je připravena pro použití i z dalších zařízeních v síti (např. z mobilního telefonu), obvykle je potřeba provést tyto 2 kroky:
- povolit Python a Node.js ve firewallu (např. na chvíli aktivovat interaktivní režim ESETu),
- na mobilním zařízení zadat hostname nebo privátní IP adresu počítače, na kterém běží server.
Aplikaci také můžete spustit pouze s Dockerem bez Docker Compose V2, ale je to o poznání náročnější!
Ukaž mi alternativní pokročilejší instalaci
ℹ️ Poznámka: Node.js ani npm nejsou požadovány, protože ve vlastním prostředí nelze frontend sestavit (je potřeba přístup přes token k privátnímu GitHub Package registru pro FontAwesome PRO). Místo toho zde použijeme automaticky sestavenou poslední produkční verzi frontendu z integračního serveru (která se automaticky nahrává do assetů ke každému release).
-
Nejdříve naklonujte repozitář, otevřete jeho složku a nahrajte si poslední produkční verzi repozitáře:
git clone "https://github.com/rodlukas/UP-admin.git" && cd UP-admin git checkout $(git describe --tags `git rev-list --tags --max-count=1`)
-
Stáhněte již sestavené zdrojové kódy frontendu z poslední produkční verze a rozbalte je přímo do repozitáře (a
frontend.zipsmažeme):wget https://github.com/rodlukas/UP-admin/releases/latest/download/frontend.zip unzip frontend.zip && rm frontend.zip -
Vytvořte vaší lokální konfiguraci prostředí ze vzorové konfigurace
.env.template:cp .env.template .env
-
Nainstalujeme všechny závislosti pro backend a aktivujeme virtuální prostředí Pythonu:
pipenv install --dev pipenv shell
-
Vytvoříme docker image a spustíme kontejner s PostgreSQL:
source scripts/shell/postgresql_docker.sh -
Připravíme celou Django aplikaci na spuštění (skript nastaví výchozí soubor s nastavením Djanga, připraví statické soubory frontendu a vytvoří databázové schéma):
source scripts/shell/release_tasks.sh -
A vytvoříme uživatelský účet pro přístup do aplikace (zadáme libovolné údaje, kterými se poté budeme přihlašovat):
python manage.py createsuperuser
-
💡 (NEPOVINNÉ) Na závěr můžeme ještě naplnit naší databázi předpřipravenými vzorovými daty, která ukážou fungování aplikace a usnadní první použití (obsahují několik klientů, skupin, lekcí, zájemců, kurzů a stavů účasti):
docker exec postgresql_cz psql --dbname postgres -h localhost -U postgres -f sample_data.pgsql
Spustíme vývojový server 🚀:
python manage.py runserver 0.0.0.0:8000✅ Aplikace je nyní dostupná na adrese http://localhost:8000/.
Můžeme také snadno spustit různé testy aplikace, například otestovat, jestli správně funguje API pro klienty:
python manage.py behave --stage=api --tags=clientsAplikace obsahuje rozsáhlé API a UI (e2e) testy – vizte podrobné informace o testech a možnostech spouštění.
ℹ️ Poznámka: údaje v aplikaci jsou smyšlené.
Projekt původně pro CI & CD používal Travis, ale v listopadu 2022 došlo k migraci na GitHub Actions.
Automatickou průběžnou analýzu a kontrolu kódu zajišťoval mj. LGTM až do listopadu 2022, kdy byl nahrazen svým nástupcem GitHub CodeQL.
Projekt byl původně nasazen na Heroku PaaS. Zde byly 4 nezávislé běžící
instance - testing (automatické nasazování z master větve), staging (stejné jako produkce),
produkce a demo (s veřejnými přístupovými údaji a ukázkovými daty, která byla automaticky a
periodicky obnovována přes Heroku Scheduler). Kvůli
oznámeným změnám cen Heroku bylo učiněno rozhodnutí posunout
se o dům dál. Nejprve v listopadu 2022 bylo na Fly.io zmigrováno testing
prostředí. Krátce nato v prosinci 2022 byla takto přesunuta i celá produkce. Migrace zahrnovala i
PostgreSQL databázi se všemi daty. Instance staging a demo byly ukončeny bez náhrady.
Vzhledem k tomu, že aplikace byla původně nasazena na Heroku PaaS s použitím jejich Builpacks, nepoužívala žádnou formu kontejnerizace. Tento přístup měl své výhody i nevýhody. Ale vzhledem k příchodu jiných PaaS jako Fly.io byla vyžadována migrace na kontejnery. To vedlo k plně kontejnerizované aplikaci založené na Dockeru (a publikovaném obrazu v Github Container Registry). S pomocí nově vzniklého Docker Compose V2 bylo také možné výrazné zjednodušení tohoto README pro instalaci a spuštění, která nyní zabere jen pár řádků.
Licencováno pod MIT licencí.
Copyright (c) 2018–2024 Lukáš Rod