Wdrożenie nAxiom w Openshift

Wersja nAxiom 1.15.0.0, data publikacji: 2025-08-13

Przeczytasz w 24 min.

• Wprowadzenie
• Wymagania
• Przygotowanie do wdrożenia
  • Utworzenie projektu Openshift
  • MS SQL Server
  • RabbitMQ
  • Nginx
  • Dodatkowe kroki konfiguracji
• Wdrożenie serwisu tenant-api i aplikacji tenant-admin
• Tworzenie pierwszego tenanta
• Wdrożenie pozostałych serwisów nAxiom

Wprowadzenie

W tym artykule opisano kroki procedury wdrożenia witryny nAxiom z użyciem Red Hat OpenShift Container Platform. W procedurze używane są szablony plików konfiguracyjnych z ustawieniami domyślnymi dostarczane w pliku archiwum.

Wymagania

• Plik archiwum z obrazami nAxiom
• Plik archiwum ze strukturą katalogów wdrożenia i szablonami plików konfiguracyjnych
• Przekazane osobno hasła dla systemowych kont użytkowników:
  • tenentsadmin
  • admin
  • consultant
• Działająca platforma Openshift/OKD
• Dostępne w terminalu narzędzia oc, helm i keytool
• Dostępne prywatne repozytorium obrazów kontenerów
• Przygotowane certyfikaty i klucze prywatne w formacie PEM:
  • internal-ca.crt
  • internal.crt: musi mieć podane alternatywne nazwy podmiotu:
    • tenant-api-service.<naxiom-project>
    • tenant-admin-service.<naxiom-project>
    • *.auth-service.<naxiom-project>
    • auth-service.<naxiom-project>
    • api-service.<naxiom-project>
    • front-service.<naxiom-project>
    • admin-service.<naxiom-project>
    • workflow-service.<naxiom-project>
    • public-api-service.<naxiom-project>
    • task-service-service.<naxiom-project>
    • syncfusion-api-service.<naxiom-project>
    • mobile-api-service.<naxiom-project>
    • documentation-service.<naxiom-project>
    • telerik-reports-service.<naxiom-project>
    • rabbitmq
  • internal.key
  • proxy-ca.crt
  • proxy.crt: musi mieć podane alternatywne nazwy podmiotu:
    • <naxiom-domain>
    • *.<naxiom-domain>
  • proxy.key

  Ciąg <naxiom-project> oznacza nazwę projektu, który ma zostać utworzony dla wdrożenia nAxiom w środowisku Openshift, a <naxiom-domain> to nazwa domeny, pod którą wdrożenie będzie udostępniane.

Przygotowanie do wdrożenia

1. Wczytaj dostarczone obrazy do prywatnego repozytorium obrazów kontenerów.

