Po co Starter?¶

Głównym założeniem Sente Startera jest możliwość łatwej i szybkiej dystrybucji aplikacji i jej przyszłych aktualizacji, głównie w sieci intranet. Taka potrzeba wynikła między innymi z problemów, jakich przysparza uruchamianie Sente S4 z zasobów sieciowych. Jednak Starter jest narzędziem bardziej uniwersalnym, ponieważ pozwala na uruchamianie w zasadzie dowolnej aplikacji.

Całość jest oparta na architekturze klient-serwer. Strona kliencka to 2 pliki — wykonywalny i konfiguracyjny. Aktualnie Starter dostępny jest w dwóch wersjach: windowsowej, która wyświetla logo Teneum oraz informuje o postępie aktualizacji oraz przenośnej-konsolowej ta może działać pod kontrolą zarówno windowsa jak i linuxa i może przydać się np. do aktualizowania narzędzi używanych w procesach Jenkinsowych. Strona serwerowa, odpowiedzialna za serwowanie plików, nie narzuca stosowania konkretnej technologii, jednak zalecanymi serwerami http są Serwer Python lub nginx.

Jak działa synchronizacja plików?¶

Przygotowanie repozytorium zdalnego¶

Starter używa repozytorium zdalnego do pobierania plików aplikacji. Repozytorium zdalne to nic innego jak katalog na serwerze http. Zalecanymi serwerami są Serwer Python lub nginx. W tym tutorialu nauczysz się jak przygotować oba warianty.

Serwer nginx¶

Instalacja¶

Pobieramy plik z oficjalnej strony producenta nginx/Windows-x.x.x
Serwer nginx nie posiada instalatora. Jego instalacja, to wypakowania pobranego archiwum, do preferowanego przez siebie folderu - na potrzeby tego dokumentu, będzie to C:\nginx
W lokalizacji, z plikami serwera, należy utworzyć nowy folder, który będzie zawierał pliki, wymagane dla Startera. Na potrzeby tego dokumentu, utworzony zostanie folder StarterFiles
Poniższy tutorial ukazuje konfigurację, w której definujemy kanały aktualizacji i "klientów, czyli wersje oprogramowania, dostępne do pobrania. Dlatego zaleca się stworzenie dwóch dodatkowych folderów, w lokalizacji przeznaczonej na pliki dla Startera. Nazwy dla nich, to kolejno Channels oraz Clients.

Konfiguracja¶

