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¶

Instrukcję dla użytkowników, porównanie trybów i opis filtrów znajdziesz w artykule Wyszukiwanie dokumentów.

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
`ChunkingUri`	Adres serwisu dzielącego tekst na fragmenty, np. `http://text-chunking-service:8000`. Ustawienie samego adresu chunkera włącza tekstowe chunki bez wektorów
`EmbeddingsUri`	Adres serwisu generującego wektory semantyczne, np. `http://text-embedding-service:8000`. `ChunkingUri` i `EmbeddingsUri` są wymagane dla wyszukiwania semantycznego
`IndexingBatchSize`	Wielkość paczki podczas pełnego indeksowania dokumentów oraz wysyłania fragmentów tekstu do indeksu. Domyślnie `1000`. Szczegóły poniżej.
`IndexingMaxDegreeOfParallelism`	Maksymalna liczba paczek przetwarzanych równolegle podczas pełnego indeksowania dokumentów. Domyślnie `5`.

Przykład (docker-compose):

environment:
  - OpenSearchSettings__Uri=http://opensearch:9200
  - OpenSearchSettings__Auth__Username=admin
  - OpenSearchSettings__Auth__Password=haslo-opensearch
  - OpenSearchSettings__ChunkingUri=http://text-chunking-service:8000
  - OpenSearchSettings__EmbeddingsUri=http://text-embedding-service:8000
  - OpenSearchSettings__IndexingBatchSize=1000
  - OpenSearchSettings__IndexingMaxDegreeOfParallelism=5

Wielkość paczek i równoległość indeksowania¶

Oba parametry należą bezpośrednio do sekcji OpenSearchSettings. Pominięcie ich w konfiguracji zachowuje wartości domyślne: 1000 elementów w paczce i 5 równoległych paczek.

IndexingBatchSize określa liczbę dokumentów pobieranych do przygotowania w jednej paczce podczas pełnego indeksowania. Określa również maksymalną liczbę wygenerowanych fragmentów tekstu (chunków) wysyłanych jednym żądaniem bulk. Jeden dokument może mieć wiele fragmentów. Ustawienie nie określa długości fragmentu ani rozmiaru żądania w bajtach. Wartość musi być większa od zera.
IndexingMaxDegreeOfParallelism ogranicza liczbę jednocześnie przetwarzanych paczek podczas pełnego indeksowania. Wartość 1 oznacza przetwarzanie kolejno. Do określenia przewidywalnego limitu używaj dodatniej liczby całkowitej. Wysyłanie fragmentów w ramach pojedynczego wywołania odbywa się kolejno; różne paczki dokumentów mogą jednak przetwarzać swoje fragmenty równolegle.

Parametry nie zmieniają wielkości paczki głównych dokumentów obsługiwanej przez osobną kolejkę bieżących aktualizacji. Nie wpływają też na liczbę wyników wyszukiwania ani podpowiedzi.

Przykład ustawienia mniejszych paczek w appsettings.local.json:

{
  "OpenSearchSettings": {
    "IndexingBatchSize": 100,
    "IndexingMaxDegreeOfParallelism": 1
  }
}

Dodaj te właściwości do istniejącej sekcji, jeśli plik już ją zawiera. Po zmianie ustawień zrestartuj API Navigator365. Sam restart nie wymusza przebudowy poprawnie zainicjalizowanego, istniejącego indeksu.

Przy paczce 100 i równoległości 5 pełne indeksowanie może przetwarzać do pięciu paczek, czyli do 500 dokumentów jednocześnie. Nie jest to limit liczby fragmentów ani całkowitego zużycia pamięci. Bezpieczna równoległość zależy od wydajności aplikacji, OpenSearch oraz wielkości załączników.

Przy diagnozowaniu przeciążenia lub błędów wysyłania dużych paczek można rozpocząć od 100 i 1, a następnie stopniowo zwiększać równoległość, obserwując czas przetwarzania i błędy. Zmniejszenie liczby elementów nie gwarantuje zmieszczenia żądania w limitach proxy lub OpenSearch — paczka może zawierać duże załączniki.

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