2. Rozpakuj dostarczone archiwum ze strukturą katalogów projektu i szablonami plików konfiguracyjnych do osobnego katalogu. Poniżej pokazano strukturę katalogów wdrożenia oraz lokalizację plików konfiguracyjnych:

     ├───certs
     │       internal-ca.crt
     │       internal.crt
     │       internal.key
     │       proxy-ca.crt
     │       proxy.crt
     │       proxy.key
     ├───configs
     │   ├───auth
     │   │       nlog-custom.config*
     │   ├───admin
     │   │       config-custom.json*
     │   ├───api
     │   │       nlog-custom.config*
     │   ├───documentation
     │   │       appsettings-custom.json*
     │   ├───front
     │   │       config-custom.json*
     │   ├───mobile-api
     │   │       nlog-custom.config*
     │   ├───nginx
     │   │       naxiom-buffers.conf
     │   │       naxiom-certificate.conf
     │   │       naxiom-headers.conf
     │   │       naxiom-openshift.conf
     │   ├───public-api
     │   │       nlog-custom.config*
     │   ├───syncfusion-api
     │   │       appsettings-custom.json*
     │   ├───task-service
     │   │       nlog-custom.config*
     │   ├───telerik-reports
     │   │       nlog-custom.config*
     │   ├───tenant-admin
     │   │       config-custom.json*
     │   ├───tenant-api
     │   │       nlog-custom.config*
     │   └───workflow
     │           config-custom.json*
     ├───deployments
     │       admin-deployment.yaml
     │       api-deployment.yaml
     │       auth-deployment.yaml
     │       documentation-deployment.yaml
     │       front-deployment.yaml
     │       mobile-api-deployment.yaml
     │       nginx-deployment.yaml
     │       public-api-deployment.yaml
     │       syncfusion-api-deployment.yaml
     │       task-service-deployment.yaml
     │       telerik-reports-deployment.yaml
     │       tenant-admin-deployment.yaml
     │       tenant-api-deployment.yaml
     │       workflow-deployment.yaml
     ├───routes
     │       naxiom-local.yaml
     │       rabbitmq-naxiom-local.yaml
     │       wildcard-naxiom-local.yaml
     ├───scc
     │       scc.yaml
     ├───scripts
     │   ├───syncfusion-api
     │   │       custom-entrypoint.sh*
     │   └───telerik-reports
     │           custom-entrypoint.sh*
     ├───secrets
     │   ├───api
     │   │       appsettings-custom.json
     │   ├───auth
     │   │       appsettings-custom.json
     │   ├───mobile-api
     │   │       appsettings-custom.json
     │   ├───public-api
     │   │       appsettings-custom.json
     │   ├───task-service
     │   │       appsettings-custom.json
     │   ├───telerik-reports
     │   │       appsettings-custom.json
     │   └───tenant-api
     │           appsettings-custom.json
     ├───services
     │       admin-service.yaml
     │       api-service.yaml
     │       auth-service.yaml
     │       documentation-service.yaml
     │       front-service.yaml
     │       mobile-api-service.yaml
     │       mssql-service.yaml**
     │       nginx-service.yaml
     │       public-api-service.yaml
     │       syncfusion-api-service.yaml
     │       task-service-service.yaml
     │       telerik-reports-service.yaml
     │       tenant-admin-service.yaml
     │       tenant-api-service.yaml
     │       workflow-service.yaml
     ├───statefulsets
     │       mssql.yaml**
     └───values
          rabbitmq-values.yaml
   

   * Pliki opcjonalne z niestandardowymi ustawieniami konfiguracyjnymi.
   ** Pliki wymagane tylko wtedy, gdy SQL Server jest również wdrażany w środowisku Openshift.

Utworzenie projektu Openshift

1. Uruchom terminal (wymagane zalogowanie do Openshift) i utwórz nowy projekt:

   oc new-project <naxiom-project> --display-name="nAxiom Production"
               --description="Production environment of nAxiom low-code platform."
   

2. Wpisz polecenie (wymagane uprawnienia administratora):

   oc edit scc anyuid
   

   znajdź sekcję runAsUser i dodaj następujące linie:

     uidRangeMax: 1000709999
     uidRangeMin: 0
   

3. Wczytaj obiekty SecurityContextConstraints. W tym celu uruchom następujące polecenia, aby wczytać plik scc.yaml do platformy OpenShift (wymagane uprawnienia administratora):

   oc create -f ./scc/scc.yaml -n <naxiom-project>
   oc adm policy add-scc-to-user run-as-root -z default -n <naxiom-project>
   

4. Utwórz obiekty secret dla certyfikatów. Trzeba to zrobić z terminala, ponieważ interfejs przeglądarkowy nie ma takiej opcji. Uruchom następujące polecenia:

   oc create secret generic cert-naxiom-internal --from-file=tls.crt=./certs/internal.crt
    --from-file=tls.key=./certs/internal.key
    --from-file=ca.crt=./certs/internal-ca.crt
    -n <naxiom-project>
   oc create secret generic cert-naxiom-proxy --from-file=tls.crt=./certs/proxy.crt
    --from-file=tls.key=./certs/proxy.key
    --from-file=ca.crt=./certs/proxy-ca.crt
    -n <naxiom-project>
   

MS SQL Server

Platforma nAxiom korzysta z baz danych na serwerze Microsoft SQL Server (w plikach konfiguracyjnych używana jest wersja 2019, w ogólności wspierane są wersje 2016 i nowsze). Dla wdrożenia w środowisku Openshift może to być serwer baz danych hostowany osobno. W takim przypadku można pominąć poniższe kroki, z wyjątkiem ostatniego, w którym opisano tworzenie użytkownika bazy danych. Wymagane będzie jedynie podanie parametrów połączenia (connection string) z bazą danych tenantów w pliku appsettings-custom.json dla serwisu tenant-api (secrets/tenant-api).

