¶ 1. Čo inštalátor robí
Inštalátor nainštaluje QASIDA API ako službu Windows. Rieši celý postup v jednom sprievodcovi:
- overí, či je zariadenie na inštaláciu pripravené (operačný systém, zdroje, sieť, databáza, licencia),
- stiahne aktuálnu verziu API a Oracle Instant Client z AsolHUB,
- vytvorí inštalačný adresár a konfiguráciu,
- zaregistruje a spustí službu Windows,
- pridá pravidlo firewallu,
- pri prechode z IIS pôvodnú inštaláciu zazálohuje a odstráni.
Inštalátor je jeden súbor QasidaApiInstaller.exe. Nepotrebuje nainštalovaný .NET – nesie si ho v sebe.
Inštaluje sa v režime HTTP. Pripojenie certifikátu (prechod na HTTPS) a ďalšie úpravy nastavení
sa robia až po inštalácii cez administračné rozhranie k API.
Aký certifikát si zabezpečiť, popisuje samostatný dokument QASIDA API – požiadavky na HTTPS certifikát.
¶ 2. Predpoklady
¶ 2.1 Oprávnenia
Inštalátor sa musí spustiť ako správca. Vyžaduje to sám – systém zobrazí výzvu kontroly
používateľských kont (UAC). Bez zvýšených oprávnení nedokáže vytvoriť službu ani pravidlo firewallu.
¶ 2.2 Operačný systém
| Systém | Podporované edície |
|---|---|
| Windows Server 2019 – 2025 | Standard, Datacenter, Essentials |
| Windows 11 | Pro, Enterprise, Education |
| Oracle Linux 8 – 10 | (podporované produktom, ale nie týmto inštalátorom – ten beží len na Windows) |
Vyžaduje sa 64-bitový systém. Windows 10, Windows 11 Home, Windows Server 2016 a staršie
podporované nie sú a inštalátor ich odmietne.
¶ 2.3 Hardvér
| Zdroj | Minimum |
|---|---|
| Procesor | 1 vCPU |
| Operačná pamäť | 2 GB |
| Voľné miesto na disku | 10 GB |
Nesplnené minimum inštaláciu nezastaví – zobrazí sa ako upozornenie spolu s tým, čo môže spôsobiť. Rozhodnutie pokračovať je na zákazníkovi.
¶ 2.4 Sieťové spojenia
| Cieľ | Účel | Blokuje inštaláciu? |
|---|---|---|
https://asolhub.assecosolutions.sk |
stiahnutie API a Instant Client | áno |
https://alis.assecosolutions.sk |
overenie licencie | áno |
https://email-sender.assecosolutions.sk |
notifikácie | áno |
ftp://ftp.datalock.sk (port 21) |
prenos súborov mimo inštalácie | nie |
¶ 2.5 Databáza
- Heslo používateľa DL pre danú databázu.
- Verzia aplikačných skriptov minimálne 26.6. Pri nižšej verzii inštalátor nepokračuje.
- Účet, pod ktorým sa API pripája (štandardne
QasidaAPI). Ak neexistuje, inštalátor ho vytvorí –
stačí zadať heslo.
¶ 3. Priebeh inštalácie
Qasida APII inštalátor je možné stiahnuť na tejto adrese:
https://asseco-spin.sk/Qasida/QasidaApiInstaller.exe
Sprievodca má štyri strany. Medzi nimi sa pohybujete tlačidlami « Späť a Ďalej ».
V pravom hornom rohu sa dá prepnúť jazyk (SK | EN).
¶ 3.1 Prvá strana – základné údaje
| Pole | Význam |
|---|---|
| Nájdené inštalácie | Zoznam QASIDA API, ktoré na zariadení už bežia – v IIS aj ako služby. Výberom položky nasmerujete inštaláciu na ňu (po potvrdení otázky). |
| Meno pre API | Databázový účet, pod ktorým sa API pripája. Štandardne QasidaAPI. |
| Heslo pre API | Heslo tohto účtu. Ak účet ešte neexistuje, inštalátor ho s týmto heslom vytvorí. |
| Heslo pre update DB | Heslo používateľa DL. Používa sa aj na zašifrovanie zálohy pôvodnej konfigurácie. |
| Data Source | Oracle pripojenie (TNS názov alebo popisovač). |
| Disk pre API | Disk, na ktorý sa API nainštaluje. Adresár pod ním určuje inštalátor sám. |
| Adresár pre API | Len na zobrazenie – vypočíta sa z disku a portu. |
| Port | Port, na ktorom bude API počúvať. Štandardne 8888. |
Zaškrtnutím Zobraziť heslá si môžete zadané heslá skontrolovať.
Pod poľami je panel, ktorý hovorí, aká inštancia sa nainštaluje – prvá (bez portu v názve) alebo
ďalšia (s portom v názve).
¶ Prevzatie nastavení z existujúceho appsettings.json
V spodnej časti strany je alternatíva k ručnému vypĺňaniu: tlačidlom Načítať appsettings.json…
prevezmete hodnoty z konfiguračného súboru inej inštalácie.
- Načíta sa len to, čo súbor obsahuje.
- Adresár pre API sa nepreberá – ten určuje výber disku.
- Protokol a certifikát sa zámerne nepreberajú, lebo inštalácia beží v režime HTTP.
- Zálohu vo formáte
.ziptreba najprv rozbaliť (7-Zip); inštalátor číta len.json.
¶ Otázka pri neprázdnom adresári
Ak cieľový adresár už obsahuje dáta, inštalátor sa opýta:
- Áno – ide o preinštaláciu existujúcej API, obsah adresára sa nahradí,
- Nie – ide o ďalšiu API, inštalátor ponúkne nový adresár s portom v názve,
- Zrušiť – návrat k úprave nastavení.
¶ 3.2 Druhá strana – kontroly
Kontroly sa spustia automaticky pri vstupe na stranu. Tlačidlo Ďalej » sa sprístupní, až keď prejdú.
| Kontrola | Čo overuje |
|---|---|
| Operačný systém | Podporovaná verzia a edícia Windows |
| Procesor / Operačná pamäť / Voľné miesto na disku | Minimálne zdroje |
| QASIDA API v IIS | Aké API bežia v IIS |
| Služby AssecoQasidaAPI | Aké API bežia ako služby |
| Cieľ inštalácie | Ktorú inštaláciu beh nahradí, alebo že ide o novú |
| Port XXXX pre API | Či je zvolený port voľný, prípadne kto ho drží |
| ASOL HUB / Licenčný server / Mailový server / FTP | Dostupnosť služieb Asseco |
| Inštalačný kód | Načítanie z databázy |
| Verzia aplikačných skriptov | Minimálne 26.6 |
| Verzia inštalátora | Či nie je k dispozícii novšia |
| Užívateľ pre API v databáze | Či účet existuje a či sa s daným heslom prihlási |
| Kontrola licencie | Platnosť licencie na ALIS |
Význam značiek:
| Značka | Význam |
|---|---|
| ✓ zelená | prešlo |
| ! oranžová | neprešlo, ale neblokuje – nedostatok zdrojov, nedostupné FTP, chýbajúci účet pre API |
| ✗ červená | chyba, inštalácia nemôže pokračovať |
Ak zmeníte port, databázu alebo heslá a vrátite sa na túto stranu, kontroly sa spustia znova –
výsledky sa vždy vzťahujú na aktuálne zadané hodnoty.
¶ 3.3 Tretia strana – nastavenie
| Pole | Význam |
|---|---|
| API používateľ | Používateľ, pod ktorým API pracuje s databázou (zoznam z databázy) |
| Výsledky aktualizácií – email | Adresa, na ktorú chodia správy o aktualizáciách databázy |
Ak kontrola zistila, že databázový účet pre API neexistuje, zobrazí sa navyše sekcia na jeho
vytvorenie. Meno je predvyplnené (QasidaAPI) a stačí zadať heslo.
Požiadavky na heslo: minimálne 8 znakov, veľké aj malé písmeno, číslica a špeciálny znak.
Heslo nesmie obsahovať dvojitú úvodzovku.
Inštalátor účet vytvorí a pridelí mu role, ktoré API potrebuje.
Na tejto strane je aj informácia o protokole – inštalácia prebehne v režime HTTP.
¶ 3.4 Štvrtá strana – inštalácia
Tlačidlom Inštalovať sa spustí samotná inštalácia. Zobrazuje sa priebeh a jednotlivé kroky;
podrobnosti sa zapisujú do log súboru.
Po úspešnom dokončení sa tlačidlo zmení na Dokončiť. Ak niektorý krok zlyhal, inštalátor
vypíše zoznam chýb a pokyny, čo poslať podpore.
Zrušenie inštalácie je možné len do momentu, keď sa začne nahrádzať pôvodná inštalácia.
Od tej chvíle sa inštalátor zrušiť nedá – prerušenie by na zariadení nenechalo funkčné API
a nebolo by sa kam vrátiť. Beh je krátky, treba ho nechať dobehnúť.
¶ 4. Čo inštalátor vytvorí
¶ 4.1 Adresárová štruktúra
Pri prvej inštancii C:\Qasida\QasidaAPI, pri ďalších C:\Qasida\QasidaAPI_<port>
(písmeno disku podľa výberu).
| Podadresár | Obsah |
|---|---|
Api |
Samotná aplikácia a appsettings.json |
InstantClient |
Oracle Instant Client vrátane SqlPlus |
Logs |
Logy služby (QasidaApi<dátum>.txt) |
DataProtectionKeys |
Kľúče, ktorými sú chránené uložené heslá |
ClientInstallFiles, DownloadInstallFiles |
Inštalačné súbory klienta |
¶ 4.2 Služba Windows
| Vlastnosť | Hodnota |
|---|---|
| Názov | AssecoQasidaAPI, pri ďalších inštanciách AssecoQasidaAPI_<port> |
| Zobrazovaný názov | Asseco QASIDA API Service (pri ďalších s portom) |
| Spustenie | Automaticky |
| Účet | Virtuálny účet NT SERVICE\<názov služby> |
| Pri zlyhaní | Trojnásobný automatický reštart po 60 sekundách |
¶ 4.3 Ďalšie zmeny
- Firewall: pravidlo
<názov služby>-<port>pre prichádzajúce TCP spojenia. - Databáza: doplnia sa číselníky API domén; pri prvej inštancii sa nastaví
QASIDA_API_BASE_URLna adresu tohto servera. Ďalšie inštancie toto nastavenie nemenia,
aby klientov nepresmerovali preč od primárnej inštalácie. - Heslá sa neukladajú do
appsettings.json, ale do úložiska poverení Windows.
¶ 5. Viac inštancií na jednom zariadení
Na jednom serveri môže bežať viac QASIDA API, každá na vlastnom porte.
- Prvá inštancia dostane názvy bez portu (
AssecoQasidaAPI,C:\Qasida\QasidaAPI). - Každá ďalšia má port v názve služby aj v názve adresára.
- Každá inštancia má vlastné úložisko hesiel a vlastné kľúče, takže sa navzájom neovplyvňujú.
- Nastavenie
QASIDA_API_BASE_URLmení len prvá inštancia.
Ak port už niekto drží, inštalátor to oznámi na druhej strane a nepustí inštaláciu ďalej.
¶ 6. Prechod z IIS
Ak na zvolenom porte beží QASIDA API pod IIS, inštalátor to zistí sám a ponúkne jej nahradenie
službou Windows. Postup:
- Prevezme nastavenia z jej
appsettings.json(prihlasovacie údaje, Data Source, mandant). - Zazálohuje pôvodnú konfiguráciu do
%ProgramData%\Asseco\QasidaApiInstaller\Backupako ZIP zašifrovaný heslom pre update DB
(AES-256 – archív otvoríte 7-Zipom alebo WinRARom, Prieskumník Windows ho neprečíta). - Zastaví IIS inštaláciu, nainštaluje službu a po úspešnom dokončení IIS stránku odstráni.
- Overí, že port už IIS neobsluhuje.
Z pôvodnej konfigurácie sa prenášajú tieto sekcie, ak ich nová konfigurácia sama neurčuje:
Proxy, ServerAgent, OpenBanking, LdapAuth, QasidaHub, QasidaMobile, Firmsio.
Prihlasovacie údaje v nich sa neprenášajú do súboru, ale do úložiska poverení.
Obmedzenie: ak je QASIDA API v IIS len aplikáciou pod cudzou stránkou, inštalátor port
uvoľniť nedokáže – port patrí bindingu tej stránky a jej zastavenie by zhodilo aj ostatné
aplikácie. V takom prípade inštalátor inštaláciu odmietne. Riešením je odstrániť binding na daný
port ručne v IIS Manageri, alebo zvoliť pre API iný port.
¶ 7. Po inštalácii
- Overenie:
http://<server>:<port>/health - Prechod na HTTPS, pripojenie certifikátu a ďalšie úpravy nastavení sa robia cez
administračné rozhranie k API, nie cez inštalátor. - Ak sa má API sprístupniť pod iným menom (alias, FQDN, IP), treba toto meno doplniť do nastavenia
AllowedHostsvappsettings.json– inak takúto požiadavku API odmietne. Jednotlivé hodnoty sa
oddeľujú bodkočiarkou.
¶ 8. Riešenie problémov
¶ 8.1 Kde sú logy
| Log | Umiestnenie |
|---|---|
| Podrobný log inštalácie | %ProgramData%\Asseco\QasidaApiInstaller\Logs\install-<dátum-čas>.log |
| Log služby | <inštalačný adresár>\Logs\QasidaApi<dátum>.txt |
| Konfigurácia služby | <inštalačný adresár>\Api\appsettings.json |
| Záloha pôvodnej konfigurácie | %ProgramData%\Asseco\QasidaApiInstaller\Backup |
Cestu k logu aj ku konfigurácii inštalátor vypíše na poslednej strane.
¶ 8.2 Najčastejšie hlásenia
| Hlásenie | Príčina a riešenie |
|---|---|
| Port … obsadzuje … | Port drží iný proces alebo IIS stránka. Zastavte ju, alebo zvoľte iný port. |
| QASIDA API na porte … je v IIS len aplikáciou pod stránkou … | Viď obmedzenie v kapitole 6 – odstráňte binding ručne, alebo zvoľte iný port. |
| Stav portu … sa nepodarilo zistiť | Systém nedokázal vrátiť zoznam načúvajúcich portov. Skúste inštaláciu zopakovať. |
| Existenciu databázového užívateľa … sa nepodarilo overiť | Dopyt do databázy zlyhal. Skontrolujte dostupnosť databázy a heslo DL. |
| Užívateľ … existuje, ale pripojenie zlyhalo | Zadané heslo pre API účet nie je správne. |
| Na tomto zariadení chýba .NET runtime… | Doinštalujte uvedený ASP.NET Core Runtime – Hosting Bundle. |
| Služba … sa ani za 2 min nezačala načúvať na porte … | Služba sa nerozbehla. Pozrite log služby v podadresári Logs. |
| Verzia aplikačných skriptov je nižšia ako 26.6 | Najprv aktualizujte databázu. |
| Je dostupná novšia verzia inštalátora | Stiahnite a použite aktuálny inštalátor. |
¶ 8.3 Keď inštalácia neprejde
Inštalátor na záver vypíše zoznam chýb a vyzve na kontaktovanie podpory. Pripravte dva súbory:
appsettings.jsonz inštalačného adresára,- podrobný log inštalácie.
Odošlite ich cez zákaznícky portál:
https://customer-portal.qasida.sk/
Súbory môžu obsahovať heslá – posielajte ich len cez portál, nie e-mailom.
¶ 9. Kontrolný zoznam pred inštaláciou
- Inštalátor sa spúšťa ako správca
- Operačný systém je v podporovanom zozname (kapitola 2.2)
- Na cieľovom disku je aspoň 10 GB voľného miesta
- Je známe heslo používateľa DL
- Je známe heslo pre API účet (alebo je pripravené nové, spĺňajúce požiadavky)
- Verzia aplikačných skriptov je aspoň 26.6
- Zvolený port je voľný
- Zo servera sú dostupné AsolHUB, licenčný a mailový server