fillup PremiumDB

Informacje ogólne

Dokument zawiera opis aplikacji serwerowej fillup PremiumDB. System pozwala na persystencję danych pochodzących z systemu fillup Desktop, umożliwia równoczesną pracę operatorów fillup Desktop z zasobami firmy oraz przechowywanie danych na serwerach wewnątrz firmy.

Wymagania sprzętowe

Środowisko serwerowe 

• Procesor: 64-bit, min. 2 GHz
• Pamięć RAM: min. 8 GB
• HDD: minimum 128 GB, zalecane 1 TB SSD - przestrzeń dyskowa powinna być dobrana pod kątem przewidywanej ilości danych zapisywanych w aplikacjach frontowych: ilości dokumentów oraz ilości i zajętości dołączanych plików jako załączniki. Średnia statystyczna zajętość jednego dokumentu to ok. 10 KB. Należy również wziąć pod uwagę ilość automatycznych i manualnych backupów jakie są wykonywane.  

 System operacyjny

Zalecamy instalację produktu na czystym środowisku Unix/Linux. Możliwa jest również instalacja aplikacji na środowisku Windows z użyciem programu WSL2 - Windows Subsystem for Linux – udostępniający zintegrowane środowisko systemu GNU/Linux z poziomu systemu Windows. WSL2 dostępne jest w systemach operacyjnych:

• Windows 11
• Windows od wersji 10 i kompilacji 1904 wzwyż
• Windows server 2019

Nie są wspierane:

• Windows 10 desktop consumer editions w wersjach poniżej kompilacji 1904
• Windows 8.1 i starsze
  • Windows 8
  • Windows 7
• Windows server 2016 poniżej kompilacji z 2017 roku i starsze
  • Windows server 2012
  • Windows server 2011
  • Windows server 2008  

Instrukcja instalacji fillup PremiumDB

Instalacja aplikacji po raz pierwszy

1. Przygotowanie środowiska zgodnie z punktem Wymagania sprzętowe, na którym zostanie zainstalowany produkt.

2. Jeżeli planujesz zainstalować aplikację na systemie Windows:

1. Zainstaluj Docker for Windows https://www.docker.com/products/docker-desktop/  (minimalna wersja 4.17.0)
2. Zainstaluj program WSL2 - Windows Subsystem for Linux – udostępniający zintegrowane środowisko systemu GNU/Linux. Więcej informacji pod linkiem: https://learn.microsoft.com/en-us/windows/wsl/install. Po instalacji sprawdź jaką posiadasz dystrybucję Linuxa (dowolna) oraz wersję WSL (wymagana w wersji 2):  

Dalszą części instalacji aplikacji serwerowej fillup PremiumDB należy przeprowadzić z poziomu Linux - wywołanie komendy wsl - która uruchomi nam domyślną powłokę Linux i zaloguje na domyślnego użytkownika:

3. Zainstaluj środowisko uruchomienia kontenerów: docker w wersji co najmniej 20.10.16 (sprawdzenie wersji po instalacji: docker --version) oraz docker compose w wersji co najmniej 2.15.1 (sprawdzenie wersji po instalacji: docker compose version). Więcej informacji na stronie dostawcy rozwiązania: https://docs.docker.com/get-docker/ .  

4. Przygotuj katalogi, do których aplikacja serwerowa będzie zapisywać dane. Katalogi powinny być dostępne dla każdego użytkownika systemu:

1. Katalog zapisu logów aplikacji.
   
   Przykład:
   sudo mkdir -p /mnt/premium/logs
   sudo chmod 777 -R /mnt/premium/logs
   
   
2. Katalog bazy danych fillup - do tego katalogu baza będzie zapisywać dane formularzy i wszystkich innych danych związanych z poprawnym działaniem aplikacji. Usunięcie danych z katalogu, ingerencja w pliki katalogu, utrata powiązania z katalogiem może skutkować trwałą utratą danych Premium DB.
   
   Przykład:
   sudo mkdir -p /mnt/premium/premiumdb/data
   sudo chmod 777 -R /mnt/premium/premiumdb/data
   
   