1. Utwórz obiekt service dla SQL Server:

   oc apply -f ./services/mssql-service.yaml -n <naxiom-project>
   

2. Utwórz obiekt secret dla hasła użytkownika sa:

   oc create secret generic "mssql" --from-literal=MSSQL_SA_PASSWORD="<sa-user-password>" -n <naxiom-project>
   

3. Utwórz obiekt statefulset dla SQL Server:

   Przed uruchomieniem polecenia można zmienić wartość zmiennej środowiskowej MSSQL_PID z Express na klucz produktu, jeśli dana organizacja dysponuje pełną wersją:

   - name: MSSQL_PID
     value: "Express"
   

   Pełny opis tych zmiennych znajduje się w witrynie Microsoft Learn.

   oc apply -f ./statefulsets/mssql.yaml -n <naxiom-project>
   

4. Po wdrożeniu kontenera SQL Server należy utworzyć login (z poziomem uprawnień sysadmin albo co najmniej dbcreator i securityadmin), bazę danych tenantów, powiązane z loginem konto użytkownika oraz schemat ta, którego właścicielem będzie utworzony użytkownik bazy danych. Nazwę bazy danych oraz identyfikator użytkownika i hasło należy podać w konfiguracji połączenia w pliku appsettings-custom.json dla serwisu tenant-api:

   "ConnectionStrings": {
    "SQLConnectionString": "Server=mssql,1443;Initial Catalog=nAxiom_tenantsAdmin; User Id=nAxiom; Password=p@ssw0rd; Encrypt=false;"
     }
   

   1. Otwórz wiersz poleceń serwera SQL Server:

      oc exec -it mssql-0 -- /opt/mssql-tools18/bin/sqlcmd -S localhost -U sa -No
      

      Podaj hasło użytkownika sa, a następnie wpisuj poniższe instrukcje SQL; każdą linię zatwierdź klawiszem Enter.

   2. Utwórz login i przypisz mu wymagane role:

      CREATE LOGIN nAxiom WITH PASSWORD='p@ssw0rd'
      ALTER SERVER ROLE securityadmin ADD MEMBER nAxiom
      ALTER SERVER ROLE dbcreator ADD MEMBER nAxiom
      GO
      

   3. Utwórz bazę danych:

      CREATE DATABASE nAxiom_tenantsAdmin
      GO
      

   4. Przełącz kontekst bazy danych:

      USE nAxiom_tenantsAdmin
      GO
      

   5. Utwórz użytkownika bazy danych i przypisz mu odpowiednie role:

      CREATE USER nAxiom FOR LOGIN nAxiom WITH DEFAULT_SCHEMA='dbo'
      ALTER ROLE db_datareader ADD MEMBER nAxiom
      ALTER ROLE db_datawriter ADD MEMBER nAxiom
      ALTER ROLE db_ddladmin ADD MEMBER nAxiom
      GO
      

   6. Utwórz schemat i przypisz utworzonego użytkownika jako jego właściciela:

      CREATE SCHEMA ta AUTHORIZATION nAxiom
      GO
      

   7. Zamknij wiersz poleceń serwera SQL Server:

      EXIT
      

RabbitMQ

nAxiom wymaga do działania brokera RabbitMQ (wersja 4.1.3), może to być broker wdrożony w środowisku nAxiom według poniższych kroków lub broker działający na zewnątrz. W tym drugim przypadku można pominąć poniższe kroki, z wyjątkiem ostatniego. Oprócz hasła użytkownika, w plikach appsettings-custom.json należy wtedy także podać nazwę hosta RabbitMQ, jak w przykładzie poniżej:

  "AppConfiguration": {
    "MessageBrokerConfiguration": {
      "HostName": "amqp://rabbitmq:5672",
      "UserName": "rabbit",
      "Password": "P@sw0rd",
      "UseSsl": true,
      "NaxQueuePrefix": "nax",
    }
  }

