Konfiguracja appsettings.json¶

Plik appsettings.json to główny plik konfiguracyjny API systemu Navigator365. Znajdziesz go w katalogu aplikacji – podczas wdrożenia to właśnie ten plik (lub zmienne środowiskowe) decyduje o tym, jak system się zachowuje.

Jak ustawiać konfigurację w Docker¶

Navigator365 uruchamia się jako kontener Docker. Wartości z appsettings.json można nadpisać na dwa sposoby:

Zmienne środowiskowe (zalecane)¶

ASP.NET Core automatycznie mapuje zmienne środowiskowe na klucze konfiguracji. Separatorem sekcji jest podwójny podkreślnik __.

Przykład w docker-compose.yml:

services:
  navigator365-api:
    image: navigator365/api:latest
    environment:
      - AppSettings__License=TWOJ-KLUCZ-LICENCYJNY
      - AppSettings__FileStorePath=/data/files
      - JwtSettings__TokenSecret=bardzo-dlugi-losowy-ciag-znakow-min-32-znaki
      - JwtSettings__AccessTokenExpireMinutes=15
      - FrontEndHostAddress=https://navigator.twojafirma.pl
    volumes:
      - navigator_files:/data/files

Podpięcie pliku konfiguracyjnego¶

Alternatywnie można podpiąć własny plik appsettings.local.json jako wolumin:

volumes:
  - ./config/appsettings.local.json:/app/appsettings.local.json:ro

Plik appsettings.local.json jest wczytywany po głównym appsettings.json i nadpisuje jego wartości – wystarczy umieścić w nim tylko te klucze, które chcesz zmienić.

AppSettings¶

Podstawowe ustawienia aplikacji.

Klucz	Opis
`License`	Klucz licencyjny systemu Navigator365 otrzymany od dostawcy
`FileStorePath`	Ścieżka na dysku, w której przechowywane są załączniki i pliki przesyłane przez użytkowników. W Docker powinna wskazywać na katalog zamontowany jako wolumin, by dane przeżyły restart kontenera

Przykład (docker-compose):

environment:
  - AppSettings__License=TWOJ-KLUCZ
  - AppSettings__FileStorePath=/data/files
volumes:
  - navigator_files:/data/files

DockerSettings¶

Klucz	Wartość domyślna	Opis
`IsReady`	`true`	Informuje aplikację, że działa w środowisku Docker. Wpływa na działanie health-checka – endpoint `/health` zwraca status gotowości kontenera, który Docker i orkiestratory (np. Kubernetes) odpytują, by sprawdzić czy aplikacja jest gotowa do obsługi ruchu

JwtSettings¶

JWT (JSON Web Token) to mechanizm uwierzytelniania użytkowników. Po zalogowaniu system wydaje token, który przeglądarka przesyła przy każdym żądaniu. Aplikacja weryfikuje ten token za pomocą poniższych ustawień.

Klucz	Opis
`TokenSecret`	Tajny klucz używany do podpisywania tokenów. Musi być unikalny dla każdej instalacji – jeśli ktoś go pozna, może sfałszować tokeny i zalogować się jako dowolny użytkownik. Zalecana długość: minimum 32 znaki losowych znaków
`ValidateIssuer`	Czy sprawdzać, skąd pochodzi token. Ustaw `true` w środowisku produkcyjnym
`Issuer`	Adres serwera API – wpisywany w token jako informacja o wystawcy
`ValidateAudience`	Czy sprawdzać, dla kogo przeznaczony jest token. Ustaw `true` w środowisku produkcyjnym
`Audiences`	Lista adresów aplikacji obsługujących ten token
`AccessTokenExpireMinutes`	Jak długo ważny jest token logowania (w minutach). Po tym czasie użytkownik zostanie wylogowany, chyba że przeglądarka odświeży token automatycznie. Typowe wartości: 5–60 minut
`RefreshTokenExpireMinutes`	Jak długo użytkownik pozostaje zalogowany bez konieczności ponownego wpisywania hasła (w minutach). Domyślnie 43200 = 30 dni

Przykład (docker-compose):

environment:
  - JwtSettings__TokenSecret=zmien-mnie-na-dlugi-losowy-ciag-znakow-XyZ123
  - JwtSettings__ValidateIssuer=true
  - JwtSettings__Issuer=https://api.navigator.twojafirma.pl
  - JwtSettings__AccessTokenExpireMinutes=15

RefreshTokenCookie¶

Ustawienia ciasteczka HTTP, w którym przeglądarka przechowuje token odświeżający.