3. Katalog zapisu kopii zapasowych - w tym katalogu będą wykonywane kopie zapasowe bazy danych
   
   Przykład:
   sudo mkdir -p /mnt/premium/premiumdb/backup
   sudo chmod 777 -R /mnt/premium/premiumdb/backup
   
   

5. Pobierz najnowszą wersję aplikacji serwerowej PremiumDB - link dostarczony przez firmę e-file.

6. Utwórz katalog, z którego zostanie uruchomiona aplikacja serwerowa. Rozpakuj aplikację do utworzonego katalogu poleceniem z konsoli Linux: unzip efile-fillup-premium… . Rozpakowanie aplikacji poza systemem Linux w Windowsie lub kopiowanie plików może się wiązać z brakiem nadania odpowiednich praw plikom aplikacji, jak np.: prawa do wykonywania skryptu premium.sh.

7. Będąc w katalogu aplikacji skonfiguruj zmienne środowiskowe znajdujące się w pliku: premium.env. Przy definiowaniu wartości nie używaj znaku spacji, wartość powinna być przypisana bezpośrednio po znaku “=”:

• Ustawienie klucza aplikacji (Laravel APP_KEY). Sposób wygenerowania klucza opisano w sekcji FAQ:
  
  PREMIUM_APP_KEY=
  
  
• Dane użytkownika i hasło do zasobów e-file. W celu otrzymania dostępu proszę o kontakt z działem obsługi klienta biznesowego firmy e-file:
  
  PREMIUM_REGISTRY_USERNAME=
  PREMIUM_REGISTRY_PASSWORD=
  
  
• Ścieżkę do logów aplikacji - katalog utworzony w punkcie 4.a :
  
  PREMIUM_LOGS_PATH=
  
  