1. Utwórz magazyn certyfikatów dla RabbitMQ na podstawie certyfikatu PEM:

   keytool -import -noprompt -file ./certs/internal.crt -alias internal -keystore truststore.p12 -srcstoretype PKCS12
   

   Po uruchomieniu polecenia zostanie wyświetlony monit o ustawienie hasła do magazynu. Zanotuj je, aby w kolejnym kroku utworzyć obiekt secret z tym hasłem.

2. Utwórz obiekt secret z certyfikatem TLS RabbitMQ, kluczem prywatnym, certyfikatem CA i magazynem certyfikatów:

   oc create secret generic "tls-rabbitmq" --from-file=truststore.p12 --from-file=internal.crt --from-file=internal.key --from-file=ca.crt=internal-ca.crt -n <naxiom-project>
   

3. Utwórz obiekt secret z hasłem do magazynu certyfikatów TLS RabbitMQ:

   oc create secret generic "tls-rabbitmq-pass" --from-literal=password="<truststore-password>" -n <naxiom-project>
   

4. Utwórz obiekt secret z hasłem użytkownika do RabbitMQ:

   oc create secret generic "rabbitmq-pass" --from-literal=rabbitmq-password="<rabbit-user-password>" -n <naxiom-project>
   

5. Dodaj repozytorium Bitnami do programu Helm:

   helm repo add bitnami https://charts.bitnami.com/bitnami
   helm repo update
   

6. Zainstaluj RabbitMQ przy użyciu programu Helm:

   Przed instalacją sprawdź dodatkowe ustawienia konfiguracyjne w pliku values/rabbitmq-values.yaml. Szczegółowy opis tych parametrów można znaleźć w dokumentacji biblioteki bitnami: https://github.com/bitnami/charts/blob/rabbitmq/16.0.13/bitnami/rabbitmq/README.md.

   helm install -n naxiom rabbitmq bitnami/rabbitmq --version 16.0.13 -f rabbitmq-values.yaml
   

7. Wpisz hasło użytkownika do RabbitMQ w kluczu MessageBrokerConfiguration we wszystkich plikach appsettings-custom.json znajdujących się w podkatalogach katalogu secrets.

Nginx

1. Utwórz obiekty configmaps dla usługi nginx.

   Przed uruchomieniem polecenia zaktualizuj nazwę projektu w dostarczonym pliku naxiom-openshift.conf; w tym celu wyszukaj w pliku wszystkie wystąpienia ciągu naxiom.svc.cluster.local i zamień na <naxiom-project>.svc.cluster.local.

   oc create configmap nginx-naxiom --from-file=naxiom.template.conf=./configs/nginx/naxiom-openshift.conf -n <naxiom-project>
   oc create configmap nginx-naxiom-buffers --from-file=naxiom-buffers.conf=./configs/nginx/naxiom-buffers.conf -n <naxiom-project>
   oc create configmap nginx-naxiom-certificate --from-file=naxiom-certificate.conf=./nginx/configs/naxiom-certificate.conf -n <naxiom-project>
   oc create configmap nginx-naxiom-headers --from-file=naxiom-headers.conf=./configs/nginx/naxiom-headers.conf -n <naxiom-project>
   

2. Utwórz obiekt service dla Nginx:

   oc apply -f ./services/nginx-service.yaml -n <naxiom-project>
   

3. Utwórz obiekt deployment dla Nginx:

   Przed uruchomieniem polecenia ustaw prawidłową wartość zmiennej DOMAIN_NAME w pliku nginx-deployment.yaml:

   env:
    - name: DOMAIN_NAME
      value: <naxiom-domain>
   

   oc apply -f ./deployments/nginx-deployment.yaml -n <naxiom-project>
   

Dodatkowe kroki konfiguracji

1. Utwórz konfiguracje poziomu logowania dla wszystkich serwisów nAxiom, które używają biblioteki NLog (patrz struktura wdrożenia):

   oc create secret generic <service-name>-nlog --from-file=nlog-custom.config=./configs/<service-name>/nlog-custom.config -n <naxiom-project>
   

