Dodávatelia

Táto dokumentácia slúži ako sprievodca pre externých dodávateľov, ktorí chcú vyvíjať softvérové riešenia pre mesto Prešov v rámci platformy DataHub.

Tento dokument je udržiavaný na GitLabe platformy DataHub: https://gitlab.presov.sk/datahub/docs/-/blob/main/pages/dodavatelia.mdx (opens in a new tab)

Úvod do platformy DataHub

Platforma DataHub mesta Prešov je centrálny dátový sklad a komunikačná platforma optimalizovaná pre IoT riešenia. Využíva protokol MQTT ako hlavný komunikačný prvok a všetky dáta sú bezpečne uchovávane na serveroch mesta.

Architektúra platformy

• Centrálny komunikačný protokol: MQTT
• Bezpečné úložisko dát: všetky dáta na serveroch mesta
• Flexibilita: aplikácie môžu byť prevádzkované aj mimo platformy
• Integrácia: zachovanie dátovej integrácie

Začiatok spolupráce

Prístup k GitLab-u

1. Kontakt s administrátorom: Kontaktujte správcu platformy DataHub na získanie prístupu
2. Registrácia v GitLab-e: Vytvorenie účtu na https://gitlab.presov.sk (opens in a new tab)
3. Priradenie do skupiny: Budete priradení do podskupiny Projekty pod hlavnou skupinou DataHub
4. Oprávnenia: Získate rolu Developer pre váš projekt

Štruktúra repozitárov

• Hlavná skupina: DataHub
• Podskupina: Projekty
• Vaša podskupina: individuálna podskupina pre vášho dodávateľa
• Štruktúra: DataHub/Projekty/[názov-dodávateľa]/[názov-projektu]

Vytvorenie nového projektu

Komunikácia s administrátorom

1. Kontaktujte administrátora: Projekt za vás vytvorí administrátor DataHub platformy
2. Poskytnite požadované údaje:
   • Názov projektu (slug-friendly formát)
   • Stručný popis projektu
   • Technológie, ktoré budete používať
   • Požiadavky na porty (ak sú potrebné)
3. Počkajte na vytvorenie: Administrátor vytvorí projekt importom šablóny https://gitlab.presov.sk/datahub/template-project (opens in a new tab)
4. Získajte prístup: Budete priradení do projektu s rolou Developer

Pracovný postup (Workflow)

Správa vetiev

Projekt využíva tri hlavné typy vetiev:

dev (vývojová vetva)

• Hlavná vetva pre vývoj
• Vývojári môžu publikovať zmeny priamo
• Spúšťa sa iba validácia (validate)
• Vývojári môžu do tejto vetvy pridať vlastné CI/CD kroky podľa potreby - nesmú však zasahovať do produkčného alebo pre-produkčného procesu

pre-release-* (predprodukčná vetva)

• Určená na testovanie pred produkciou
• Merge requesty schvaľujú iba Maintaineri
• Spúšťa sa validácia a build (validate, build)

main (produkčná vetva)

• Produkčné verzie
• Merge requesty iba z pre-release-* vetiev
• Merge requesty schvaľujú iba Maintaineri
• Spúšťa sa kompletný proces (validate, build, deploy)

Odporúčaný postup nasadzovania

Vlastné vetvy → dev → pre-release-* → main

Konfigurácia aplikácie

Containerfile

• Definuje inštrukcie pre vytvorenie produkčného obrazu
• Základ pre lokálny vývoj aj produkčné nasadenie
• Musí byť prispôsobený vašej technológii

Quadlet konfigurácia

Súbor .datahub/project-slug.container:

• Premenujte na slug vašeho projektu (napr. my-project.container)
• Konfigurácia pre Podman systemd jednotky

Environmentálne premenné

1. Vývoj: Použite súbor .env (nie je v Git-e)
2. Produkcia: Koordinujte s Maintainerom na vytvorenie .env súboru na serveri
3. Vzor: Aktualizujte .env-sample s potrebnými premennými

Dokumentácia

Verejná dokumentácia

• Umiestnená v priečinku .docs/
• Formát: Markdown (.mdx súbory)
• Automaticky publikovaná na https://docs.presov.sk (opens in a new tab)
• Framework: Nextra

Projektová dokumentácia

• Aktualizujte README.md s informáciami o projekte
• Zahrňte: popis, požiadavky, spôsob spustenia, konfiguráciu

Testovacie scenáre

• Vytvorte súbor .datahub/TESTING.md
• Popíšte kroky na manuálne overenie funkčnosti
• Slúži pre Maintainerov na validáciu projektu

Komunikácia s platformou

MQTT protokol

• Centrálny komunikačný protokol platformy
• EMQX Broker na broker.datahub.presov.sk
• Webové rozhranie pre monitoring

Databázové služby

• PostgreSQL server dostupný na platforme
• Prístupové práva riadi administrátor

Nástroje platformy

• GitLab: https://gitlab.presov.sk (opens in a new tab)
• Dokumentácia: https://docs.presov.sk (opens in a new tab)

Dôležité odkazy

• Informačný balík pre prácu s MQTT brokerom dátového skladu mesta Prešov - https://gitlab.presov.sk/datovy-sklad/mqtt-dev (opens in a new tab)
• Informačný balík pre nasadzovanie softvéru do dátového skladu mesta Prešov - https://gitlab.presov.sk/datovy-sklad/ops (opens in a new tab)

Táto príručka poskytuje základný prehľad postupov pre externých dodávateľov. Pre podrobnejšie informácie konzultujte štartovací manuál alebo kontaktujte správcov platformy DataHub.