Klucz	Opis
`Path`	Ciasteczko będzie wysyłane tylko do żądań pod ten adres URL. Ogranicza ekspozycję tokenu – zostaw domyślną wartość `/api/auth`
`HttpOnly`	`true` = ciasteczko jest niewidoczne dla JavaScriptu (ochrona przed kradzieżą przez złośliwe skrypty). Zalecane: `true`
`Secure`	`true` = ciasteczko wysyłane tylko przez szyfrowane połączenie HTTPS. W produkcji zawsze `true`. Podczas testów lokalnych przez HTTP zmień na `false`
`SameSite`	Kontroluje, kiedy ciasteczko jest wysyłane przy żądaniach z innych stron. `Strict` = tylko z tej samej domeny (najlepsze bezpieczeństwo)

AuthenticationSettings¶

Wybór metody logowania użytkowników.

Klucz	Opis
`UseWindows`	`true` = użytkownicy logują się kontem domenowym Windows (Active Directory). Nie muszą wpisywać hasła – system rozpoznaje ich automatycznie na podstawie konta Windows. Wymaga środowiska domenowego
`UseIsam`	`true` = logowanie przez zewnętrzny system ISAM (IBM Security Access Manager). Używane w środowiskach korporacyjnych z centralnym zarządzaniem tożsamością
`PostLogoutRedirectUrl`	Opcjonalny adres URL, pod który frontend ma przekierować użytkownika po wylogowaniu. Przydaje się np. przy integracji z zewnętrznym SSO, stroną startową firmy albo osobnym portalem logowania. Zostaw puste, aby po wylogowaniu wracać do ekranu logowania Navigator365

Jeśli obie wartości to false, użytkownicy logują się standardowym loginem i hasłem wpisanym w systemie Navigator365.

Przykład (docker-compose):

environment:
  - AuthenticationSettings__UseWindows=false
  - AuthenticationSettings__UseIsam=false
  - AuthenticationSettings__PostLogoutRedirectUrl=https://login.twojafirma.pl/logout

SecuritySettings¶

Reguły bezpieczeństwa kont użytkowników.

Klucz	Opis
`RequireConfirmedEmail`	`true` = nowy użytkownik musi kliknąć link aktywacyjny wysłany na e-mail, zanim będzie mógł się zalogować
`RequireUniqueEmail`	`true` = nie można założyć dwóch kont z tym samym adresem e-mail (zalecane)
`MaxFailedAccessAttempts`	Po ilu nieudanych próbach logowania konto zostanie czasowo zablokowane. Chroni przed atakami brute-force
`DefaultLockoutTimeSpan`	Jak długo (w minutach) konto pozostaje zablokowane po przekroczeniu limitu prób

PasswordSecuritySettings¶

Wymagania, które musi spełniać hasło nowego użytkownika.

Klucz	Opis
`RequireDigit`	Wymaga co najmniej jednej cyfry (0–9)
`RequireUppercase`	Wymaga co najmniej jednej wielkiej litery
`RequireLowercase`	Wymaga co najmniej jednej małej litery
`RequireNonAlphanumeric`	Wymaga co najmniej jednego znaku specjalnego (np. `!`, `@`, `#`)
`RequiredLength`	Minimalna długość hasła w znakach

Hangfire¶

Hangfire to wewnętrzny scheduler – uruchamia zadania w tle, takie jak wysyłanie powiadomień, generowanie raportów czy synchronizacje z zewnętrznymi systemami.

General¶

Klucz	Opis
`WorkerCount`	Ile zadań może być przetwarzanych jednocześnie. Zwiększ, jeśli system ma dużo zadań w kolejce i serwer ma odpowiednią liczbę rdzeni
`SchedulePollingIntervalSeconds`	Co ile sekund scheduler sprawdza, czy są zadania do wykonania. Mniejsza wartość = szybsze reagowanie, ale większe obciążenie bazy
`DistributedLockTimeoutIntervalMinutes`	Ile minut scheduler czeka na zwolnienie blokady, zanim uzna zadanie za nieobsługiwane. Ważne w środowiskach z wieloma instancjami API

Dashboard¶

Panel zarządzania zadaniami Hangfire dostępny pod adresem /hangfire. Pozwala podglądać kolejkę zadań, historię wykonań i błędy.

Klucz	Opis
`Username`	Login do panelu. Zostaw puste, jeśli panel nie powinien być publicznie dostępny (zalecane schowanie go za VPN lub firewallem)
`Password`	Hasło do panelu