2. Utwórz obiekty secret dla plików niestandardowych ustawień konfiguracyjnych:

   Przed uruchomieniem polecenia dla serwisu tenant-api w pliku appsettings-custom.json dla tego serwisu tenant-api wpisz odpowiednie wartości w konfiguracji połączenia z bazą danych:

   "ConnectionStrings": {
       "SQLConnectionString": "Server=mssql,1443;Initial Catalog=nAxiom_tenantsAdmin; User Id=nAxiom; Password=p@ssw0rd; Encrypt=false;"
     }
   

   oc create secret generic api-config --from-file=appsettings-custom.json=./secrets/api/appsettings-custom.json -n <naxiom-project>
   oc create secret generic auth-config --from-file=appsettings-custom.json=./secrets/auth/appsettings-custom.json -n <naxiom-project>
   oc create secret generic mobile-api-config --from-file=appsettings-custom.json=./secrets/mobile-api/appsettings-custom.json -n <naxiom-project>
   oc create secret generic public-api-config --from-file=appsettings-custom.json=./secrets/public-api/appsettings-custom.json -n <naxiom-project>
   oc create secret generic task-service-config --from-file=appsettings-custom.json=./secrets/task-service/appsettings-custom.json -n <naxiom-project>
   oc create secret generic telerik-reports-config --from-file=appsettings-custom.json=./secrets/telerik-reports/appsettings-custom.json -n <naxiom-project>
   oc create secret generic tenant-api-config --from-file=appsettings-custom.json=./secrets/tenant-api/appsettings-custom.json -n <naxiom-project>
   

3. Utwórz obiekty route, które będą odpowiadać za kierowanie ruchu do serwisu Nginx, jeden dla domeny i jeden z obsługą poddomen (wymaganą do obsługi wielu tenantów) oraz osobny dla brokera RabbitMQ:

   Przed uruchomieniem poleceń zmień nazwę hosta w plikach YAML w folderze routes.

   oc apply -f ./routes/naxiom-local.yaml -n <naxiom-project>
   oc apply -f ./routes/wildcard-naxiom-local.yaml -n <naxiom-project>
   oc apply -f ./routes/rabbitmq-naxiom-local.yaml -n <naxiom-project>
   

4. Sprawdź, czy domena ustawiona w konfiguracji obiektu route jest dostępna w przeglądarce. Błąd 502 jak na ilustracji poniżej oznacza, że serwis Nginx działa. Wystąpienie innego błędu będzie oznaczało, że ruch nie dociera do serwisu Nginx.

   

Wdrożenie serwisu tenant-api i aplikacji tenant-admin

1. We wszystkich plikach w katalogu deployments zmień:

   • adres i port repozytorium obrazów oraz ścieżkę do obrazu i tag:

   image: image-registry.local:5000/naxiom/<service-name>:<image-tag>
   

   • nazwę przestrzeni nazw:

   - name: IMG_DEPLOY_NAMESPACE
   value: <naxiom-project>
   

   • nazwę domeny:

   - name: IMG_DOMAIN_NAME
   value: <naxiom-domain>
   

   Te zmiany dotyczą poleceń wykonywanych w kolejnym kroku oraz w pierwszym kroku rozdziału Wdrożenie pozostałych serwisów nAxiom .

2. Utwórz obiekty service i deployment dla serwisów tenant-api i tenant-admin.

   oc apply -f ./services/tenant-api-service.yaml -n <naxiom-project>
   oc apply -f ./services/tenant-admin-service.yaml -n <naxiom-project>
   oc apply -f ./deployments/tenant-api-deployment.yaml -n <naxiom-project>
   oc apply -f ./deployments/tenant-admin-deployment.yaml -n <naxiom-project>
   

3. Aby sprawdzić, czy konfiguracja w pliku tenant-api-deployment jest poprawna, użyj polecenia:

   oc logs tenant-api-deployment-\<hash\> -n <naxiom-project>
   

   gdzie <hash> to ciąg znaków dodawany przez Openshift do nazwy poda. Jeśli wynik polecenia zawiera wpis:

   ...Time of the file access "/tmp/certificate.key" changed, removing from disk.
   

   serwis tenant-api działa prawidłowo.

4. Wpisz w przeglądarce adres https://<naxiom-domain>/tenatnsadmin. Zostanie wyświetlona strona logowania do serwisu tenant-admin:

   

   Zaloguj się i utwórz pierwszego tenanta.

Tworzenie pierwszego tenanta