Plik konfiguracyjny serwera, znajduje się w <ścieżka_wypakowania_plików>\conf\nginx.conf. Sekcja, która jest na potrzeby tej konfiguracji istotna, znajduje się w znaczniku server.

 server {
        listen       80;
        server_name  localhost;

        #charset koi8-r;

        #access_log  logs/host.access.log  main;

        location / {
            root   html;
            index  index.html index.htm;
        }

        ...dalsza konfiguracja

Warning

Zamieszczony powyżej kod, pochodzi z wersji 1.21.16 i w przyszłości, może wyglądać inaczej. Najważniejsze, by zlokalizować znacznik server, bo to on agreguje główną konfigurację.

Parametr listen odpowiada za port, na którym będzie działał serwer. Możliwe do edycji, jeśli np. z jakiś przyczyn port 80 jest już zajęty, ale należy pamiętać, o wprowadzonej tutaj zmianie, bo adres jest wymagany w dalszej części materiału.
Parametr server_name zaleca się pozostawić bez zmian.
Znacznik location / należy edytować, dokonując dwóch modyfikacji:
- Linia ze znacznikiem root informuje serwer, o nazwie folderu, który będzie domyślną lokalizacją. Należy tutaj wprowadzić nazwę folderu, utworzonego na potrzeby przechowywania plików Startera
- Linię informującą o pliku index należy usunąć
- Należy dodać nowy wpis, o treści autoindex on;

Poniżej umieszczony przykład konfiguracji, zmienionej, według wyżej podanych kroków

server {
        listen       80;
        server_name  localhost;

        #charset koi8-r;

        #access_log  logs/host.access.log  main;

        location / {
            root   StarterFiles;
            autoindex on;
        }


        ...dalsza konfiguracja

Test działania¶

By zweryfikować poprawność konfiguracji i działania serwera, należy uruchomić plik nginx.exe, który znajduje się w folderze z plikami serwera. Jeśli wszystko zostało skonfiguorwane poprawnie i serwer się uruchomił, to wpisanie w przeglądarce, adresu http://localhost:<port_z_konfiguracji> powinno wyświetlić zawartość folderu, utworzonego na potrzeby plików startera i określonego w konfiguracji.

Warning

Pierwsze uruchomienie serwera nginx, często wyświetla monit z zapory systemu windows, z pytaniem, czy zezwolić procesowi nginx'a na dostęp do sieci. W przypadku instalacji u klient, o tym, w jakich sieciach może działać proces, należy zdecydać z administratorem klienta. Oznaczać to będzie, w pełni poprawną konfigurację.

Tip

Po poprawanym otworzeniu strony w przeglądarce, warto przejść do folderu na pliki Startera i stworzyć tam nowy plik/folder - po odświeżeniu strony, powinien się on na niej pojawić.

Automatyczne uruchamianie serwera¶

By serwer aktualizacji był zawsze dostępny, należy jego uruchamianie dodać do autostartu. By to wykonać, należy kolejno: 1. Otworzyć folder z plikami serwera nginx i utworzyć skrót, dla aplikacji nginx.exe (PPM->Utwórz skrót) 2. Otworzyć aplikację Uruchom (wyszukać frazę w Menu Start lub użyć skrótu klawiszowego Windows + R) 3. W wyświetlonym oknie, należy wprowadzić frazę shell:startup i wcisnąć OK 4. Skopiować utworzony w folderze nginx'a skrót i wkleić do folderu, który otworzył się, po wciśnięciu OK 5. Gotowe!

Taki zabieg spowoduje, że nawet po ponownym uruchomieniu komputera, serwer sam się uruchomi.

Serwer python¶

Instalacja automatyczna¶

Pobieramy plik HttpPython.zip
Wypakowujemy folder np. na dysku C:\
Jeśli chcemy hostować pliki z folderu c:\sente to nic nie zmieniamy. Gdy potrzebujemy innej ścieżki lub portu (przykładowy 80 jest już zajęty) to należy wejść do wypakowanego folderu i edytować plik ServiceInstall.py
Poniższy tutorial ukazuje konfigurację, w której definujemy kanały aktualizacji i klientów, czyli wersje oprogramowania, dostępne do pobrania. Dlatego zaleca się stworzenie dwóch dodatkowych folderów, w lokalizacji przeznaczonej na pliki dla Startera. Nazwy dla nich, to kolejno Channels oraz Clients.

_svc_name_ = "PythonHttpServer"
_svc_display_name_ = "PythonHttpServer"
_svc_port = 80
_svc_http_path = "C:\sente"

Modyfikujemy _svc_http_path na ścieżkę do folderu, który będzie hostowany przez serwer HTTP. Analogicznie port. Nie możemy zmieniać nazwy serwera oraz nazwy wyświetlanej. Dalsze części skryptów korzystają z w/w nazwy.

Po ustawieniu folderu tworzymy go w systemie.
Uruchamiamy konsolę cmd jako administrator.
Przechodzimy do C:\HttpPython\ i uruchamiamy plik HTTP.Service.Install.bat
Serwer powinien zostać zainstalowany i uruchomiony.

Po wykonaniu powyższych kroków, serwer powinien być dostępny, pod adresem http://localhost:<port_z_konfiguracji>/. Otworzenie powyższego linku w przeglądarce, powinno wyświetlić zawartość katalogu, zdefiniowanego w pliku konfiguracyjnym (na ten moment pustą, bo katalog nie ma zawartości).

Ważne!

Gdy z zewnątrz (inny komputer) nie widzimy plików oznacza to, że np. firewall zablokował połączenie. Należy dodać wyjątek do zapory lub programu antywirusowego.

Ważne!

Dla wydajnego działania serwera HTTP należy ustawić w pliku *.config startera parametr "MaxDownloadConnections" na 10. Przy tej wartości serwer najlepiej sobie radzi.

Test konfiguracji repozytorium¶

Po wykonaniu powyższych kroków warto przetestować czy repozytorium jest dostępne z przeglądarki. W tym celu należy:

Sprawdź, czy usługa "PythonHttpServer" działa, jeśli nie, to ją uruchom.
Otwórz przeglądarkę www na maszynie, na której stoi serwer i wpisz adres http://localhost:<port_z_konfiguracji>. W oknie przeglądarki powinna wyświetlić się zawartość katalogu, czyli foldery Channels oraz Clients

Pliki startera¶

Założenia ogólne¶

Ważne!

Lokalizacja na pliki została wskazana w pliku konfiguracyjnym, w trakcie instalacji. W powyższym dokumencie jest to <sciezka_do_nginxa>/StarterFiles dla serwera nginx`` orazC:\Sentedla serwerapython```

Konfiguracja kanałów aktualizacji¶

W jednym repozytorium można skonfigurować praktycznie nieskończoną liczbę kanałów aktualizacji. Mogą to być zarówno różne aplikacje, jak i różne wersje tej samej aplikacji. Każdy kanał powinien być skonfigurowany w osobnym pliku json (katalog Channels w przykładowej strukturze).
Poniżej przykładowa struktura. Parametry określają kolejno z jakiego adresu Starter ma pobierać wersję stabilną aplikacji Sente Teneum i gdzie szukać pliku sum kontrolnych - o jego generowaniu, w kolejnym rozdziale.

{
  "BaseRepositoryUrl" : "http://<adres_ip_serwera>:<port>/Clients/Stable/4.2.0/",
  "RelativeCRC32DataFileUrl" : "files.crc"
}

Przed zatwierdzeniem konfiguracji, dobrą praktyką jest, by adres, przypisywany pod BaseRepositoryUrl, otworzyć w oknie przeglądarki. Taka akcja, powinna wyświetlić zawartość folderu - jeśli tak się dzieje, to adres jest poprawny i można zapisać plik konfiguraycjny.

Generowanie sum kontrolnych¶

Starter dokonuje selekcji plików do pobrania na podstawie sum kontrolnych zapisanych w pliku files.crc, który jest pobierany z repozytorium wraz z aplikacją. Aby Starter działał poprawnie należy więc taki plik wygenerować. Możesz to zrobić za pomocą Starter Managera. W parametrze podaj tylko ścieżkę do aplikacji.

Najnowszą wersję Starter Managera można znaleźć w X:\DBR\release\starter

`Sente.Launcher.Manager.Portable.exe -TargetDir=C:\Sente\Clients\Stable\4.2.0\`

Tip

Obejrzyj wideo

Po wygenerowaniu pliku files.crc repozytorium jest już gotowe. - W razie problemów można dopisać -Verbose=true. - Od wersji 1.0.6 można również podać za pomocą parametru -include= nazwę pliku, w którym podamy listę plików, dla których mają być liczone kody CRC. Kolejne ścieżki umieszczamy w nowych liniach, na przykład:

wyrażenie	pasuje do	nie pasuje do	opis
file.txt	file.txt	otherfile.txt, file.etx	konkretny plik w głównym katalogu
dir/file.txt	dir/file.txt, dir\file.txt	dir2/file.txt, dir\file2.txt	konkretny plik w konkretnym podkatalogu
*	file.ext, file.ext.2, .gitignore	dir/file.txt	dowolny plik w podanym katalogu
*.	file.	file.ext, .ext	plik bez rozszerzenia
.*	.gitignore	file., file.ext	plik bez nazwy
**/	dir/, dir1\dir2\, dir1/dir2\dir3\	file.ext	wiele (co najmniej jeden) katalogów
`<wyrażenie regularne>	wyrażenie regularne musi zostać dopasowane do całej ścieżki i nazwy pliku razem z rozszerzeniem, czyli `[^.]*[.]dot` będzie pasować do `cos.dot` i `.dot` ale nie do `cos.dotted`

Przykład

wywołanie:

Sente.Launcher.Manager.Portable.exe -targetdir=c:/workspace/s4/out -include=C:\workspace\s4\Out\s4-include.txt -Verbose=true

Treść pliku s4-include.txt:

*.dll
*.exe
*.bpl
*.xml
*.ini
*.app
*.prt
*.rpt
*.dbi
*.ser
*.loc
*.config
*.pak
*.bin
*.lib
bmp/*

Polecenie usuwania plików¶

Od wersji 1.1.4 Startera można w konfiguracji zdalnej określać, które pliki mają ZA KAŻDYM RAZEM być usuwane z dysku przed aktualizacją, na przykład:

{
  "BaseRepositoryUrl" : "http://<adres_ip_serwera>:<port>/Clients/Stable/4.2.0/",
  "RelativeCRC32DataFileUrl" : "files.crc",
  "Commands" : [
    { 
      "Command" : "delete",
      "FileMask" : "*.bpl"
    },
    { 
      "Command" : "delete",
      "FileMask" : "*.exe"
    },
  ]
}

Ustawianie specjalnych konfiguracji dla poszczególnych użytkowników¶

Od wersji 1.1.7 można w zdalnej konfiguracji określać specjalne konfiguracje dla poszczególnych użytkowników, określonych za pomocą ich ip, nazwy użytkownika lub obu jednocześnie.

}
  "BaseRepositoryUrl" : "http://<adres_ip_serwera>:<port>/Clients/Stable/4.2.0/",
  "RelativeCRC32DataFileUrl" : "files.crc",
    "UsersConfigs" : [{
      "BaseRepositoryUrl" : "adres repozytorium, z którego ma korzystać dany użytkownik, nadpisuje BaseRepositoryUrl z pliku .config",
      "UserLogin" : "nazwa użykownika - skrócona iksiński lub z domeną SENTE\\iksiński - uwaga na znak \ w jsonie trzeba go escapować \\",
      "UserIp" : "ip użytkownika",
      "UserMachineName": "nazwa komputera użytkownika",
      "TargetDirUrl" : "folder na komputerze użytkownika, do którego mają być pobierane pliki, nadpisuje TargetDirUrl z pliku .config",
      "ApplicationToExecute" : "plik .exe, który ma zostać uruchomiony po aktualizacji. Nadpisuje klucz ApplicationToExecute z pliku .config"
    },
    {kolejny użytkownik}
    ]
{

Jeśli jednocześnie podamy adres ip i login użytkownika, to aby Starter skorzystał ze specjalnej konfiguracji, oba parametry muszą się zgadzać. Parametry TargetDirUrl i ApplicationToExecute są opcjonalne. Gdy nie jest on ustawiony to Starter korzysta z folderu i aplikacji, które są ustawione w lokalnej konfiguracji użytkownika. W ścieżce TargetDirUrl można korzystać ze zmiennych systemowych, np %LOCALAPPDATA%\Sente\Teneum. Instalowanie tam Teneum nie wymaga uprawnień administratora.

Udzielenie dostępu tylko wybranym użytkownikom¶

Od wersji 1.1.7.3 można w zdalnej konfiguracji nie określać bazowego repozytorium zdalnego, a w zamian tego ustawić tekst komunikatu dla użytkowników, którzy nie mają w swoim UserConfigu zdefiniowanego adresu url repozytorium. Można nie dodawać tego klucza, wtedy w przypadku, gdy nie ma zdefiniowanego repozytorium, wyświetlany jest domyślny tekst komunikatu.

}
    "NoBaseRepositoryErrorText" : "tekst, który chcemy wyświetlić użytkownikom, którym nie daliśmy dostępu",
    "RelativeCRC32DataFileUrl" : "files.crc",
        "UsersConfigs" : [{
             "BaseRepositoryUrl" : "adres repozytorium, z którego ma korzystać dany użytkownik"
              "UserLogin" : "nazwa użykownika - skrócona iksiński lub z domeną SENTE\\iksiński - uwaga na znak \ w jsonie trzeba go escapować \\",
              "UserIp" : "ip użytkownika",
              "UserMachineName": "nazwa komputera użytkownika",
              "TargetDirUrl" : "folder na komputerze użytkownika, do którego mają być pobierane pliki, nadpisuje TargetDirUrl z pliku .config",
              "ApplicationToExecute" : "plik .exe, który ma zostać uruchomiony po aktualizacji. Nadpisuje klucz ApplicationToExecute z pliku .config"
        },
        {kolejny użytkownik}
        ]
{

Aby NoBaseRepositoryErrorText działał poprawnie, w konfiguracji zdalnej nie może być zadeklarowane BaseRepositoryUrl!

Rolling update¶

Przykład, zaprezentowany w powyższej konfiguracji, pozwala, by wybranym użytkownikom ustawić inną wersję aplikacji, niż domyślną i łatwo ją zmieniać modyfikując tylko plik ze zdalną konfiguracją. W takim wypadku musimy mieć zdefiniowanych co najmniej dwa Channele z plikami, ale oprócz tego zalecamy też pobierać je do osobnych lokalizacji lokalnych, dzięki czemu po przełączeniu nie trzeba będzie pobierać żadnych plików. Na przykład %LOCALAPPDATA%\Sente\S4 oraz %LOCALAPPDATA%\Sente\S4_test

Starter 1.0.7¶

Od wersji startera 1.0.7 został wprowadzony dodatkowy parametr -includealso= który działa tak jak -include=. Jeżeli podano obie opcje, uwzględniane są listy zawarte w obu plikach. Pozwala nam to obsłużyć przypadek, w którym chcemy mieć jeden plik ze standardowymi plikami aplikacji a w drugim trzymać konfigurację per użytkownik. Możemy wtedy wygenerować różne pliki crc dla różnych użytkowników.

Dodatkowa opcja -output= pozwala podać explicite nazwę generowanego pliku crc. Domyślna wartość jest zgodna z poprzednimi wersjami (files.crc). W związku z tym, że dopuszczamy teraz w katalogu wiele plików .crc rozszerzenie to zostało NA STAŁE włączone do plików wykluczonych z dystrybucji.

Konfiguracja klienta startera¶

Najnowszą wersję Startera można znaleźć w X:\DBR\release\launcher.

Skopiuj pliki startera do wybranego przez siebie katalogu. Nie musi to być katalog, z którego będzie uruchamiana aplikacja, ponieważ ścieżka do aplikacji jest konfigurowalna.
Skonfiguruj startera w pliku TeneumStarter.exe.config. Opisane niżej trzy klucze są absolutnym minimum wymaganym do działania.
- RemoteLauncherConfigurationUrl - Tutaj wpisz adres http do pliku konfiguracyjnego json.
- TargetDirUrl - Tu wpisz katalog docelowy dla pobranej aplikacji. Jeżeli pokrywa się z katalogiem, w którym uruchamiasz startera po prostu wpisz ./.
- ApplicationToExecute - Tu wpisz nazwę pliku, który uruchomi startera po aktualizacji, czyli najczęściej sentes4.exe.
Uruchom Launcher. Powinien pojawić się splashscreen, który poinformuje, że startera pobiera równolegle pliki. Po zakończeniu pobierania zostanie uruchomiona aplikacja.

Tip

Obejrzyj wideo

Włączenie dokładniejszych logów¶

W dowolnej wersji startera w przypadku problemów możliwe jest zwiększenie ilości informacji domyślnie zapisywanych do loga aplikacji. W tym celu należy ustawić atrybut minlevel na Trace :

<configuration>
  ...
  <nlog>
    ...
    <rules>
      <logger ... minlevel="Trace" ... />

Telemetria w starterze¶

starter w wersjach powyżej 1.1.7 wysyła domyślnie dane telemetryczne na serwer https://telemetria.sente.pl. Są one przechowywane w tabeli LAUNCHER_TELEMETRY_DATA na bazie firmowej.

Informacje, które starter wysyła na serwer: - wersja startera - wersja uruchamianej aplikacji - krok, w którym starter zakończył działanie - lokalne ip, użytkownik oraz domena komputera użytkownika

Telemetrię w starterze można wyłączyć w lokalnym configu startera za pomocą klucza: IsTelemetryEnabled=false

Adres lub metodę webserwisu, do którego wysyłane są dane telemetryczne można zmienić w lokalnym configu startera za pomocą kluczy:

TelemetryApiUriString=[adres webserwisu]
TelemetryApiMethodString=[metoda webserwisu]

Wymuszenie uruchamiania aplikacji przez startera¶

Starter od wersji 1.1.7 przy uruchamianiu aplikacji dodaje dodatkowy argument -ranbylauncher oraz ustawia prywatną dla usera ale trwałą zmienną środowiskową SENTELAUNCHER. Dzięki temu aplikacja może wykryć czy została uruchomiona przez startera czy nie i na przykład uruchomić startera samodzielnie a samemu się zamknąć.

Wymuszenie uruchamiania aplikacji Sente S4 przez startera¶

Trzeba mieć wersję >=4.6.10 aplikacji lub zmiany z tematu BS131023 (Lista zmian i drobny fix) oraz startera 1.1.7 a także ustawiony w pliku .app klucz:

[General]
RunOnlyByLauncher=yes

Jeżeli coś nie gra¶

Jeżeli wystąpi jakiś błąd pasek postępu będzie migał na czerwono, a starter zapisze treść błędu w pliku Sente.Launcher.log, w katalogu, z którego został uruchomiony.

Tip

Obejrzyj wideo

Ograniczenia startera¶

Max rozmiar plików jakie można pobierać to 50MB.
Ponieważ wykrywanie różnic między zdalnym repozytorium a plikami pobranymi lokalnymi odbywa się na podstawie sum kontrolnych, nie jest możliwe podgranie do repozytorium nowego pliku tak po prostu bez wygenerowania nowego pliku z sumami kontrolnymi (files.crc).
Działanie startera jest jednokierunkowe. To oznacza, że różnice wykryte w repozytorium zdalnym są pobierane lokalnie z nadpisaniem istniejących plików. Natomiast różnice wykryte lokalnie nie będą przesyłane do repozytorium zdalnego.

Deinstalacja automatyczna, serwera python HTTP¶

Uruchamiamy konsolę cmd z prawami administratora
Przechodzimy do folderu, gdzie zostało wypakowane, wcześniej pobrane archiwum
Uruchamiamy skrypt: HTTP.Service.Remove.bat

Konfiguracja zapory sieciowej¶

Możliwe jest, że starter będzie działał poprawnie, na komputerze, na którym został skonfigurowany serwer, ale nie będzie dostępny z innego komputera. Powodem takie stanu rzeczy, jest prawdopodobnie zapora systemu Windows. Odblokowanie dostępu do serwera, z zewnątrz, wykonuje się następująco: 1. W Menu Start należy wyszukać frazę Zapora Windows Defender z zabezpieczeniami zaawansowanymi i ją uruchomić. 2. Z menu po lewej stronie, należy wybrać reguły przychodzące''' 3. Po tym kroku, należy wybrać akcjęNowa reguła, z menu po prawej stronie 4. Jako typ reguły, należy wsazaćPort5. Typ protokołu, należy wskazaćTCPi poniżej wybraćOkreślone porty lokalne, a w polu tekstowym, wpisać port, ustawiony w pliku konfiguracyjnym serwera 6. Na ekranie akcji, należy wskazać, by zezwalał na połączenie 7. Na oknie wyboru profilu, należy wskazać odpowiednie opcje - do konsultacji z Administratorem sieciowym 8. Należy powtórzyć czynności, zaczynając od punktu nr.2, ale wybraćreguły wychodzące```