Przykład (docker-compose):

environment:
  - Hangfire__Dashboard__Username=admin
  - Hangfire__Dashboard__Password=bezpieczne-haslo

OpenSearchSettings¶

OpenSearch to wyszukiwarka pełnotekstowa – umożliwia szybkie przeszukiwanie treści dokumentów w systemie. Jest opcjonalna; jeśli nie jest skonfigurowana, wyszukiwanie działa jedynie po metadanych.

Klucz	Opis
`Uri`	Adres URL instancji OpenSearch, np. `http://opensearch:9200`
`Auth.Username`	Nazwa użytkownika OpenSearch
`Auth.Password`	Hasło użytkownika OpenSearch
`EmbeddingsUri`	Adres serwisu generującego wektory semantyczne (embeddingi), używanego przez funkcje AI do wyszukiwania znaczeniowego. Zostaw puste, jeśli nie używasz modułu AI

Przykład (docker-compose):

environment:
  - OpenSearchSettings__Uri=http://opensearch:9200
  - OpenSearchSettings__Auth__Username=admin
  - OpenSearchSettings__Auth__Password=haslo-opensearch

Indices¶

Lista indeksów OpenSearch konfigurowanych przez system. Zazwyczaj nie wymaga zmian – domyślna konfiguracja jest odpowiednia dla większości instalacji.

Klucz	Opis
`Alias`	Nazwa indeksu w OpenSearch, np. `documents_pl` dla dokumentów po polsku
`Version`	Wersja schematu indeksu. Zmiana wartości wymusza przebudowanie indeksu
`UseMinimalSettings`	`true` = uproszczona konfiguracja indeksu (mniejsze zużycie zasobów, odpowiednie dla małych instalacji)

StackManagement¶

Integracja z zewnętrzną usługą zarządzania stosami. Zostaw puste, jeśli ta integracja nie jest używana.

Klucz	Opis
`BaseUrl`	Adres URL API zewnętrznej usługi
`ApiKey`	Klucz API do autoryzacji żądań

AISettings¶

Ustawienia modułu sztucznej inteligencji odpowiedzialnego za automatyczne odczytywanie danych z dokumentów (np. OCR z AI, ekstrakcja pól z faktur).

Klucz	Opis
`AIDataCaptureUri`	Adres serwisu AI. Serwis ten musi być dostępny sieciowo z kontenera API

Przykład (docker-compose):

environment:
  - AISettings__AIDataCaptureUri=http://ai-service:8000

LicenseServer¶

Konfiguracja połączenia z serwerem licencji Navigator365. Wymagana do weryfikacji aktywnej licencji.

Klucz	Opis
`Url`	Adres URL serwera licencji – otrzymasz go od dostawcy systemu
`ApiKey`	Klucz API do autoryzacji – unikalny dla każdej instalacji

Ustawienia ogólne¶

Klucz	Opis
`AllowedHosts`	Lista hostów (domen), z których API przyjmuje żądania. `*` oznacza wszystkie domeny – odpowiednie do testów; w produkcji wpisz konkretną domenę, np. `api.navigator.twojafirma.pl`
`FrontEndHostAddress`	Publiczny adres frontendu aplikacji, np. `https://navigator.twojafirma.pl`. Używany w linkach wysyłanych e-mailem (np. reset hasła) oraz w konfiguracji CORS
`DefaultBackgroundServicesInterval`	Co ile minut uruchamiane są domyślne procesy w tle
`WorkflowSubstitutionsInterval`	Co ile minut system sprawdza zastępstwa w obiegach dokumentów (np. gdy pracownik jest na urlopie)
`TrashCleanupInterval`	Co ile minut system automatycznie czyści elementy usunięte do kosza po upływie okresu retencji
`MaxAgeOfLogsInDays`	Po ilu dniach logi systemowe są usuwane z bazy danych. Zmniejsz, jeśli baza szybko rośnie
`KeysPath`	Ścieżka do klucza szyfrowania ASP.NET Core Data Protection, używanego m.in. do zabezpieczania ciasteczek sesji. W Docker wskaż na katalog zamontowany jako wolumin – inaczej po restarcie kontenera wszyscy użytkownicy zostaną wylogowani

Przykład pełnej konfiguracji ogólnej (docker-compose):

environment:
  - AllowedHosts=navigator.twojafirma.pl
  - FrontEndHostAddress=https://navigator.twojafirma.pl
  - KeysPath=/keys
  - MaxAgeOfLogsInDays=30
volumes:
  - navigator_keys:/keys