AppInstaller — opis techniczny

📅 2026-05-15 1.15.6.4 👤 mmy, dbo ⏳ 45 min.

Spis treści

1. Wprowadzenie
2. Wymagania systemowe
3. Tryby instalacji
4. Parametry wiersza poleceń (CLI)
5. Konfiguracja JSON — pełna specyfikacja
6. Kroki instalacji — mechanizm działania
7. Przykłady uruchomienia
8. Przykładowy plik konfiguracji JSON
9. Kody zakończenia (Exit Codes)
10. Ograniczenia i znane braki
11. Dobre praktyki
12. FAQ / Rozwiązywanie problemów

1. Wprowadzenie

nAxiom AppInstaller to aplikacja instalacyjna typu wizard (kreator) dla platformy nAxiom, działająca w środowisku Windows. Odpowiada za:

konfigurację witryny IIS oraz pul aplikacji,
rozpakowanie pakietów aplikacji (ZIP) na serwer WWW,
konfigurację połączeń z bazami danych SQL Server,
ustawienie schematów bazy danych,
konfigurację brokera komunikatów RabbitMQ,
konfigurację diagnostyki (logi, OpenTelemetry),
ustawienie restrykcji IP dla poszczególnych aplikacji,
konfigurację lokalizacji zasobów (załączniki, e-mail, OCR).

Instalator może działać w trzech trybach:

GUI — graficzny kreator,
nogui — pełna instalacja bez interfejsu graficznego (silent/headless),
noguiupdate — aktualizacja plików bez zmiany konfiguracji (silent/headless).

2. Wymagania systemowe

Instalator automatycznie weryfikuje poniższe wymagania w pierwszym kroku. Wymagania oznaczone jako obowiązkowe blokują instalację w przypadku niespełnienia.

Wymaganie	Obowiązkowe	Opis
System operacyjny Windows	✅	Wymagany system Windows
.NET Framework 4.8	❌	Wykorzystywany przez Crystal Reports
.NET 8	✅	Środowisko uruchomieniowe dla aplikacji DotNetCore
ANCM (ASP.NET Core Hosting Bundle)	✅	Moduł hostujący dla IIS
IIS 8+	✅	Internet Information Services
IIS — Przeglądanie katalogów	✅	Funkcja HTTP: Directory Browsing
IIS — IP Security	✅	Moduł zabezpieczeń: IP Address and Domain Restrictions
IIS — Zawartość statyczna	✅	Funkcja HTTP: Static Content
IIS — Inicjowanie aplikacji	✅	Application Initialization
URL Rewrite (rozszerzenie IIS)	✅	Moduł URL Rewrite
Microsoft SQL Server 2016+	❌	Baza danych (może być zdalny serwer)
SAP Crystal Reports Runtime 13	❌	Tylko jeśli instalowany jest moduł Crystal
Uprawnienia administratora	✅	Wymagane do zarządzania IIS
Erlang/OTP	❌	Wymagane dla RabbitMQ
RabbitMQ	❌	Broker komunikatów

Uwaga: Instalator musi być uruchamiany z uprawnieniami administratora (Run as Administrator).

3. Tryby instalacji

3.1 Tryb GUI (graficzny)

Domyślny tryb uruchamiany bez parametrów lub z konfiguracją JSON bez flagi nogui/noguiupdate. Kreator prowadzi użytkownika przez wszystkie kroki instalacji za pomocą formularzy.

AppInstaller.exe

Opcjonalnie z wstępnie załadowaną konfiguracją z pliku JSON (formularz GUI zostanie wypełniony wartościami z pliku):

AppInstaller.exe it=:file iv=:".\install.json"

Tryb graficzny został obszernie opisany w Przewodniku instalacji .

3.2 Tryb headless — pełna instalacja (`nogui`)

Pełna instalacja bez interfejsu graficznego. Wszystkie ustawienia odczytywane z konfiguracji JSON. Komunikaty wyświetlane na konsoli. Wymaganie: kompletna konfiguracja JSON zawierająca wszystkie sekcje.

AppInstaller.exe it=:file iv=:".\install.json" nogui

3.3 Tryb headless — aktualizacja plików (`noguiupdate`)

Tryb aktualizacji istniejącej witryny. Aktualizuje wyłącznie pliki aplikacji (rozpakowuje nowe paczki ZIP) bez modyfikacji konfiguracji (bazy danych, IIS, schematy, itp.). Wymaga, aby na IIS istniała dokładnie jedna witryna nAxiom.

AppInstaller.exe it=:file iv=:".\install.json" noguiupdate

W tym trybie z pliku JSON wymagana jest jedynie sekcja Packages.

3.4 Porównanie trybów

Funkcja	GUI	GUI + JSON	nogui	noguiupdate
Interfejs graficzny	✅	✅	❌	❌
Konfiguracja IIS	✅	✅	✅	❌ (pomija)
Konfiguracja baz danych	✅	✅	✅	❌ (pomija)
Rozpakowywanie paczek	✅	✅	✅	✅
Konfiguracja schematów	✅	✅	✅	❌ (pomija)
Restrykcje IP	✅	✅	✅	❌ (pomija)
RabbitMQ	✅	✅	✅	❌ (pomija)
Diagnostyka	✅	✅	⚠️ częściowe	❌ (pomija)
Wyjście na konsolę	❌	❌	✅	✅
Wymaga pełnego JSON	❌	❌	✅	❌ (tylko Packages)

4. Parametry wiersza poleceń (CLI)

4.1 Składnia

AppInstaller.exe [it=:<typ_wejścia>] [iv=:"<wartość>"] [nogui|noguiupdate]

4.2 Lista parametrów

