Instalacja

Wymagania wstępne

System operacyjny: Ubuntu 22.04+ lub Debian 12+ (inne dystrybucje Linux mogą działać, ale nie są oficjalnie wspierane)
RAM: minimum 4 GB (zalecane 8 GB)
Dysk: minimum 20 GB wolnego miejsca
Docker: zostanie zainstalowany automatycznie, jeśli nie jest obecny
Dostęp sieciowy: serwer musi mieć dostęp do internetu (pobieranie obrazów Docker) oraz do serwera SAP B1

Instalacja

1. Pobranie repozytorium

git clone https://github.com/BizCode-Sp-z-o-o/bizflow-nh.git
cd bizflow-nh
chmod +x install.sh ctl.sh openbao-entrypoint.sh

2. Uruchomienie instalatora

sudo ./install.sh

Instalator wymaga uprawnień root (Docker socket, porty, certyfikaty). Przeprowadzi Cię przez interaktywną konfigurację.

Na Ubuntu/Debian Docker zostanie zainstalowany automatycznie, jeśli nie jest obecny (apt, klucz GPG, oficjalne repozytorium Docker, systemctl enable, konfiguracja rotacji logów).

3. Tryb instalacji

Deployment mode
  1) dev  — direct port access, no SSL, for development/testing
  2) prod — Nginx Proxy Manager with SSL, domain-based routing

Dev — API dostępne na porcie 5001, Dashboard na 4322. Do testów i wdrożeń w sieci lokalnej.
Prod — NPMplus (z CrowdSec) zarządza ruchem, SSL i domenami. Wszystkie serwisy dostępne wyłącznie przez reverse proxy. Monitoring i panel NPM dostępne tylko z localhost (tunel SSH).

4. Dane ACR

Azure Container Registry credentials
  ACR Username: xxxxxxxxx
  ACR Password: xxxxxxxxx

5. Domeny (tryb prod)

W trybie produkcyjnym instalator zapyta o domeny:

Dashboard domain (e.g. bizflow.klient.pl): bizflow.firma.pl
API domain [api.bizflow.firma.pl]:
Email for Let's Encrypt: admin@firma.pl

Domyślna domena API to api. + domena dashboardu. Można ją zmienić.

Konfiguracja DNS

Przed instalacją skieruj domeny na IP serwera:

bizflow.firma.pl      A     → IP serwera
api.bizflow.firma.pl  A     → IP serwera (lub CNAME na bizflow.firma.pl)

6. Monitoring (opcjonalny)

Enable monitoring? (y/n) [y]:

Jeśli włączony, instalator doda:

Grafana — dashboardy metryk (KSeF, API, infrastruktura)
Prometheus — zbieranie metryk
Tempo — śledzenie rozproszone (distributed tracing)
Dozzle — przeglądarka logów kontenerów
OpenTelemetry Collector — agregacja telemetrii

Hasła do Grafany i Dozzle są generowane automatycznie i wyświetlane w podsumowaniu instalacji.

7. Automatyczne generowanie haseł

Instalator generuje unikalne, losowe hasła dla każdej instalacji:

PostgreSQL (baza danych)
RabbitMQ (kolejka wiadomości)
Redis (pamięć podręczna)
JWT (tokeny autoryzacji)
OpenBao (magazyn certyfikatów — automatyczna inicjalizacja i odpieczętowanie)
MinIO (przechowywanie plików)
Grafana (monitoring)
Dozzle (logi)

Hasła zapisywane są w pliku .env (chmod 600, dostęp tylko dla właściciela).

8. Środowisko KSeF

Środowisko KSeF (test/demo/prod) nie jest konfigurowane w instalatorze — to ustawienie aplikacyjne. Po zalogowaniu zmień je w Ustawienia → Organizacja → [firma] → Integracja KSeF (combobox). Zmiana działa natychmiast.

Domyślnie ustawione jest środowisko test (ksef-test.mf.gov.pl).

Po instalacji

Tryb dev

Application:
  Dashboard:  http://localhost:4322
  API:        http://localhost:5001

Default login:
  Email:    admin@bizflownh.dev
  Password: Admin123!

Tryb prod

Application:
  Dashboard:  https://bizflow.firma.pl
  API:        https://api.bizflow.firma.pl

Default login:
  Email:    admin@bizflownh.dev
  Password: Admin123!

Konfiguracja NPM (tryb prod)

Panel administracyjny NPM jest dostępny tylko z localhost. Połącz się przez tunel SSH:

ssh -L 8181:127.0.0.1:81 user@IP_SERWERA

Następnie otwórz http://localhost:8181 w przeglądarce.

Domyślne dane logowania NPM: admin@example.com / changeme (zmień po pierwszym logowaniu).

Konfiguracja proxy

Skonfiguruj dwa proxy hosts w NPM:

Domena	Forward Host	Forward Port	SSL
`bizflow.firma.pl`	`dashboard`	`4322`	Let’s Encrypt
`api.bizflow.firma.pl`	`api`	`8080`	Let’s Encrypt

Dla proxy hosta API dodaj w zakładce Custom Nginx Configuration:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";

Monitoring (tryb prod)

Monitoring jest dostępny tylko z localhost. Połącz się przez tunel SSH:

ssh -L 3001:127.0.0.1:3001 -L 3002:127.0.0.1:3002 user@IP_SERWERA

Grafana: http://localhost:3001 (login: admin / hasło z podsumowania instalacji)
Dozzle: http://localhost:3002 (login: admin / hasło z podsumowania instalacji)

Automatyczne aktualizacje

System używa Watchtower do automatycznego wykrywania i pobierania nowych obrazów Docker z ACR. Domyślnie sprawdza co 5 minut. Po wykryciu nowego obrazu kontener jest automatycznie restartowany z nową wersją.

Dane w bazie nie są usuwane przy aktualizacji.

Zarządzanie systemem

Wszystkie operacje wykonujesz skryptem ctl.sh:

Komenda	Opis
`./ctl.sh start`	Uruchomienie wszystkich kontenerów
`./ctl.sh stop`	Zatrzymanie wszystkich kontenerów
`./ctl.sh restart`	Restart wszystkich kontenerów
`./ctl.sh status`	Status kontenerów
`./ctl.sh logs [serwis]`	Logi (np. `./ctl.sh logs api`)
`./ctl.sh update`	Ręczne pobranie najnowszych obrazów z ACR i restart
`./ctl.sh backup`	Kopia zapasowa bazy danych
`./ctl.sh restore [plik]`	Przywrócenie z kopii zapasowej

Kopie zapasowe

./ctl.sh backup

Tworzy skompresowany zrzut bazy PostgreSQL w katalogu backups/.

Dodatkowo kontener db-backup automatycznie tworzy kopię zapasową co 6 godzin (kompresja zstd, retencja 7 dni).