================================================================================
  i-BOK 5 - Internetowe Biuro Obslugi Klienta
  INSTRUKCJA INSTALACJI
  Wersja: 5.0 | Data: 2026-03-13
================================================================================


================================================================================
 1. WYMAGANIA SYSTEMOWE
================================================================================

1.1 System operacyjny
---------------------
  - Linux (Rocky Linux 8/9, CentOS 8/9, Debian 11+, Ubuntu 22.04+)
  - Windows Server z IIS (nieoficjalnie)

1.2 Serwer WWW
---------------
  - Apache 2.4 z mod_rewrite, mod_headers, mod_authz_core
  - lub Nginx z odpowiednia konfiguracja
  - lub OpenLiteSpeed

1.3 PHP - minimalna wersja: 7.4
---------------------------------
  Wymagany PHP 7.4 lub nowszy (zalecany PHP 8.1+).
  Powod: typed properties (string $var), null coalescing ??=,
  arrow functions, spread operator.

  Testowane na: PHP 7.4, 8.0, 8.1, 8.2, 8.3, 8.4

1.4 Wymagane moduly PHP
------------------------
  Obowiazkowe:
    - pdo_mysql     (polaczenie z baza PYXIS/MySQL)
    - openssl       (szyfrowanie AES-256-CBC, tokeny, 2FA)
    - curl          (bramki platnosci, heartbeat, API)
    - json          (konfiguracja, API, dane)
    - session       (zarzadzanie sesjami)
    - mbstring      (obsluga UTF-8, polskie znaki)
    - gd            (generowanie QR kodow 2FA)

  Opcjonalne:
    - zip           (eksport/import danych)
    - fileinfo      (wykrywanie MIME typow zalacznikow email)

  Weryfikacja modulow:
    php -m | grep -iE "pdo_mysql|openssl|curl|json|session|mbstring|gd"

  Lub w PHP:
    <?php
    $required = ['pdo_mysql','openssl','curl','json','session','mbstring','gd'];
    foreach ($required as $ext) {
        echo "$ext: " . (extension_loaded($ext) ? 'OK' : 'BRAK') . "\n";
    }

1.5 Baza danych
----------------
  - MySQL 5.7+ lub MariaDB 10.3+
  - Kodowanie: utf8mb4 (utf8mb4_unicode_ci)
  - Baza PYXIS (zwykle PYXIS4SQL) musi istniec z tabelami: Licencja, Userdb/vUserdb,
    Fv, Fvk, Oplaty, Mac, Podmioty, Operator, ZleceniaSerwisowe,
    Infrastruktura, vUmowyLista


================================================================================
 2. INSTALACJA
================================================================================