Parametr	Wymagany	Opis
`it=:<typ>`	Tak*	Typ wejścia konfiguracji. Dozwolone wartości: `file`, `json`
`iv=:"<wartość>"`	Tak*	Wartość wejścia — ścieżka do pliku JSON (dla `it=:file`) lub zminimalizowany JSON (dla `it=:json`)
`nogui`	Nie	Uruchamia instalator w trybie silent — pełna instalacja bez GUI
`noguiupdate`	Nie	Uruchamia instalator w trybie silent — aktualizacja plików bez zmiany konfiguracji

* Parametry it i iv są wymagane, gdy podano nogui lub noguiupdate. W trybie GUI są opcjonalne (służą do wstępnego wypełnienia formularzy).

4.3 Format separatora

Parametry klucz-wartość używają separatora =: (znak równości + dwukropek):

it=:file
iv=:"C:\config\install.json"

4.4 Obsługiwane ścieżki do pliku JSON

Typ ścieżki	Przykład	Opis
Bezwzględna	`C:\nAxiom\install.json`	Pełna ścieżka na dysku
Względna (`.\`)	`.\install.json`	Względem katalogu instalatora
Nadrzędna (`..\`)	`..\config\` `install.json`	Katalog nadrzędny (z rekurencyjną obsługą)

5. Konfiguracja JSON — pełna specyfikacja

Plik JSON zawiera kompletną konfigurację instalacji. Poniżej opisano każdą sekcję z typami danych i dozwolonymi wartościami.

5.1 Struktura główna

{
  "IISApplication": { ... },
  "Environment": { ... },
  "Packages": [ ... ],
  "Databases": [ ... ],
  "GlobalSettings": { ... },
  "ResourceLocations": [ ... ],
  "Schemas": { ... },
  "Restrictions": { ... },
  "MessageBrokerConfiguration": { ... },
  "DiagnosticsConfiguration": { ... }
}

5.2 `IISApplication` — Konfiguracja witryny IIS

{
  "IISApplication": {
    "MainBinding": {
      "Host": "mysite.com",
      "Port": 443,
      "IpAddress": "*",
      "Protocol": "https",
      "CertificateThumbprint": "03C7D02F959CDEBB4C8AB47D079FE17163C53F38",
      "CertificateStore": "My"
    },
    "OptionalLocalBinding": {
      "Host": "localhost",
      "Port": 8082,
      "IpAddress": "*",
      "Protocol": "http"
    },
    "InstallationType": "Global",
    "WebsiteName": "naxiom.mysite",
    "WebsitePath": "C:\\inetpub\\naxiom",
    "CompanyName": "MyCompany",
    "PoolIdentityType": "ApplicationPoolIdentity",
    "IdentityUser": "",
    "IdentityPassword": ""
  }
}

Pole	Typ	Wartości	Opis
`MainBinding.` `Host`	string	—	Nazwa hosta (domena)
`MainBinding.` `Port`	int	1–65535	Port witryny
`MainBinding.` `IpAddress`	string	`*` lub adres IP	Adres IP nasłuchiwania
`MainBinding.` `Protocol`	string	`http`, `https`	Protokół
`MainBinding.` `Certificate` `Thumbprint`	string	hex	Odcisk palca certyfikatu SSL (wymagane dla HTTPS)
`MainBinding.` `Certificate` `Store`	string	`My`, `Root`, itp.	Magazyn certyfikatów Windows
`Optional` `Local` `Binding`	object/null	—	Opcjonalne dodatkowe powiązanie (np. localhost na HTTP)
`Installation` `Type`	string	`Local`, `Global`	`Local` — dostęp lokalny; `Global` — dostęp z Internetu
`Website` `Name`	string	—	Nazwa witryny w IIS
`Website` `Path`	string	—	Ścieżka na dysku do plików witryny
`Company` `Name`	string	—	Nazwa klucza licencyjnego
`Pool` `Identity` `Type`	string	`ApplicationPoolIdentity`, `SpecificUser`	Tożsamość puli aplikacji
`Identity` `User`	string	—	Nazwa użytkownika (wymagane dla `SpecificUser`)
`Identity` `Password`	string	—	Hasło (wymagane dla `SpecificUser`)

Instalacja Global: wartość Host nie może być localhost ani 127.0.0.1.

5.3 `Environment` — Typ środowiska

{
  "Environment": {
    "EnvironmentType": "Production"
  }
}

Wartość	Opis
`Development`	Środowisko deweloperskie
`Test`	Środowisko testowe
`Production`	Środowisko produkcyjne

5.4 `Packages` — Pakiety instalacyjne

Lista pakietów ZIP do zainstalowania. Każdy wpis odpowiada jednej aplikacji platformy nAxiom.

{
  "Packages": [
    {
      "Name": "Front",
      "ZipPath": "C:\\nAxiom\\1.15.6\\front.zip"
    },
    {
      "Name": "Api",
      "ZipPath": "C:\\nAxiom\\1.15.6\\api.zip"
    }
  ]
}

Dostępne nazwy pakietów (`Name`):

Nazwa	Typ aplikacji	Opis	Wymagana DB
`Front`	Angular	Główna strona internetowa	❌
`Admin`	Angular	Panel administratora	❌
`Api`	.NET Core	Interfejs programistyczny (API)	✅
`Auth`	.NET Core	Panel autoryzacyjny	✅
`TenantsApi`	.NET Core	API zarządzania tenantami	✅
`TenantsAdmin`	Angular	Aplikacja zarządzania tenantami	❌
`Crystal`	.NET Framework	Generator raportów Crystal Reports	✅
`Workflow`	Angular	Graficzne przejścia dokumentów	❌
`TaskService`	.NET Core	Serwis zadań czasowych	✅
`PublicApi`	.NET Core	Publiczne API	✅
`OcrApi`	.NET Core	API rozpoznawania tekstu	❌
`Ocr`	Angular	Aplikacja OCR	❌
`Syncfusion`	.NET Core	Konwerter plików PDF	❌
`ReportsApi`	.NET Core	Moduł raportów	✅
`MobileApi`	.NET Core	API dla aplikacji mobilnej	✅
`DocApi`	.NET Core	Moduł dokumentacji	❌
`DocPdf`	Content	Dokumentacja PDF	❌
`Word`	Angular	Wtyczka MS Word	❌
`Outlook`	Angular	Wtyczka MS Outlook	❌
`MobileTools`	Content	Pliki generatora aplikacji mobilnych	❌
`Bpmn`	Angular	Edytor BPMN/DMN	❌

Pomijanie pakietów: Aby pominąć instalację określonego pakietu, wystarczy usunąć go z sekcji Packages (oraz z Databases, jeśli dotyczy).

5.5 `Databases` — Połączenia z bazami danych

Lista konfiguracji baz danych dla aplikacji, które ich wymagają.

{
  "Databases": [
    {
      "Name": "Api",
      "DatabaseConnection": {
        "Server": "localhost",
        "UsePort": false,
        "Port": 1433,
        "Timeout": 15,
        "Instance": "SQLEXPRESS",
        "IntegratedSecurity": false,
        "Username": "tenant1user",
        "Password": "!Q2w3e4r",
        "Database": "nAxiom"
      }
    },
    {
      "Name": "TenantsApi",
      "DatabaseConnection": {
        "Server": "localhost",
        "UsePort": false,
        "Port": 1433,
        "Timeout": 15,
        "Instance": "SQLEXPRESS",
        "IntegratedSecurity": false,
        "Username": "tenantadmin",
        "Password": "!Q2w3e4r",
        "Database": "nAxiom_tenantsAdmin"
      }
    }
  ]
}

Pole	Typ	Domyślnie	Opis
`Name`	string	`Api`, `TenantsApi`	Nazwa serwisu używającego bazy danych: `Api` - baza używana przez wszystkie serwisy, `TenantsApi` - baza danych tenantów
`Server`	string	`localhost`	Adres serwera SQL
`UsePort`	bool	`false`	Czy użyć niestandardowego portu
`Port`	int	`1433`	Port SQL Server
`Timeout`	int	`120`	Timeout połączenia (sekundy)
`Instance`	string	`SQLEXPRESS`	Nazwa instancji SQL (puste = domyślna)
`Integrated` `Security`	bool	`true`	Czy używać uwierzytelniania Windows
`Username`	string	`""`	Login SQL (gdy `IntegratedSecurity = false`)
`Password`	string	`""`	Hasło SQL (gdy `IntegratedSecurity = false`)
`Database`	string	`nAxiom`	Nazwa bazy danych

5.6 `GlobalSettings` — Połączenie administratora SA

Używane do operacji wymagających uprawnień SA (tworzenie baz danych, użytkowników).

{
  "GlobalSettings": {
    "DatabaseConnectionSA": {
      "Server": "localhost",
      "UsePort": false,
      "Port": 1433,
      "Timeout": 15,
      "Instance": "SQLEXPRESS",
      "IntegratedSecurity": false,
      "Username": "sa",
      "Password": "saPassword!@89",
      "Database": ""
    }
  }
}

Struktura DatabaseConnectionSA jest identyczna jak DatabaseConnection opisane w sekcji 5.5.

5.7 `ResourceLocations` — Lokalizacja zasobów

Definiuje, gdzie przechowywane są poszczególne typy zasobów aplikacji.

{
  "ResourceLocations": [
    {
      "ResourceType": "Attachments",
      "Location": "DataBaseTable",
      "DatabaseConnection": {
        "Server": "localhost",
        "UsePort": false,
        "Port": 1433,
        "Instance": "SQLEXPRESS",
        "Username": "sa",
        "Password": "!Q2w3e4r",
        "Database": "nAxiom.TESTOWY"
      },
      "TableName": "dbo.my_attachments",
      "FolderPath": ""
    },
    {
      "ResourceType": "EmailMessages",
      "Location": "InstallationFolder",
      "DatabaseConnection": null,
      "TableName": "",
      "FolderPath": ""
    },
    {
      "ResourceType": "Ocr",
      "Location": "NoChange",
      "DatabaseConnection": null,
      "TableName": "",
      "FolderPath": ""
    },
    {
      "ResourceType": "AdditionalLibrary",
      "Location": "InstallationFolder",
      "DatabaseConnection": null,
      "TableName": "",
      "FolderPath": ""
    }
  ]
}

Typy zasobów (`ResourceType`):

Wartość	Opis
`Attachments`	Załączniki dokumentów
`EmailMessages`	Wiadomości e-mail
`Ocr`	Rozpoznane pliki OCR
`AdditionalLibrary`	Dodatkowe biblioteki

Lokalizacja (`Location`):

Wartość	Zastosowanie	Opis
`InstallationFolder`	Pierwsza instalacja / aktualizacja	Folder instalacyjny witryny
`SelectedFolder`	Pierwsza instalacja / aktualizacja	Wybrany folder na dysku (wymaga `FolderPath`)
`DataBaseTable`	Pierwsza instalacja / aktualizacja	Tabela w bazie danych (wymaga `DatabaseConnection` i `TableName`)
`NoChange`	Tylko aktualizacja	Zachowuje obecne ustawienia (nie zmienia konfiguracji)

5.8 `Schemas` — Schematy bazy danych

{
  "Schemas": {
    "AppCoreSchema": "core",
    "AppAuthSchema": "auth",
    "AppUserSchema": "*"
  }
}

Pole	Domyślnie	Opis
`AppCoreSchema`	`core`	Schemat tabel systemowych
`AppAuthSchema`	`auth`	Schemat tabel autoryzacyjnych
`AppUserSchema`	`*`	Schemat tabel użytkownika (`*` = wszystkie)

5.9 `Restrictions` — Restrykcje IP

Konfiguracja filtrowania ruchu IP na poziomie poszczególnych aplikacji IIS.

{
  "Restrictions": {
    "ClearRestrictions": false,
    "Applications": [
      {
        "Name": "front",
        "Restrictions": [
          {
            "Ip": "192.168.1.1",
            "Mask": "255.255.255.255",
            "HasMask": false,
            "Traffic": "Allow"
          }
        ]
      },
      {
        "Name": "api",
        "Restrictions": [
          {
            "Ip": "192.168.1.0",
            "Mask": "255.255.255.0",
            "HasMask": true,
            "Traffic": "Deny"
          }
        ]
      }
    ]
  }
}

Pole	Typ	Opis
`ClearRestrictions`	bool	`true` = wyczyść istniejące restrykcje przed dodaniem nowych
`Applications\[].` `Name`	string	Nazwa aplikacji (lowercase, np. `front`, `api`)
`Restrictions\[].` `Ip`	string	Adres IP
`Restrictions\[].` `Mask`	string	Maska podsieci
`Restrictions\[].` `Has` `Mask`	bool	Czy stosować maskę podsieci
`Restrictions\[].` `Traffic`	string	`Allow` lub `Deny`

5.10 `MessageBrokerConfiguration` — RabbitMQ

{
  "MessageBrokerConfiguration": {
    "HostName": "rabbitmq.mycompany.com",
    "VirtualHostName": "/",
    "UserName": "naxiom",
    "Password": "secretPassword",
    "StartLocalServices": false,
    "RabbitNodePort": 0,
    "RabbitDistPort": 0,
    "RabbitManagementConsolePort": 0,
    "ErlangEpmdPort": 0
  }
}

Pole	Typ	Opis
`HostName`	string	Adres hosta RabbitMQ
`Virtual` `Host` `Name`	string	Nazwa hosta wirtualnego w RabbitMQ
`UserName`	string	Użytkownik RabbitMQ
`Password`	string	Hasło RabbitMQ
`Start` `Local` `Services`	bool	`true` = uruchom lokalne usługi RabbitMQ (instalacja lokalna)
`Rabbit` `Node` `Port`	int	Port węzła RabbitMQ (domyślnie 5672)
`Rabbit` `Dist` `Port`	int	Port dystrybucyjny Erlang
`Rabbit` `Management` `Console` `Port`	int	Port konsoli zarządzania RabbitMQ (domyślnie 15672)
`Erlang` `Epmd` `Port`	int	Port EPMD Erlang (domyślnie 4369)

Gdy StartLocalServices = true, instalator konfiguruje porty i uruchamia lokalne serwisy RabbitMQ. Gdy false, podaj adres zdalnego serwera RabbitMQ.

5.11 `DiagnosticsConfiguration` — Diagnostyka i telemetria (opcjonalne)

{
  "DiagnosticsConfiguration": {
    "LogLevel": "Info",
    "LogsTarget": "Db3",
    "ElasticEndpoint": "",
    "ElasticUserName": "",
    "ElasticPassword": "",
    "TelemetryEnabled": false,
    "TracesEndpoint": "",
    "TracesProtocol": "",
    "LogsEndpoint": "",
    "LogsProtocol": "",
    "MetricsEndpoint": "",
    "MetricsProtocol": ""
  }
}

Pole	Typ	Wartości	Opis
`LogLevel`	string	`Trace`, `Debug`, `Info`, `Warn`, `Error`, `Fatal`	Poziom logowania (NLog)
`LogsTarget`	string	`Db3`, `ElasticSearch`	Cel logów: pliki SQLite (Db3) lub ElasticSearch
`Elastic` `Endpoint`	string	URL	Endpoint ElasticSearch
`Elastic` `User` `Name`	string	—	Użytkownik ElasticSearch
`Elastic` `Password`	string	—	Hasło ElasticSearch
`Telemetry` `Enabled`	bool	—	Włącz OpenTelemetry
`Traces` `Endpoint`	string	URL	Endpoint OTLP traces
`Traces` `Protocol`	string	`grpc`, `http/protobuf`	Protokół OTLP traces
`Logs` `Endpoint`	string	URL	Endpoint OTLP logs
`Logs` `Protocol`	string	`grpc`, `http/protobuf`	Protokół OTLP logs
`Metrics` `Endpoint`	string	URL	Endpoint OTLP metrics
`Metrics` `Protocol`	string	`grpc`, `http/protobuf`	Protokół OTLP metrics

Sekcja DiagnosticsConfiguration jest obsługiwana tylko w trybie nogui. W trybie noguiupdate jest pomijana. Dodatkowe ograniczenia opisano w sekcji 10.

6. Kroki instalacji — mechanizm działania

Instalator wykonuje poniższe kroki sekwencyjnie. W trybie GUI każdy krok odpowiada jednej stronie kreatora. W trybie nogui kroki są przetwarzane automatycznie z danymi z pliku JSON.

Krok 1: Weryfikacja wymagań systemowych (`ApplicationRequirementStep`)

Sprawdza obecność wszystkich komponentów (IIS, .NET, SQL Server, itp.). W trybie nogui — jeśli wymaganie obowiązkowe nie jest spełnione, instalacja zostaje przerwana z komunikatem na konsoli.

Krok 2: Konfiguracja IIS (`IISConfigurationStep`)

Odczytuje istniejące witryny nAxiom z serwera IIS.
Ustawia: nazwę witryny, ścieżkę na dysku, typ instalacji (Local/Global), powiązanie (host, port, IP, protokół), certyfikat SSL, tożsamość puli aplikacji.
W trybie noguiupdate — automatycznie wybiera jedyną istniejącą witrynę nAxiom (wymaga dokładnie jednej).

Krok 3: Ruch wewnętrzny (`InternalTrafficStep`)

Opcjonalne dodatkowe powiązanie (binding) dla ruchu wewnętrznego (np. localhost:8082 po HTTP). Konfigurowane przez OptionalLocalBinding w JSON.

Krok 4: Typ środowiska (`EnvironmentTypeStep`)

Ustawia typ środowiska: Development, Test lub Production. Wpływa na pliki konfiguracyjne generowane dla aplikacji.

Krok 5: Przygotowanie pakietów (`PreparePackagesStep`)

Mapuje wpisy z sekcji Packages na dostępne aplikacje.
Rozpoznaje ścieżki do plików ZIP.
W trybie noguiupdate — instaluje tylko pakiety, które już istniały na witrynie lub są oznaczone jako wymagane.

Krok 6: Administrator bazy danych (`AdminDatabaseConnectionStep`)

Konfiguruje połączenie SA (administrator SQL Server).
Mapuje połączenia z Databases do odpowiednich aplikacji.
Odczytuje GlobalSettings.DatabaseConnectionSA.

Krok 7: Połączenia bazodanowe tenantów (`DatabaseConnectionStep`)

Konfiguruje dedykowane połączenia z bazą danych dla poszczególnych aplikacji (np. Api → nAxiom, TenantsApi → nAxiom_tenantsAdmin).

Krok 8: Lokalizacja zasobów (`ResourcesLocationStep`)

Definiuje, gdzie przechowywane są załączniki, wiadomości e-mail, pliki OCR i biblioteki. Obsługuje trzy strategie: folder instalacyjny, wybrany folder lub tabela w bazie danych.

Krok 9: Konfiguracja RabbitMQ (`MessageBrokerConfigurationStep`)

Konfiguruje brokera komunikatów. Obsługuje dwa tryby: połączenie z istniejącym serwerem RabbitMQ lub uruchomienie lokalnych serwisów.

Krok 10: Ustawienia aplikacji (`ApplicationSettingsStep`)

Konfiguruje schematy bazy danych (core, auth, schematy użytkownika).

Krok 11: Diagnostyka (`DiagnosticConfigurationStep`)

Konfiguruje logowanie (NLog) i telemetrię (OpenTelemetry). Odczytuje ustawienia z istniejącej instalacji, zmiennych środowiskowych oraz bazy TenantAdmin.

Krok 12: Restrykcje IP (`IpRestrictionStep`)

Dodaje reguły filtrowania IP do poszczególnych aplikacji w IIS. Możliwe jest czyszczenie istniejących restrykcji przed dodaniem nowych.

Krok 13: Instalacja (`InstallerStep`)

Właściwy krok instalacyjny. Wykonuje sekwencję:

Zatrzymanie witryny IIS i pul aplikacji.
Tworzenie/aktualizacja witryny IIS — konfiguruje bindingi, pule, ścieżki.
Tworzenie/aktualizacja aplikacji IIS — tworzy podkatalogi i aplikacje IIS dla każdego modułu.
Archiwizacja logów — przenosi stare pliki .log, .txt, .db3 z sufiksem _arch.
Rozpakowywanie pakietów ZIP — usuwa stare pliki i rozpakowuje nowe paczki.
Ustawienie uprawnień — nadaje uprawnienia do katalogów aplikacji.
Tworzenie katalogów zasobów — dla załączników, OCR, e-mail.
Backup konfiguracji — tworzy kopie zapasowe plików appsettings.json, appsettings-protected.json, web.config.
Modyfikacja konfiguracji — aktualizuje connection stringi, URL-e, schematy, ustawienia CORS, itp.
Dodanie MIME types — rejestracja .webmanifest.
Wyłączenie Directory Browsing i WebDAV.
Konfiguracja restrykcji IP.
Aktualizacja URL Rewrite rules.
Obsługa błędów globalnych (custom error handling w IIS).
Przygotowanie usług RabbitMQ (jeśli StartLocalServices = true).
Uruchomienie pul aplikacji i witryny IIS.
Generacja pliku summary.json — zawiera URL zainstalowanej witryny.

Krok 14: Podsumowanie (`FinalizeStep`)

Wyświetla adresy URL zainstalowanych aplikacji. W trybie nogui — instalator kończy działanie z kodem wyjścia 0.

7. Przykłady uruchomienia

7.1 Tryb GUI — czysta instalacja

# Uruchom instalator z interfejsem graficznym (bez konfiguracji wstępnej)
.\AppInstaller.exe

7.2 Tryb GUI z wstępnie załadowaną konfiguracją

# GUI z wypełnionymi polami z pliku JSON
.\AppInstaller.exe it=:file iv=:".\install.json"

7.3 Pełna instalacja headless (nogui) z pliku JSON

# Instalacja silent z pliku konfiguracyjnego
.\AppInstaller.exe it=:file iv=:"C:\nAxiom\config\install.json" nogui

7.4 Pełna instalacja headless — JSON inline

# Instalacja silent z JSON przekazanym jako parametr
.\AppInstaller.exe it=:json iv=:"{\"IISApplication\":{\"MainBinding\":{\"Host\":\"mysite.com\",\"Port\":443,\"IpAddress\":\"*\",\"Protocol\":\"https\",\"CertificateThumbprint\":\"03C7D02F...\",\"CertificateStore\":\"My\"},\"InstallationType\":\"Global\",\"WebsiteName\":\"naxiom\",\"WebsitePath\":\"C:\\inetpub\\naxiom\",\"CompanyName\":\"MyCompany\",\"PoolIdentityType\":\"ApplicationPoolIdentity\"},\"Environment\":{\"EnvironmentType\":\"Production\"},\"Packages\":[{\"Name\":\"Front\",\"ZipPath\":\".\\front.zip\"},{\"Name\":\"Api\",\"ZipPath\":\".\\api.zip\"}],\"Databases\":[{\"Name\":\"Api\",\"DatabaseConnection\":{\"Server\":\"localhost\",\"Instance\":\"SQLEXPRESS\",\"Database\":\"nAxiom\",\"IntegratedSecurity\":true}}],\"Schemas\":{\"AppCoreSchema\":\"core\",\"AppAuthSchema\":\"auth\",\"AppUserSchema\":\"*\"},\"Restrictions\":{\"ClearRestrictions\":false,\"Applications\":[]},\"MessageBrokerConfiguration\":{\"HostName\":\"localhost\",\"VirtualHostName\":\"/\",\"UserName\":\"guest\",\"Password\":\"guest\",\"StartLocalServices\":false}}" nogui

⚠️ Przy JSON inline należy użyć zminimalizowanego formatu i poprawnie stosować znaki ucieczki (\") w cmd/PowerShell.

7.5 Aktualizacja plików (noguiupdate)

# Aktualizacja paczek bez zmian konfiguracji
.\AppInstaller.exe it=:file iv=:".\update.json" noguiupdate

Minimalny plik update.json dla noguiupdate:

{
  "Packages": [
    { "Name": "Front", "ZipPath": ".\\front.zip" },
    { "Name": "Admin", "ZipPath": ".\\admin.zip" },
    { "Name": "Api", "ZipPath": ".\\api.zip" },
    { "Name": "Auth", "ZipPath": ".\\auth.zip" },
    { "Name": "TenantsApi", "ZipPath": ".\\tenantsApi.zip" },
    { "Name": "TenantsAdmin", "ZipPath": ".\\tenantsAdmin.zip" },
    { "Name": "Workflow", "ZipPath": ".\\workflow.zip" },
    { "Name": "TaskService", "ZipPath": ".\\taskservice.zip" }
  ]
}

7.6 Sprawdzenie kodu zakończenia w PowerShell

.\AppInstaller.exe it=:file iv=:".\install.json" nogui
$exitCode = $LASTEXITCODE
Write-Host "Kod zakończenia: $exitCode"

if ($exitCode -eq 0) {
    Write-Host "Instalacja zakończona pomyślnie."
} elseif ($exitCode -eq 1) {
    Write-Host "Instalacja zakończona z błędem."
} elseif ($exitCode -eq 10) {
    Write-Host "Instalacja przerwana przed krokiem instalacji."
}

7.7 Uruchomienie z uprawnieniami administratora (PowerShell)

Start-Process -FilePath ".\AppInstaller.exe" `
  -ArgumentList 'it=:file iv=:".\install.json" nogui' `
  -Verb RunAs `
  -Wait

8. Przykładowy plik konfiguracji JSON

Poniżej kompletny plik konfiguracji do instalacji w trybie nogui:

{
  "IISApplication": {
    "MainBinding": {
      "Host": "naxiom.mojafirma.pl",
      "Port": 443,
      "IpAddress": "*",
      "Protocol": "https",
      "CertificateThumbprint": "03C7D02F959CDEBB4C8AB47D079FE17163C53F38",
      "CertificateStore": "My"
    },
    "OptionalLocalBinding": {
      "Host": "localhost",
      "Port": 8082,
      "IpAddress": "*",
      "Protocol": "http"
    },
    "InstallationType": "Global",
    "WebsiteName": "naxiom.mojafirma",
    "WebsitePath": "C:\\inetpub\\naxiom",
    "CompanyName": "MojaFirma",
    "PoolIdentityType": "ApplicationPoolIdentity",
    "IdentityUser": "",
    "IdentityPassword": ""
  },
  "Environment": {
    "EnvironmentType": "Production"
  },
  "Packages": [
    { "Name": "Front", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\front.zip" },
    { "Name": "Admin", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\admin.zip" },
    { "Name": "Api", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\api.zip" },
    { "Name": "Auth", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\auth.zip" },
    { "Name": "TenantsApi", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\tenantsApi.zip" },
    { "Name": "TenantsAdmin", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\tenantsAdmin.zip" },
    { "Name": "Crystal", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\crystal.zip" },
    { "Name": "Workflow", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\workflow.zip" },
    { "Name": "TaskService", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\taskservice.zip" },
    { "Name": "PublicApi", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\PublicApi.zip" },
    { "Name": "Syncfusion", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\syncfusion.zip" },
    { "Name": "ReportsApi", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\reportsApi.zip" },
    { "Name": "MobileApi", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\mobileApi.zip" },
    { "Name": "DocApi", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\docApi.zip" },
    { "Name": "DocPdf", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\docPdf.zip" },
    { "Name": "Bpmn", "ZipPath": "C:\\nAxiom\\Wersje\\1.15.6\\bpmn.zip" }
  ],
  "Databases": [
    {
      "Name": "Api",
      "DatabaseConnection": {
        "Server": "sql-server.mojafirma.pl",
        "UsePort": false,
        "Port": 1433,
        "Timeout": 30,
        "Instance": "",
        "IntegratedSecurity": false,
        "Username": "naxiom_app",
        "Password": "StrongPassword123!",
        "Database": "nAxiom"
      }
    },
    {
      "Name": "TenantsApi",
      "DatabaseConnection": {
        "Server": "sql-server.mojafirma.pl",
        "UsePort": false,
        "Port": 1433,
        "Timeout": 30,
        "Instance": "",
        "IntegratedSecurity": false,
        "Username": "naxiom_tenantadmin",
        "Password": "StrongPassword456!",
        "Database": "nAxiom_tenantsAdmin"
      }
    }
  ],
  "GlobalSettings": {
    "DatabaseConnectionSA": {
      "Server": "sql-server.mojafirma.pl",
      "UsePort": false,
      "Port": 1433,
      "Timeout": 30,
      "Instance": "",
      "IntegratedSecurity": false,
      "Username": "sa",
      "Password": "SAPassword789!",
      "Database": ""
    }
  },
  "ResourceLocations": [
    {
      "ResourceType": "Attachments",
      "Location": "InstallationFolder",
      "DatabaseConnection": null,
      "TableName": "",
      "FolderPath": ""
    },
    {
      "ResourceType": "EmailMessages",
      "Location": "InstallationFolder",
      "DatabaseConnection": null,
      "TableName": "",
      "FolderPath": ""
    },
    {
      "ResourceType": "Ocr",
      "Location": "InstallationFolder",
      "DatabaseConnection": null,
      "TableName": "",
      "FolderPath": ""
    },
    {
      "ResourceType": "AdditionalLibrary",
      "Location": "InstallationFolder",
      "DatabaseConnection": null,
      "TableName": "",
      "FolderPath": ""
    }
  ],
  "Schemas": {
    "AppCoreSchema": "core",
    "AppAuthSchema": "auth",
    "AppUserSchema": "*"
  },
  "Restrictions": {
    "ClearRestrictions": false,
    "Applications": []
  },
  "MessageBrokerConfiguration": {
    "HostName": "rabbitmq.mojafirma.pl",
    "VirtualHostName": "/",
    "UserName": "naxiom",
    "Password": "RabbitPassword!",
    "StartLocalServices": false,
    "RabbitNodePort": 0,
    "RabbitDistPort": 0,
    "RabbitManagementConsolePort": 0,
    "ErlangEpmdPort": 0
  }
}

9. Kody zakończenia (Exit Codes)

Kod	Znaczenie
`0`	Instalacja zakończona pomyślnie
`1`	Wystąpił błąd podczas instalacji
`10`	Instalacja przerwana przed krokiem instalacyjnym (zamknięto kreator)

W trybie nogui/noguiupdate kod zakończenia jest dostępny poprzez:

cmd: echo %ERRORLEVEL%
PowerShell: $LASTEXITCODE

10. Ograniczenia i znane braki

10.1 Ograniczenia trybu `nogui`

Ograniczenie	Opis
Brak walidacji danych wejściowych	Instalator nie sprawdza poprawności wartości w pliku JSON przed rozpoczęciem instalacji. Błędne dane mogą spowodować nieprzewidywalne zachowanie.
Diagnostyka — częściowe wsparcie	Sekcja `DiagnosticsConfiguration` w trybie `nogui` jest jedynie częściowo obsługiwana — metoda `SetSettings` przyjmuje model, ale nie aplikuje wszystkich wartości do kontrolek. Główna konfiguracja diagnostyki odczytywana jest z istniejących plików `appsettings.json`, zmiennych środowiskowych i bazy TenantAdmin. Domyślne ustawienia mogą być zastosowane zamiast tych z JSON.
Brak parametru `--help`	Instalator nie oferuje wbudowanej pomocy CLI.

10.2 Ograniczenia trybu `noguiupdate`

Ograniczenie	Opis
Jedna witryna	Tryb `noguiupdate` działa poprawnie wyłącznie, gdy na IIS istnieje dokładnie jedna witryna nAxiom.
Brak zmiany konfiguracji	Aktualizowane są wyłącznie pliki — ustawienia IIS, bazy danych, schematy, restrykcje itp. pozostają niezmienione.

10.3 Ograniczenia ogólne

Ograniczenie	Opis
Tylko Windows	Instalator jest aplikacją Windows Forms — działa wyłącznie na systemie Windows.
Wymagane uprawnienia administratora	Operacje na IIS wymagają uruchomienia jako administrator.
Hasła w jawnym tekście	Hasła w pliku JSON są przechowywane w postaci jawnej. Connection stringi są szyfrowane dopiero po wgraniu do plików konfiguracyjnych.
Brak walidacji JSON	Brak schematu JSON Schema do walidacji pliku konfiguracyjnego. Błędy w strukturze JSON powodują wyjątki deserializacji.
Brak logowania do pliku	W trybie `nogui` komunikaty wyświetlane są na konsoli — nie ma dedykowanego pliku logu z instalacji (jedynie `summary.json` po zakończeniu).
Brak mechanizmu rollback	W przypadku błędu podczas instalacji — nie jest wykonywane automatyczne cofnięcie zmian (konfiguracja jest przywracana z backup, ale witryna IIS może pozostać w niespójnym stanie).

10.4 Ustawienia z JSON — pominięte w trybie `noguiupdate`

Następujące sekcje pliku JSON są ignorowane w trybie noguiupdate:

IISApplication (poza wyborem istniejącej witryny)
Environment
Databases
GlobalSettings
ResourceLocations
Schemas
Restrictions
MessageBrokerConfiguration
DiagnosticsConfiguration

11. Dobre praktyki

11.1 Przygotowanie pliku JSON

Użyj szablonu — skopiuj plik ConfigTemplate.json z AppInstaller\Configuration\Documentation\ jako punkt wyjścia.
Waliduj JSON — przed uruchomieniem sprawdź poprawność składni JSON (np. python -m json.tool install.json lub dowolny edytor z podświetlaniem).
Nie zostawiaj hasła SA w pliku — po instalacji usuń plik konfiguracyjny lub zabezpiecz go odpowiednimi uprawnieniami.
Test w trybie GUI — przed deploymentem nogui przetestuj konfigurację w trybie GUI z załadowanym JSON (it=:file iv=:".\install.json" bez nogui), aby zweryfikować poprawność wartości.

11.2 Bezpieczeństwo

Uprawnienia pliku JSON — ogranicz dostęp do pliku konfiguracyjnego (zawiera hasła w jawnej postaci).
Usunięcie pliku po instalacji — po pomyślnej instalacji usuń plik JSON zawierający dane uwierzytelniające.
Certyfikat SSL — dla instalacji Global zawsze używaj protokołu https z poprawnym certyfikatem.
Restrykcje IP — dla aplikacji backendowych (Api, TaskService, Crystal) rozważ ograniczenie dostępu do ruchu wewnętrznego.
Konto puli aplikacji — w środowisku produkcyjnym rozważ użycie dedykowanego konta (SpecificUser) zamiast ApplicationPoolIdentity.

11.3 Aktualizacje

Backup przed aktualizacją — instalator tworzy pliki .backup, ale warto mieć pełną kopię katalogu witryny.
Użyj noguiupdate do aktualizacji plików — nie zmienia konfiguracji, minimalizuje ryzyko.
Plik summary.json — po instalacji sprawdź plik summary.json w katalogu instalatora — zawiera URL witryny.

11.4 Automatyzacja i CI/CD

Ścieżki względne — w pliku JSON używaj ścieżek względnych (.\front.zip) — ułatwia przenoszenie między środowiskami.
Sprawdzaj exit code — w skryptach zawsze weryfikuj $LASTEXITCODE / %ERRORLEVEL%.

Przekierowanie wyjścia — w trybie nogui output jest kierowany na konsolę:

.\AppInstaller.exe it=:file iv=:".\install.json" nogui 2>&1 | Tee-Object -FilePath "install.log"

Osobny JSON per środowisko — przygotuj osobne pliki konfiguracyjne dla dev/test/prod.

11.5 Pomijanie opcjonalnych pakietów

Aby pominąć instalację opcjonalnych modułów (np. OcrApi, Crystal, PublicApi):

Usuń wpis pakietu z sekcji Packages.
Usuń wpis z sekcji Databases (jeśli aplikacja wymaga bazy danych).
Upewnij się, że żadna inna sekcja nie odwołuje się do pominiętego pakietu.

12. FAQ / Rozwiązywanie problemów

Instalator kończy się natychmiast z kodem 1

Przyczyna: Brak poprawnej konfiguracji JSON przy użyciu flagi nogui/noguiupdate. Rozwiązanie: Upewnij się, że parametry it i iv są poprawnie sformatowane. Separator to =: (nie =).

Błąd: “Nie znaleziono witryny do automatycznej aktualizacji”

Przyczyna: Tryb noguiupdate nie znalazł żadnej witryny nAxiom na IIS. Rozwiązanie: Upewnij się, że na serwerze IIS istnieje witryna z pulą aplikacji o nazwie zaczynającej się od naxiom..

Błąd: “Automatyczna aktualizacja nie może być przeprowadzona jeżeli istnieje więcej niż jedna witryna”

Przyczyna: Na IIS istnieje więcej niż jedna witryna nAxiom. Rozwiązanie: Użyj trybu nogui z pełną konfiguracją JSON zamiast noguiupdate.

Certyfikat SSL nie został znaleziony

Przyczyna: Podany CertificateThumbprint nie odpowiada żadnemu certyfikatowi w magazynie. Rozwiązanie: Sprawdź thumbprint certyfikatu w MMC (Certificates → Local Computer) i upewnij się, że wartość CertificateStore jest poprawna (zwykle My dla Personal).

Plik JSON nie jest odnajdywany

Przyczyna: Ścieżka w parametrze iv jest niepoprawna. Rozwiązanie:

Użyj ścieżki bezwzględnej: iv=:"C:\config\install.json"
Ścieżka względna .\ odnosi się do katalogu, w którym znajduje się AppInstaller.exe, nie do bieżącego katalogu roboczego.

Brak komunikatów na konsoli w trybie `nogui`

Przyczyna: Instalator jest aplikacją Windows Forms — konsola musi być podłączona. Rozwiązanie: Uruchom z poziomu istniejącej konsoli cmd lub PowerShell (nie przez podwójne kliknięcie). Instalator automatycznie podłącza się do konsoli nadrzędnej.

Wygenerowano na podstawie analizy kodu źródłowego nAxiom AppInstaller.

AppInstaller — opis techniczny

1. Wprowadzenie

2. Wymagania systemowe

3. Tryby instalacji

3.1 Tryb GUI (graficzny)

3.2 Tryb headless — pełna instalacja (nogui)

3.3 Tryb headless — aktualizacja plików (noguiupdate)

3.4 Porównanie trybów

4. Parametry wiersza poleceń (CLI)

4.1 Składnia

4.2 Lista parametrów

4.3 Format separatora

4.4 Obsługiwane ścieżki do pliku JSON

5. Konfiguracja JSON — pełna specyfikacja

5.1 Struktura główna

5.2 IISApplication — Konfiguracja witryny IIS

5.3 Environment — Typ środowiska

5.4 Packages — Pakiety instalacyjne

Dostępne nazwy pakietów (Name):

5.5 Databases — Połączenia z bazami danych

5.6 GlobalSettings — Połączenie administratora SA

5.7 ResourceLocations — Lokalizacja zasobów

Typy zasobów (ResourceType):

Lokalizacja (Location):

5.8 Schemas — Schematy bazy danych

5.9 Restrictions — Restrykcje IP

5.10 MessageBrokerConfiguration — RabbitMQ

5.11 DiagnosticsConfiguration — Diagnostyka i telemetria (opcjonalne)