ksef-pdf-generator/DEPLOYMENT.md

Instrukcja Deployment aplikacji KSEF PDF Generator na nginx

1. Przygotowanie artefaktów

Aplikacja została już zbudowana do folderu dist-app/:

cd /home/ms/projekty/fv-ksef-nodejs/ksef-pdf-generator

# Jeśli potrzebujesz ponownie zbudować:
npm run build:app

Zawartość dist-app/:

• index.html - główny plik HTML (punkt wejścia SPA)
• assets/ - folder ze skonkatenowanymi JS, CSS i zasobami

---

2. Deployment na serwer docelowy

a) Zkopuj artefakty do serwera

# Lokalnie, na maszynie z kodem:
scp -r dist-app/ user@www.sic.pl:/var/www/ksef/

# LUB jeśli deployment robisz z serwera:
scp -r /home/ms/projekty/fv-ksef-nodejs/ksef-pdf-generator/dist-app/ /var/www/ksef/

b) Upewnij się, że nginx ma uprawnienia

sudo chown -R www-data:www-data /var/www/ksef/
sudo chmod -R 755 /var/www/ksef/

---

3. Konfiguracja nginx

Opcja A: Dodaj blok do istniejącego /etc/nginx/nginx.conf

1. Otwórz /etc/nginx/nginx.conf:

sudo nano /etc/nginx/nginx.conf

2. W sekcji http {} dodaj:

include /etc/nginx/conf.d/ksef.conf;

Opcja B: Utwórz osobny plik konfigu

1. Zkopuj nginx-ksef.conf z repozytorium:

sudo cp nginx-ksef.conf /etc/nginx/conf.d/ksef.conf

2. WAŻNE: Edytuj /etc/nginx/conf.d/ksef.conf i zmień scieżki:

# ZMIEŃ TĘ LINIĘ:
root /home/ms/projekty/fv-ksef-nodejs/ksef-pdf-generator/dist-app;
alias /home/ms/projekty/fv-ksef-nodejs/ksef-pdf-generator/dist-app/;

# NA TWOJE ŚCIEŻKI W PRODUKCJI, np:
root /var/www/ksef;
alias /var/www/ksef/;

---

4. Testowanie konfigu i restartowanie nginx

# Sprawdź składnię konfigu
sudo nginx -t

# Jeśli OK, restartuj nginx
sudo systemctl restart nginx

# Lub reload (bez drop current connections):
sudo systemctl reload nginx

---

5. Weryfikacja

Otwórz w przeglądarce: http://www.sic.pl/ksef/

Powinieneś zobaczyć interfejs aplikacji z polami do wgrania XML-ów.

---

6. Logi i debugowanie

Logi nginx:

sudo tail -f /var/log/nginx/ksef-access.log
sudo tail -f /var/log/nginx/ksef-error.log

Jeśli widzisz błędy 404 na asetach, sprawdź:

• Ścieżkę w alias / root
• Uprawnienia folderu /var/www/ksef/
• Że dist-app/index.html istnieje

---

7. HTTPS (SSL/TLS)

Aby używać HTTPS:

1. Uzyskaj certyfikat (np. Let's Encrypt):

sudo certbot certonly --webroot -w /var/www/ksef -d www.sic.pl

2. Odkomentuj blok server { listen 443 ssl ... } w nginx-ksef.conf i wstaw ścieżki certyfikatu.

3. Konfiguruj HTTP → HTTPS redirect.

---

8. Aktualizacja aplikacji (CI/CD)

Podczas deployment nowej wersji:

1. Zbuduj aplikację lokalnie:

npm run build:app

2. Zkopuj do serwera (zastępując starą wersję):

scp -r dist-app/* user@www.sic.pl:/var/www/ksef/

3. Cache przeglądarki: ponieważ index.html nie ma cache (max-age=0), przeglądarki zawsze pobiorą najnowszą wersję przy następnej wizycie.

---

Struktura produkcji

/var/www/ksef/
├── index.html           (punkt wejścia, no cache)
├── assets/
│   ├── index-HASH.js    (bundled app, cached)
│   └── index-HASH.css   (bundled styles, cached)

--

Gotowe! Aplikacja powinna być dostępna na http://www.sic.pl/ksef/ 🚀