•  Adres serwera, pod którym udostępniona zostanie aplikacja serwerowa fillup Premium DB wewnątrz firmy klienta (jeżeli wersja będzie udostępniona pod domeną z certyfikatem SSL należy dodatkowo ustawić parametr PREMIUM_FORCE_HTTPS na wartość true
  
  PREMIUM_PREMIUMDB_APP_URL=
  
  Przykład:
  PREMIUM_PREMIUMDB_APP_URL=https://premiumdb.domenafirmy.pl:8030
  
  
• Podaj hasło do bazy danych. Baza danych zostanie utworzona przy pierwszym uruchomieniu aplikacji z podanym hasłem - prosimy o zapamiętanie hasła w bezpiecznym miejscu w firmie. Hasło powinno zawierać znaki alfanumeryczne bez znaków specjalnych #,*'"()|/><$*:
  
  PREMIUM_PREMIUMDB_DB_PASSWORD=
  
  Stopień komplikacji i długość hasła nie jest limitowana przez aplikację tylko przez system operacyjny. Zalecamy stosowanie bezpiecznych haseł tj dłuższych jak 12 znaków.
  
  
• Skonfiguruj katalogi: przechowywania plików bazy danych fillup, kopii zapasowych (odpowiednie katalogi utworzone w punkcie 4.b oraz 4.c - podajemy pełne ścieżki, ważna jest wielkość liter):
  
  PREMIUM_PREMIUMDB_DATA_PATH=
  PREMIUM_PREMIUMDB_DATA_BACKUP_PATH=

8. Dodaj usera, na którym pracujesz do grupy docker:

sudo usermod -aG docker ${USER}

oraz dodaj katalog /.docker

mkdir /.docker
chmod 777 /.docker

9. Uruchom aplikację serwerową PremiumDB: ./premium.sh start

10. Sprawdź lokalnie czy system jest dostępny: curl http://localhost:8030/api/ping - system powinien zwrócić status 200 oraz tekst "OK" i numerem wersji.

11. Sprawdź czy katalogi persystencji danych nie są puste, wskazane pod zmiennymi:

PREMIUM_PREMIUMDB_DATA_PATH.  

12. Przed udostępnieniem serwera dla aplikacji desktopowej wskazane jest postawienie serwera proxy do aplikacji fillup PremiumDB, tak aby serwer wykorzystywał protokół https (odpowiednio skonfigurowane certyfikaty domenowe firmy) i był dostępny tylko wewnątrz firmy. Lokalnie (na serwerze) PremiumDB jest dostępny pod url: http://localhost:8030 . Pod tym adresem udostępniamy także panel administracyjny - patrz rozdział Panel Administracyjny.

Aktualizacja aplikacji

Aktualizację aplikacji serwerowej PremiumDB można wykonać ręcznie lub przy pomocy dostarczonych skryptów. Uwaga! Nie należy wgrywać starszej wersji od aktualnie uruchomionej - może to spowodować niestabilność aplikacji serwerowej.

Aktualizacja za pomocą skryptów:

1. Pobierz najnowszą wersję skryptu instalacyjnego dostarczonego przez firmę e-file. Rozpakuj paczkę instalacyjną i uruchom skrypt: ./instalator_premium.sh.

Aktualizacja ręczna:

1. Pobierz najnowszą wersję aplikacji serwerowej PremiumDB - link dostarczony przez firmę e-file.
2. Sprawdź uruchomioną wersję aplikacji serwerowej fillup PremiumDB z panelu administracyjnego (patrz Panel administracyjny). Jeżeli pobrana wersja jest nowsza niż aktualnie uruchomiona, można przejść do kolejnego kroku aktualizacji.
3. Zatrzymaj aktualną wersję aplikacji serwerowej Premium: ./premium.sh stop
4. Utwórz katalog, z którego zostanie uruchomiona nowa wersja aplikacji PremiumDB, następnie rozpakuj aplikację do utworzonego katalogu poleceniem z konsoli Linux np.: unzip efile-fillup-premium… . Rozpakowanie aplikacji poza systemem Linux w Windowsie lub kopiowanie plików może się wiązać z brakiem nadania odpowiednich praw plikom aplikacji, jak np.: prawa do wykonywania skryptu premium.sh.
5. Przenieś konfigurację zmiennych środowiskowych z wcześniejszej wersji aplikacji (konfiguracja znajdująca się w pliku: config/premium.env). Upewnij się się, że wszystkie zmienne środowiskowe w pliku są poprawnie skonfigurowane.
6. Uruchom aplikację serwerową PremiumDB: ./premium.sh start
7. Sprawdź lokalnie czy system jest dostępny:
   curl http://localhost:8030/api/ping
   System powinien zwrócić status 200 oraz tekst “OK” z numerem wersji .  

Panel administracyjny

Dla celów utrzymania i kontroli działania aplikacji serwerowej PremiumDB dostarczono panel administracyjny. Panel dostępny jest pod linkiem:

• http://localhost:8030/web/home  - z poziomu serwera
• https://[adres_serwera]/web/home - po odpowiednim skonfigurowaniu sieci przez administratora firmy i przekierowaniu ruchu z serwera aplikacji PremiumDB do sieci firmowej.  

W panelu administracyjnym możemy wyróżnić sekcję raportów formularzy oraz sekcję bazy danych.

Raporty formularzy są niezależną listą od profili wystawionych formularzy w bazie z możliwością filtrowania po różnych kolumnach takich jak np. data czy profil w bazie.  

Sekcja baza danych umożliwia zarządzanie kopiami zapasowymi:  

Zaimplementowany mechanizm umożliwia zarządzanie sporządzaniem kopii oraz automatycznym czyszczeniem powstałych archiwów baz.

Pliki kopii baz przechowywane są w katalogu zdefiniowanym w sekcji
PREMIUM_PREMIUMDB_DATA_BACKUP_PATH=

Konfiguracja klienta fillup Desktop

Aby połączyć się z serwerem backendowym PremiumDB z systemu fillup Desktop należy utworzyć nowe połączenie do bazy danych (dostępne z poziomu aplikacji Desktop: Ustawienia->Dane aplikacji->Dodaj połączenie do bazy danych).  

W polu "Ścieżka do serwera bazy Premium" należy podać adres serwera, pod którym administratorzy firmy uruchomili aplikację serwerową fillup PremiumDB.

Po skonfigurowaniu połączenia możemy już przełączyć się na bazę Premium jak na rysunku poniżej wybierając "Przełącz na tę bazę".  

Następnie logujemy się na domyślnie założonego użytkownika "Administrator" z hasłem "admin". Po pierwszym logowaniu zaleca się zmianę hasła użytkownika z poziomu aplikacji fillup Desktop.  

Jeżeli logowanie przebiegnie pomyślnie przywita nas ekran powitalny.

Tabela odpowiedzialności

(1) dotyczy tylko instalacji na serwerze z systemem Windows

FAQ 

• Jak uruchomić aplikację serwerową PremiumDB?
  Przejdź do katalogu aplikacji i wpisz w linii komend polecenie: ./premium.sh start
• Jak zatrzymać aplikację serwerową PremiumDB?
  Przejdź do katalogu aplikacji i wpisz w linii komend polecenie: ./premium.sh stop
• Jak zrestartować aplikację serwerową PremiumDB?
  Przejdź do katalogu aplikacji i wpisz w linii komend polecenie: ./premium.sh restart
• Jak sprawdzić czy aplikacja serwerowa jest uruchomiona?
  Wpisz w linii komend polecenie: docker ps. Na liście kontenerów powinny się pojawić kontenery:
  - premium_premiumdb_nginx,
  - premium_premiumdb_php,
  - premium_premiumdb_php_schedule,
  - premium_premiumdb_db.

Wszystkie powinny mieć status: “healthy” jak na obrazku poniżej:

Jeżeli kontenery mają status “healthy”, sprawdź czy serwer odpowiada:
curl http://localhost:8030/api/ping - serwer powinien zwrócić status 200 oraz tekst “OK” z numerem wersji.  

• Jak wygenerować klucz PREMIUM_APP_KEY (Laravel APP_KEY)?

Generowanie klucza na publicznej stronie WWW:
https://generate-random.org/laravel-key-generator. 

Generowania klucza z poziomu aplikacji:
- uruchom aplikację Premium bez ustawienia klucza PREMIUM_APP_KEY (wszystkie pozostałe zmienne w pliku premium.env muszą być już poprawnie skonfigurowane)
- uruchom polecenie: docker exec -i premium_premiumdb_php php artisan key:generate --show
- skopiuj klucz i wprowadź zmiany w pliku konfiguracyjnym premium.env
- zatrzymaj i uruchom ponownie aplikację PremiumDB

Przykład poprawnej wartości klucza:
base64:MWR0ZDJzZjk4cjd0cmFmN2Foa2YzbXBpNGVvdnVxOGE=  

•  Wystąpił błąd The container name is already in use by … - co zrobić?
  
  Error response from daemon: Conflict. The container name "/premium_premiumdb_db" is already in use by container "e8ef4ef0605478353ca24f27c58639d4f9a4461734556414484f6f02f55dd149". You have to remove (or rename) that container to be able to reuse that name.
  
  Oznacza, że została już zainstalowana wcześniejsza wersja aplikacji serwerowej. Sprawdzenie zainstalowanej wersji wykonujemy poleceniem: docker container ls -a

Starą wersję aplikacji można usunąć poprzez uruchomienie polecenia:

- ./premium.sh remove
- lub poprzez ręczne usuwanie kontenerów poleceniem docker rm:

• docker rm premium_premiumdb_php -f
• docker rm premium_premiumdb_php_schedule -f
• docker rm premium_premiumdb_nginx -f
• docker rm premium_premiumdb_db -f

• Jak sprawdzić wersję aplikacji serwerowej PremiumDB?
  Uruchom panel administracyjny aplikacji -patrz punkt Panel administracyjny. Szczegółowe dane znajdują się na głównym ekranie panelu.
• Po restarcie Windows-a lub Linuxa nie działa aplikacja serwerowa fillup PremiumDB?
  Należy ponownie uruchomić aplikację: ./premium.sh start
  Jeżeli aplikacja została uruchomiona w środowisku Windows poprzez WSL, w usługach autostartu należy dodać skrypt restartujący premium: wsl sh -c "cd /katalogpremium && ./premium.sh restart" (gdzie /katalog premium jest katalogiem w systemie Linux w jakim znajduje się aplikacja premium)