Zaloguj się do serwisu tenants-admin, używając loginu tenantsadmin i przekazanego osobno hasła (patrz Wymagania ). Po zalogowaniu zostanie wyświetlona strona aplikacji z menu po lewej stronie i pustą listą tenantów w części głównej. Aplikację opisano w osobnej dokumentacji. W celu utworzenia pierwszego tenanta należy kliknąć przycisk Add new tenant i podać dane w uruchomionym kreatorze.

• Code: kod tenanta; tylko znaki alfanumeryczne, znaki podkreślenia (_) i myślniki (-); kodu tenanta określonego w tym kroku nie można zmienić.
• Database:
  • New database: dla tworzonego tenanta zostanie utworzona nowa baza danych o podanych parametrach.
  • Existing database: tenant zostanie powiązany z istniejącą bazą danych o podanych parametrach.
• Database connection definition:
  • Parameters: (domyślnie) podaj podstawowe parametry połączenia z bazą danych w polach:
    • Server name: adres serwera SQL Server.
    • Login: login do bazy danych; jeśli nie istnieje zostanie utworzony, zaleca się podanie loginu utworzonego z mocnym hasłem specjalnie dla administratora tenantów.
    • Password: hasło do bazy danych (dostępny jest przycisk generowania mocnego hasła).
    • Database: nazwa bazy danych pierwszego tenanta.
  • Connection string: podaj konfigurację połączenia z bazą danych w polu tekstowym Database connection string; ta opcja pozwala użyć dodatkowych parametrów, których nie ma w opcji Parameters.

Kliknij przycisk Create, aby utworzyć pierwszego tenanta w środowisku nAxiom. Wymagane jest podwójne potwierdzenie. Nowy tenant jest tworzony jako nieaktywny. Po jego utworzeniu należy go aktywować, włączając przełącznik. Dodatkowo konieczne jest podanie wartości w polu Customer Name na karcie Main. Jest to ciąg znaków, na podstawie którego jest identyfikowana licencja danego tenanta (podczas pierwszego logowania konsultant z organizacji tego tenanta musi zaimportować plik licencji zgodny z wartością w polu Customer Name).

Należy zauważyć, że wartość podana w polu Code zostaje domyślnie użyta jako przedrostek adresu URL do nAxiom dla danego tenanta. Jeśli tenant ma używać bazowego adresu środowiska nAxiom bez przedrostka, należy wyczyścić pole Url prefix na karcie Configuration.

Wdrożenie pozostałych serwisów nAxiom

1. Utwórz obiekty service i deployment dla pozostałych serwisów nAxiom:
   • admin
   • api
   • auth
   • documentation
   • front
   • mobile-api
   • public-api
   • syncfusion-api
   • task-service
   • telerik-reports
   • workflow

   Poniżej pokazano przykład dla serwisu api:

   oc apply -f ./services/api-service.yaml -n <naxiom-project>
   oc apply -f ./deployments/api-deployment.yaml -n <naxiom-project>
   

   Zależnie od liczby dodanych tenantów uruchomienie serwisu api może potrwać kilka minut. Podobnie jak w przypadku serwisu tenant-api, znakiem powodzenie będzie obecność wpisu w logu odpowiedniego poda:

   ...Time of the file access "/tmp/certificate.key" changed, removing from disk.
   

2. Następnie sprawdź, czy pod adresem https://<naxiom-domain> jest dostępna witryna nAxiom. Jeśli cały proces przebiegł poprawnie, zostanie wyświetlona strona logowania.

   

   Zaloguj się na jedno z predefiniowanych kont:

Administrator

login: admin, hasło: przekazane osobno, patrz Wymagania

Korzystając z tego konta można logować się do aplikacji FrontSPA (front office) i zarządzać użytkownikami, w tym nadawać im uprawnienia z obszaru zarządzania użytkownikami.

Konsultant

login: consultant, przekazane osobno, patrz Wymagania

Konsultant loguje się do aplikacji AdminSPA (back office), w której buduje aplikacje biznesowe. Konsultant może także wyznaczać innych konsultantów, to jest przyznawać użytkownikom uprawnienia z obszaru globalnych uprawnień aplikacji.

Na tym kończy się proces wdrożenia nAxiom w środowisku Openshift.

×