2.1 Przygotowanie katalogu
---------------------------
  Domyslna lokalizacja: /var/www/ibok5/

  mkdir -p /var/www/ibok5
  cp -r ibok5/* /var/www/ibok5/
  cp -r ibok5/.htaccess /var/www/ibok5/

2.2 Utworzenie wymaganych katalogow
------------------------------------
  Katalogi tworza sie automatycznie, ale mozna utworzyc recznie:

  mkdir -p /var/www/ibok5/cfg
  mkdir -p /var/www/ibok5/logs
  mkdir -p /var/www/ibok5/db/payments/sessions
  mkdir -p /var/www/ibok5/db/2fa
  mkdir -p /var/www/ibok5/admin
  mkdir -p /var/www/ibok5/data

2.4 Konfiguracja bazy danych - Instalator (ZALECANE)
------------------------------------------------------
  Po skopiowaniu plikow i skonfigurowaniu serwera WWW, otworz
  w przegladarce:

    https://twojafirma.pl/ibok5/install.php

  Instalator automatycznie:
  a) Sprawdzi wymagania systemowe (PHP, rozszerzenia)
  b) Zweryfikuje prawa dostepu do katalogow (cfg/, logs/, db/)
  c) Sprawdzi zabezpieczenia .htaccess
  d) Umozliwi podanie danych polaczenia z baza MySQL/MariaDB
  e) Przetestuje polaczenie i wykryje charset bazy
  f) Sprawdzi wersje serwera MySQL (>= 5.7) / MariaDB (>= 10.2)
  g) Zweryfikuje obecnosc kluczowych tabel PYXIS
  h) Zapisze konfiguracje do cfg/database.cfg

  Instalator wymaga akceptacji umowy licencyjnej (EULA.txt).

  UWAGA: Instalator jest dostepny TYLKO gdy baza nie jest jeszcze
  skonfigurowana. Jesli polaczenie juz dziala, otwarcie install.php
  przekieruje na admin.php.

2.5 Konfiguracja bazy danych - reczna (alternatywa)
-----------------------------------------------------
  Zamiast instalatora mozna recznie utworzyc plik cfg/database.cfg:

  {
      "enabled": true,
      "host": "localhost",
      "port": 3306,
      "database": "nazwa_bazy_pyxis",
      "username": "uzytkownik",
      "password": "haslo",
      "charset": "utf8mb4"
  }

  WAZNE - charset:
  Wartosc "charset" musi odpowiadac kodowaniu bazy danych PYXIS.
  Bledny charset powoduje nieprawidlowe wyswietlanie polskich znakow.
  Typowe wartosci:
    - utf8mb4  - nowe instalacje PYXIS (zalecane)
    - utf8     - starsze instalacje PYXIS z UTF-8
    - latin2   - stare instalacje PYXIS (ISO 8859-2)
    - cp1250   - stare instalacje PYXIS (Windows-1250)

  Sprawdzenie charset bazy z konsoli MySQL:
    SELECT DEFAULT_CHARACTER_SET_NAME FROM information_schema.SCHEMATA
    WHERE SCHEMA_NAME = 'nazwa_bazy';

2.6 Konfiguracja serwera WWW
------------------------------

  --- Apache (zalecany) ---

  <VirtualHost *:443>
      ServerName ibok.twojafirma.pl
      DocumentRoot /var/www/ibok5

      SSLEngine on
      SSLCertificateFile /etc/ssl/certs/ibok.crt
      SSLCertificateKeyFile /etc/ssl/private/ibok.key

      <Directory /var/www/ibok5>
          AllowOverride All
          Require all granted
      </Directory>

      # Blokada dostepu do katalogow wewnetrznych
      <DirectoryMatch "^/var/www/ibok5/(inc|cfg|db|logs|lang|sql)">
          Require all denied
      </DirectoryMatch>
  </VirtualHost>

  # Przekierowanie HTTP -> HTTPS
  <VirtualHost *:80>
      ServerName ibok.twojafirma.pl
      Redirect permanent / https://ibok.twojafirma.pl/
  </VirtualHost>

  --- Nginx ---

  server {
      listen 443 ssl;
      server_name ibok.twojafirma.pl;
      root /var/www/ibok5;
      index index.php;

      ssl_certificate /etc/ssl/certs/ibok.crt;
      ssl_certificate_key /etc/ssl/private/ibok.key;

      # Blokada katalogow wewnetrznych
      location ~ ^/(inc|cfg|db|logs|lang|sql)/ {
          deny all;
      }

      # Blokada plikow konfiguracyjnych
      location ~ \.(cfg|log|json|vbk)$ {
          deny all;
      }

      # Blokada config.php
      location = /config.php {
          deny all;
      }

      location ~ \.php$ {
          fastcgi_pass unix:/run/php-fpm/www.sock;
          fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
          include fastcgi_params;
      }
  }


================================================================================
 3. PRAWA DOSTEPU (PERMISSIONS)
================================================================================

  Zakladamy ze serwer WWW dziala jako uzytkownik: apache (lub www-data)

3.1 Wlasciciel plikow
-----------------------
  chown -R root:apache /var/www/ibok5

3.2 Prawa do katalogow
------------------------
  # Katalog glowny i pliki PHP - tylko odczyt
  chmod 750 /var/www/ibok5
  find /var/www/ibok5 -type f -name "*.php" -exec chmod 640 {} \;

  # Katalogi statyczne (CSS, JS, fonty, obrazy) - odczyt publiczny
  chmod 755 /var/www/ibok5/css
  chmod 755 /var/www/ibok5/js
  chmod 755 /var/www/ibok5/fonts
  find /var/www/ibok5/css -type f -exec chmod 644 {} \;
  find /var/www/ibok5/js -type f -exec chmod 644 {} \;
  find /var/www/ibok5/fonts -type f -exec chmod 644 {} \;

  # Katalogi z zapisem - serwer WWW musi miec zapis
  chmod 770 /var/www/ibok5/cfg
  chmod 770 /var/www/ibok5/logs
  chmod 770 /var/www/ibok5/db
  chmod 770 /var/www/ibok5/db/payments
  chmod 770 /var/www/ibok5/db/payments/sessions
  chmod 770 /var/www/ibok5/db/2fa
  chmod 770 /var/www/ibok5/admin
  chmod 770 /var/www/ibok5/data

  # Pliki konfiguracyjne - ograniczony dostep
  find /var/www/ibok5/cfg -type f -exec chmod 660 {} \;

  # Pliki .htaccess - odczyt dla Apache
  find /var/www/ibok5 -name ".htaccess" -exec chmod 644 {} \;

3.3 Tabela praw dostepu
-------------------------

  Katalog/Plik              Prawa   Wlasciciel    Opis
  -----------------------------------------------------------------------
  /var/www/ibok5/           750     root:apache   Katalog glowny
  ├── *.php                 640     root:apache   Pliki PHP (tylko odczyt)
  ├── .htaccess             644     root:apache   Reguly Apache
  │
  ├── inc/                  750     root:apache   Biblioteki PHP
  │   └── *.php             640     root:apache   Tylko odczyt
  │
  ├── pages/                750     root:apache   Strony klienta
  ├── pages_admin/          750     root:apache   Strony admina
  ├── lang/                 750     root:apache   Tlumaczenia
  ├── sql/                  750     root:apache   Schemat bazy
  │
  ├── cfg/                  770     root:apache   Konfiguracja (ZAPIS)
  │   ├── database.cfg      660     apache:apache Dane dostepu do bazy
  │   ├── smtp.cfg          660     apache:apache Dane SMTP
  │   ├── tpay.cfg          660     apache:apache Dane Tpay (szyfrowane)
  │   ├── p24.cfg           660     apache:apache Dane P24 (szyfrowane)
  │   ├── payu.cfg          660     apache:apache Dane PayU (szyfrowane)
  │   └── *.cfg             660     apache:apache Pozostale konfiguracje
  │
  ├── logs/                 770     root:apache   Logi aplikacji (ZAPIS)
  ├── db/                   770     root:apache   Dane (ZAPIS)
  │   ├── payments/         770     root:apache   Logi platnosci
  │   │   └── sessions/     770     root:apache   Sesje platnosci
  │   └── 2fa/              770     root:apache   Dane 2FA
  │
  ├── admin/                770     root:apache   Szablony tekstowe (ZAPIS)
  ├── data/                 770     root:apache   PDF-y klientow (ZAPIS)
  │
  ├── css/                  755     root:apache   Arkusze stylow
  ├── js/                   755     root:apache   JavaScript
  ├── fonts/                755     root:apache   Czcionki

3.4 SELinux (Rocky Linux / CentOS)
------------------------------------
  Jezeli SELinux jest wlaczony:

  # Pozwol Apache na zapis
  setsebool -P httpd_unified 1

  # Lub dokladniej:
  semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/ibok5/cfg(/.*)?"
  semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/ibok5/logs(/.*)?"
  semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/ibok5/db(/.*)?"
  semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/ibok5/admin(/.*)?"
  semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/ibok5/data(/.*)?"
  restorecon -Rv /var/www/ibok5/

  # Pozwol na polaczenia sieciowe (baza danych, API, bramki platnosci)
  setsebool -P httpd_can_network_connect 1
  setsebool -P httpd_can_network_connect_db 1
  setsebool -P httpd_can_sendmail 1


================================================================================
 4. KONFIGURACJA PHP (php.ini)
================================================================================

  Zalecane ustawienia:

  ; Sesje
  session.cookie_httponly = 1
  session.cookie_samesite = Strict
  session.use_strict_mode = 1
  session.use_only_cookies = 1
  session.cookie_secure = 1          ; wylacznie dla HTTPS

  ; Bezpieczenstwo
  expose_php = Off
  display_errors = Off
  log_errors = On
  error_log = /var/log/php/error.log

  ; Limity
  max_execution_time = 60
  memory_limit = 128M
  post_max_size = 20M                ; dla zalacznikow email
  upload_max_filesize = 20M
  max_input_vars = 2000

  ; Strefa czasowa
  date.timezone = Europe/Warsaw

  ; Kodowanie
  default_charset = "UTF-8"
  mbstring.internal_encoding = UTF-8


================================================================================
 5. PIERWSZE URUCHOMIENIE
================================================================================

5.1 Instalator (pierwsze uruchomienie)
----------------------------------------
  Przy pierwszym uruchomieniu otworz:

    https://ibok.twojafirma.pl/install.php

  Instalator przeprowadzi przez konfiguracje bazy danych krok po kroku.
  Po zapisaniu konfiguracji przekieruje na panel admina.

  Szczegoly dzialania instalatora - patrz sekcja 2.4.

5.2 Dostep do panelu klienta
------------------------------
  https://ibok.twojafirma.pl/

  - Logowanie danymi klienta z bazy PYXIS (tabela vUserdb)
  - Wymaga skonfigurowanej bazy danych (cfg/database.cfg)

5.3 Dostep do panelu admina
-----------------------------
  https://ibok.twojafirma.pl/admin.php

  - Wymaga konta admina w bazie (tabela ibok_admin)

5.4 Konfiguracja po zalogowaniu
---------------------------------
  1. admin.php -> SMTP            -> Konfiguracja poczty wychodzacej
  2. admin.php -> Platnosci       -> Konfiguracja bramek (Tpay/P24/PayU)
  3. admin.php -> Kontrola dostepu -> Whitelist/blacklist IP
  4. admin.php -> Edycja          -> Szablony naglowkow, stopek, FAQ

5.4 Konfiguracja 2FA (opcjonalna)
-----------------------------------
  Panel admina i klienta obsluguja 2FA (TOTP):
  - admin.php -> 2FA -> Wlacz uwierzytelnianie dwuskladnikowe
  - Kompatybilne z: Google Authenticator, Authy, Microsoft Authenticator


================================================================================
 6. BEZPIECZENSTWO
================================================================================

6.1 Zabezpieczenia wbudowane
------------------------------
  [OK] Sesje: HttpOnly, SameSite=Strict, Secure (HTTPS), 30-min timeout
  [OK] CSRF: tokeny sesyjne na formularzach POST
  [OK] XSS: htmlspecialchars() na wszystkich danych uzytkownika (1300+ uzyc)
  [OK] CSP: Content-Security-Policy z nonce na skryptach
  [OK] Brute-force: 5 prob logowania / 15 minut blokady per IP
  [OK] 2FA: TOTP (Google Authenticator) + kody zapasowe
  [OK] Szyfrowanie: AES-256-CBC dla danych wrazliwych (hasla bramek)
  [OK] Kontrola dostepu IP: osobna dla klienta i admina
  [OK] Naglowki bezpieczenstwa: X-Frame-Options, X-Content-Type-Options,
       X-XSS-Protection, Referrer-Policy
  [OK] Blokada katalogow: .htaccess deny na inc/, cfg/, db/, logs/, lang/
  [OK] Hasla: bcrypt (password_hash / password_verify)
  [OK] Audit log: rejestracja akcji z IP, uzytkownikiem, znacznikiem czasu

6.2 Dodatkowe zalecenia
-------------------------
  - Uzywaj HTTPS (certyfikat SSL/TLS) - OBOWIAZKOWE
  - Skonfiguruj firewall (iptables/firewalld) - ogranicz dostep do portow
  - Regularnie aktualizuj PHP i serwer WWW
  - Monitoruj logi: logs/ibok_YYYY-MM.log
  - Wlacz 2FA dla konta administratora
  - Zmien domyslny timeout sesji w config.php (IBOK_SESSION_TIMEOUT)
  - Ogranicz dostep do admin.php po IP (cfg/access_control.cfg)

6.3 Pliki .htaccess (ochrona)
-------------------------------
  Projekt zawiera 7 plikow .htaccess:

  .htaccess           - Blokuje *.vbk, *.cfg, *.log, *.json, config.php
                        Wylacza listowanie katalogow, naglowki bezpieczenstwa
  inc/.htaccess       - Deny all (blokuje dostep HTTP do bibliotek)
  cfg/.htaccess       - Deny all (blokuje dostep do konfiguracji)
  db/.htaccess        - Deny all (blokuje dostep do danych)
  db/payments/.htaccess - Deny all
  logs/.htaccess      - Deny all (blokuje dostep do logow)
  lang/.htaccess      - Deny all (blokuje dostep do plikow jezykowych)


================================================================================
 8. BRAMKI PLATNOSCI
================================================================================

  Obslugiwane bramki:
  - Tpay (tpay.com) - BLIK, przelewy, karty
  - Przelewy24 (przelewy24.pl) - BLIK, przelewy, karty
  - PayU (payu.com) - BLIK, karty, przelewy, raty

  Konfiguracja w panelu admina: admin.php -> Platnosci

  Adresy callback (webhook) - ustawic w panelu bramki:
    https://ibok.twojafirma.pl/payment_callback.php

  Dane uwierzytelniajace sa szyfrowane AES-256-CBC
  i przechowywane w cfg/tpay.cfg, cfg/p24.cfg, cfg/payu.cfg


================================================================================
 9. ROZWIAZYWANIE PROBLEMOW
================================================================================

9.1 Blad polaczenia z baza
-----------------------------
  - Sprawdz cfg/database.cfg (dane dostepu)
  - Testuj z konsoli: mysql -h HOST -u USER -p DATABASE
  - Sprawdz czy modul pdo_mysql jest zainstalowany: php -m | grep pdo_mysql
  - Sprawdz logi: logs/ibok_YYYY-MM.log

9.2 Blad 403 przy logowaniu
-------------------------------
  - Sprawdz kontrole dostepu IP: cfg/access_control.cfg
  - Sprawdz .htaccess (AllowOverride All w konfiguracji Apache)
  - Sprawdz SELinux: getenforce (moze blokowac Apache)

9.3 Sesja wygasa zbyt szybko
--------------------------------
  - Domyslny timeout: 30 minut (config.php: IBOK_SESSION_TIMEOUT)
  - session_ping.php automatycznie podtrzymuje sesje
  - Sprawdz session.gc_maxlifetime w php.ini

9.4 Platnosci nie dzialaja
------------------------------
  - Sprawdz konfiguracje bramki: admin.php -> Platnosci
  - Sprawdz callback URL (musi byc dostepny z internetu)
  - Sprawdz logi: db/payments/YYYY-MM.log
  - Tryb sandbox: wlacz w konfiguracji bramki (do testow)

9.5 2FA nie dziala
---------------------
  - Sprawdz synchronizacje czasu serwera (NTP): timedatectl
  - Kody sa wazne 30 sekund (+/- 1 okres tolerancji)
  - Uzyj kodow zapasowych jezeli TOTP nie dziala
  - Sprawdz modul gd: php -m | grep gd (wymagany dla kodow QR)

9.6 Brak polskich znakow
----------------------------
  - Sprawdz charset bazy: utf8mb4_unicode_ci
  - Sprawdz PHP: mbstring.internal_encoding = UTF-8
  - Sprawdz .htaccess: AddDefaultCharset UTF-8


================================================================================
 10. KONTAKT I WSPARCIE
================================================================================

  Producent: ININOUT & PYXIS
  WWW:       https://pyxisisp.pl

================================================================================
  (c) ININOUT & PYXIS. Wszelkie prawa zastrzezone.
================================================================================
