Dodávatelia

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

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

Správy platformy vo vašej aplikácii

Správca platformy vie pre každú aplikáciu zadať oznámenie, ktoré sa má zobraziť jej používateľom nad hlavičkou — odstávka, výpadok integrácie, plánovaná údržba. Zadáva ho v CIMPO v detaile aplikácie; zobrazenie si rieši vaša aplikácia. Ak ho neimplementujete, správca vašim používateľom odstávku neoznámi.

Sú dve cesty a používajú sa spolu:

  1. REST — nosná. Pri načítaní si vyžiadajte správy:

    • neprihlásený návštevník: GET https://datahub.presov.sk/api/v1/public/clients/<vas_client_id>/messages (bez tokenu, vracia len oznámenia určené všetkým)
    • prihlásený používateľ: GET https://datahub.presov.sk/api/v1/me/messages (s jeho access tokenom; pridá aj oznámenia len pre prihlásených a tie cielené na jeho rolu)

    Odpoveď obsahuje messages (už odfiltrované podľa toho, kto sa pýta), version a next_change_at.

  2. MQTT — živá aktualizácia. Prihláste sa na odber system/messages/<vas_client_id>. Payload je len { "client_id": …, "version": … }; keď sa version líši od tej, ktorú máte, zavolajte REST znova. Topic je retain, takže aktuálnu hodnotu dostanete hneď po prihlásení na odber. Ping príde aj na začiatku a na konci naplánovaného okna platnosti.

Tri veci, na ktorých sa to najčastejšie pokazí:

  • Obsah neposielame cez MQTT, len odtlačok. Oznámenie cielené na rolu by sa inak vysielalo všetkým odberateľom.
  • Nefiltrujte podľa cielenia u seba. Server pošle len to, čo má daný používateľ vidieť.
  • text je markdown. Pri renderovaní výslovne povoľte len schémy odkazov http, https, mailto, tel a relatívne. Server nebezpečný text odmieta už pri zápise, ale obrana patrí do oboch vrstiev — niektoré markdown knižnice majú blokovanie schém vypnuté.

Úplný popis vrátane tvaru odpovede a odporúčaného toku je v integračnom manuáli Core API (kapitoly „Správy aplikácie" a „MQTT — Správy aplikácie").

Databázové služby

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

Nástroje platformy

Dôležité odkazy

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.

Práca s dátamiMôj Prešov