﻿# WorkSmartHub Dockeren és Kubernetesen

> Ez a repository elkészíti a WorkSmartHub konténer-image-ét, és futtatja Dockerrel vagy Kubernetesen; ez a dokumentum mindkét üzemeltetési mód leírása. A WorkSmartHub (WorkWise Solutions) egyetlen webalkalmazás: az ASP.NET Core szervert és az Angular portált ugyanaz a konténer szolgálja ki,…

Source: https://workwise-solutions.net/hu/docs/installation/operator-guide/ · Language: hu · English version: https://workwise-solutions.net/docs/installation/operator-guide/

Ez a repository elkészíti a WorkSmartHub konténer-image-ét, és futtatja Dockerrel vagy Kubernetesen; ez a dokumentum
mindkét üzemeltetési mód leírása. A WorkSmartHub (WorkWise Solutions) egyetlen webalkalmazás: az ASP.NET Core szervert
és az Angular portált ugyanaz a konténer szolgálja ki, ugyanazon a porton.

## A repository tartalma

| Útvonal | Mi ez |
|---------|-------|
| `build/build-image.sh`, `build/build-image.ps1` | A `worksmarthub:<verzió>` image elkészítése a Backend és a Frontend forrásmappájából (bash vagy PowerShell) |
| `docker/linux/` | `worksmarthub-run.sh` (a konténer indítása), `worksmarthub-service-install.sh` / `worksmarthub-service-uninstall.sh` (systemd szolgáltatás) |
| `docker/win/` | Ugyanez Windowsra, Docker Desktoppal: `worksmarthub-run.ps1`, `worksmarthub-service-install.ps1` / `worksmarthub-service-uninstall.ps1` (ütemezett feladat) |
| `kubernetes-helm-chart/` | A `worksmarthub` Helm chart: az alkalmazás, egy tartós adatkötet, opcionálisan beépített PostgreSQL és Redis, Ingress, NetworkPolicy-k |
| `test-local/` | Tesztszkriptek helyi Docker démonhoz és minikube-hoz (lásd [test-local/README.md](https://github.com/WorkWise-Solutions/WorkSmartHub-Docker-Kubernetes/blob/main/test-local/README.md)) |

## Előfeltételek

- **Docker:** Linuxon Docker Engine 20.10 vagy újabb, Windowson Docker Desktop (részletek: [Docker előfeltételek](#docker-előfeltételek)).
- **Kubernetes:** egy fürt, `kubectl` és Helm 3 (részletek: [Kubernetes előfeltételek](#kubernetes-előfeltételek)).
- **Az image elkészítéséhez:** a Backend .NET SDK-ja (`WorkSmartHub/global.json`), Node.js és npm, Docker, valamint bash
  (Windowson Git Bash) vagy PowerShell 5.1 vagy 7.
- Az image az ASP.NET Core 10.0 futtatókörnyezetet tartalmazza Ubuntu 24.04 LTS-en, és a nem root `appuser`
  felhasználóként (uid 1001) fut. A gépekre nem kell .NET futtatókörnyezet; a futtatókörnyezet frissítése új
  image-dzsel érkezik.

## Az image elkészítése

Nincs registry és nincs pipeline: az image helyben készül a két forrásmappából.

```bash
# ebből a repositoryból, ha a források a ../WorkSmartHub-Backend és ../WorkSmartHub-Frontend testvérmappákban vannak
bash build/build-image.sh --version 23
```

```powershell
.\build\build-image.ps1 -Version 23
```

A szkript

1. lefordítja a Frontendet (`npm ci && npm run build`; a csomag a `.br` és `.gz` fájljaival a `dist/` mappájába kerül);
   a `--skip-frontend-build` / `-SkipFrontendBuild` a meglévő `dist/` mappát használja;
2. a Backend forrását egy ideiglenes munkamappába másolja (`.git`, `bin`, `obj`, helyi adatbázisok, naplók és File
   Storage nélkül), a Frontend csomagot a másolat `WorkSmartHub/wwwroot/Frontend` mappájába teszi, és a verziót
   `ReleaseId`-ként beírja a másolat `wwwroot/version.json` fájljába (az alkalmazás által mutatott kiadásszám; csak
   pozitív egész kerül be, egy `23-rc1` jellegű címke esetén a fájl változatlan marad);
3. lefuttatja a `dotnet publish -c Release` parancsot a másolaton;
4. lefuttatja a `docker build --pull` parancsot a publish kimenet `Dockerfile`-jával, és `worksmarthub:<verzió>`,
   valamint `worksmarthub:latest` címkét ad.

A forrásmappák nem változnak: a build fájlokat generál újra (az API klienst, az `appsettings.template.json`-t), és ez a
munkamappa másolatában történik, amelyet a szkript a végén töröl (a `--keep-staging` / `-KeepStaging` megtartja). Az
image címkéi: `org.opencontainers.image.version`, valamint a két forrásmappa Git revíziója
(`com.workwise.worksmarthub.backend.revision`, `...frontend.revision`, nem commitolt változásnál `+dirty` utótaggal).

| Kapcsoló (bash / PowerShell) | Alapérték | Jelentés |
|------------------------------|-----------|----------|
| `--backend <mappa>` / `-Backend` | `../WorkSmartHub-Backend` | A Backend mappa (a `submodules/WorkWise.Common` almodullal) |
| `--frontend <mappa>` / `-Frontend` | `../WorkSmartHub-Frontend` | A Frontend mappa |
| `--skip-frontend-build` / `-SkipFrontendBuild` | | A `<frontend>/dist` újrahasználása |
| `--changelog <file>` / `-Changelog <file>` | `../WorkSmartHub-Changelog/changelog.html` | A portálon megjelenő kiadási jegyzék, az image-be `wwwroot/changelog.html` néven kerül |
| `--version <v>` / `-Version` | a `WorkSmartHub/wwwroot/version.json` `ReleaseId` értéke, ha pozitív | Az image címkéje. Fejlesztői munkapéldányban ott `-1` áll, ezért adja meg a verziót |
| `--repository <név>` / `-Repository` | `worksmarthub` | Az image neve, registryhez pl. `docker.io/cegnev/worksmarthub` |
| `--no-latest` / `-NoLatest` | | Ne kerüljön át a `latest` címke |
| `--minikube` / `-Minikube` | | A minikube Docker démonjában készül; másik profilhoz `--minikube-profile <név>` / `-MinikubeProfile` |
| `--save <fájl.tar>` / `-Save` | | Az image-et tar fájlba is kiírja |
| `--no-cache` / `-NoCache` | | Rétegcache nélkül készül, így az image a legfrissebb Ubuntu biztonsági frissítéseket kapja |
| `--staging <mappa>` / `-Staging` | új ideiglenes mappa | Ide kerül a másolat és a publish kimenet (üres kell legyen) |
| `--keep-staging` / `-KeepStaging` | | A munkamappa megtartása |

**Másik gépre.** Fájlként vigye át: `--save worksmarthub-23.tar`, a fájl átmásolása, majd a célgépen
`docker load -i worksmarthub-23.tar`.

**minikube.** A `--minikube` közvetlenül a minikube Docker démonjában építi az image-et (`eval $(minikube docker-env)`),
így a fürt registry nélkül is megtalálja. A `minikube image load` ekkora image-nél Windowson nem használható: hibával
leáll.

```bash
minikube start --driver=docker
bash build/build-image.sh --version 23 --minikube
```

**Később registryvel.** A `--repository registry.example.com/worksmarthub` kapcsolóval készítse, `docker push` mindkét
címkére, és ugyanezt a repositoryt állítsa be a Docker szkriptekben (`WSH_IMAGE` vagy `--image`) és a chartban
(`app.image.repository`).

**Mi van az image-ben.** A publish kimenet a `/app` alatt (belépési pont `dotnet WorkSmartHub.dll`, az `appuser`
tulajdonában), a 8080-as figyelési port, és a `/app/data` adatmappa, amelybe a `/app/database.db`, `/app/FileStorage` és
`/app/Logs` hivatkozás mutat (lásd [Adatmegőrzés](#adatmegőrzés)). Az image-ben van `bash`, `sh`, `tar` és `openssl`,
de nincs `curl` vagy `wget`, és nincs `HEALTHCHECK` utasítás (lásd [Állapotellenőrzés](#állapotellenőrzés)).

---

## Docker

A `docker/linux` és a `docker/win` mappa szkriptjei Docker-konténerként futtatják az alkalmazást: előtérben, háttérben,
vagy a gép indulásakor induló szolgáltatásként.

### Docker előfeltételek

- **Linux:** Docker Engine 20.10 vagy újabb (`docker version`), a Docker saját csomagtárolójából telepítve, induláskor
  engedélyezve (`sudo systemctl enable --now docker`). A szkripteket `sh` paranccsal futtassa; a szolgáltatás telepítő
  és eltávolító szkriptje rootjogot kér (`sudo sh ...`).
- **Windows:** Docker Desktop WSL 2 háttérrel, Linux-konténerekkel. Az indítószkripthez nem kell rendszergazdai jog, a
  szolgáltatás telepítéséhez és eltávolításához igen.
- A `worksmarthub:<verzió>` image a gépen: ott készült ([Az image elkészítése](#az-image-elkészítése)), vagy
  `docker load -i` paranccsal betöltötték.
- Opcionálisan egy `appsettings.json` és egy `worksmarthub.env` az indítószkript mellett (lásd [Beállítások](#beállítások)).
- Szolgáltatásként telepítéshez olyan szkriptmappa, amelyet a gép más felhasználói nem írhatnak (lásd
  [A szkriptmappa védelme](#a-szkriptmappa-védelme)).

### Beállítások

Az alkalmazás a `/app/appsettings.json` fájlt és a környezeti változókat olvassa; **a környezeti változó felülírja a
fájlt**. A változó neve a beállítás útvonala, a szakaszok között `__` jellel, tömbelemeknél `__0`, `__1`:
`ConnectionStrings__InternalDb`, `CacheSettings__Type`, `HttpSettings__Urls__0`, `PublicBaseUrl`.

Fájl nélkül a konténer az image-be épített `appsettings.json`-nal fut: SQLite az adatkötetben, memóriabeli cache, helyi
felhasználók. Az indítószkript minden esetben beállítja a `HttpSettings__Urls__0=http://+:8080` figyelési címet.
További beállításhoz két út van:

- **`worksmarthub.env` az indítószkript mellett:** környezeti változók, soronként egy `NÉV=érték`, idézőjelek és
  `export` nélkül. A szkript `--env-file` kapcsolóval adja át. Titkos értékekhez ez a megfelelő hely; csak a
  rendszergazdák olvashassák (`sudo chown root:root worksmarthub.env && sudo chmod 600 worksmarthub.env`).
- **`appsettings.json` az indítószkript mellett:** a teljes beállításfájl, a `/app/appsettings.json` helyére csatolva.
  Az image gyári fájljából induljon ki:
  ```bash
  docker run --rm --entrypoint cat worksmarthub:23 /app/appsettings.json > appsettings.json
  ```
  Az alkalmazás minden induláskor beleírja a fájlba egy újabb verzió új beállításkulcsait, és megtartja az Ön értékeit
  (előtte biztonsági másolatot ír a konténer `/app` mappájába: `appsettings.json.backup.<időpont>`). Ehhez az
  alkalmazásnak (uid 1001) írnia kell tudnia a fájlt: Linuxon
  `sudo chown 1001:root appsettings.json && sudo chmod 600 appsettings.json`. Root tulajdonú, 644-es módú fájllal is
  működik: ekkor az alkalmazás naplózza, hogy `appsettings.json is read-only; new settings keep their defaults until the
  file is updated`, és az új kulcsokat az alapértékükkel, memóriában használja. Root tulajdonú, 600-as vagy 640-es módú
  fájlt nem tud olvasni, és nem indul el. Mindenki által írhatóvá soha ne tegye a fájlt.

A fájl megjegyzésekkel kiegészített JSON; minden beállítás magyarázata benne van. A szakaszok:

| Szakasz | Szerepe |
|---------|---------|
| `ConnectionStrings` | A belső adatbázis: `InternalDbType` (0 SQLite, 1 SQL Server, 2 PostgreSQL, 3 MySQL), `InternalDb` (kapcsolati karakterlánc), `Schema` (csak SQL Server és PostgreSQL; SQLite-nál és MySQL-nél üres kell legyen), `MySqlServerVersion` (csak MySQL) |
| `CacheSettings` | `Type`: `InMemory` (alapérték), `None`, `Redis`, `SqlServer`, `Postgres`, `MySql`, mindegyikhez saját beállításblokkal |
| `PublicBaseUrl` | A cím, amelyen a felhasználók megnyitják az alkalmazást (lásd lent) |
| `HttpSettings` | `Urls` (figyelési címek; a konténerben `http://+:8080`), `Cors` |
| `Swagger` | `Enabled`: az interaktív API-leírás a `/swagger` címen |
| `Serilog` | Naplókimenetek (konzol és a `Logs/log-.txt` napi fájlok) és naplózási szintek |
| `UseDetailedExceptions` | Hibarészletek az API hibaválaszaiban |
| `UserSettings` | A felhasználótár: `Local` (alapérték), `LDAP`, `AzureAD` (Microsoft Entra ID), `ActiveDirectory` |
| `LoginSettings` | `AuthType` (`Local`, `ActiveDirectory`, `AppleConnect`, `OAuth`), a munkamenet hossza, az OAuth szolgáltatók (Okta, Google, Microsoft, Custom), a bejelentkezési süti, a JWT aláírókulcs |
| `Notifications` | A Microsoft Teams szolgáltatás címe |
| `EmailSettings` | Az alkalmazás által küldött e-mailek SMTP szervere |
| `TicketAttachment`, `ImageConfiguration` | A munkalap-mellékletek és alkatrészképek hivatkozásainak aláírókulcsa, élettartama és a feltöltés darabmérete |
| `ConfigSync` | Milyen gyakran veszik át a csomópontok az Admin felületen tett beállításváltozásokat (alapérték 10 másodperc) |

Minden más (File Storage-ok, értesítési csatornák, a Számlázz.hu kapcsolat, szolgáltatás felhasználói katalógusok,
biztonsági fejlécek, háttérfolyamatok, megjelenés) az Admin felületen állítható, és az adatbázisban tárolódik.

#### Az első éles használat előtt beállítandók

| Beállítás | Miért |
|-----------|-------|
| `LoginSettings.JwtAuthenticationSettings.SymmetricSecurityKey` | A bejelentkezési és a személyes hozzáférési tokeneket írja alá. A gyári érték nyilvános: azzal bárki hamisíthatna tokent bármely felhasználó nevében. Későbbi módosítása mindenkit kijelentkeztet, és érvényteleníti a hozzáférési tokeneket. |
| `TicketAttachment.DownloadLink.SymmetricSecurityKey` | A munkalap-mellékletek letöltési hivatkozásait írja alá. Későbbi módosítása érvényteleníti a korábban feltöltött mellékletek hivatkozásait. |
| `ImageConfiguration.ImageLink.SymmetricSecurityKey` | Az alkatrészképek hivatkozásait írja alá. Későbbi módosítása érvényteleníti a korábban feltöltött képek hivatkozásait. |
| `PublicBaseUrl` | pl. `https://wsh.example.com/`. Ebből készülnek az e-mailekben lévő hivatkozások (jelszó-visszaállítás, leiratkozás, az értesítések lábléce, a háttérfolyamatok által küldött e-mailekben is), a későbbi e-mailekhez tárolt hivatkozások és a mobilos aktiválás QR-kódja. Ha üres, ezek minden kérés címéből készülnek, amelyet a kérés küldője választhat meg. |
| `EmailSettings` | Az SMTP szerver, a port, a felhasználó, a jelszó és a feladó, ha az alkalmazás e-mailt küld. |
| `UseDetailedExceptions` | A gyári fájlban `true`. Éles üzemben `false`, hogy az API-hibák ne tartalmazzanak belső részleteket. |

Minden kulcshoz más, hosszú, véletlen értéket adjon (például `openssl rand -base64 48`), minden csomóponton ugyanazt. Az
alkalmazás minden induláskor `SECURITY:` figyelmeztetést naplóz, amíg egy kulcs a gyári értéken van, vagy a
`PublicBaseUrl` üres. A `worksmarthub.env` fájlban:

```
LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey=<hosszú véletlen érték>
TicketAttachment__DownloadLink__SymmetricSecurityKey=<egy másik hosszú véletlen érték>
ImageConfiguration__ImageLink__SymmetricSecurityKey=<egy harmadik hosszú véletlen érték>
PublicBaseUrl=https://wsh.example.com/
UseDetailedExceptions=false
```

> Ha a csatolt fájl a `ConnectionStrings` helyett az újabb `InternalDatabaseSettings` szakaszt használja, az erősebb a
> `ConnectionStrings` szakasznál és a `ConnectionStrings__*` környezeti változóknál; ekkor `InternalDatabaseSettings__*`
> változókat használjon.

#### Naplózási szintek

| Csatorna | `appsettings.json` kulcs | Környezeti változó |
|----------|--------------------------|--------------------|
| Alapértelmezett (az alkalmazás) | `Serilog:MinimumLevel:Default` | `Serilog__MinimumLevel__Default` |
| Microsoft (ASP.NET Core, Entity Framework) | `Serilog:MinimumLevel:Override:Microsoft` | `Serilog__MinimumLevel__Override__Microsoft` |
| Rendszer | `Serilog:MinimumLevel:Override:System` | `Serilog__MinimumLevel__Override__System` |

- Érvényes értékek: `Verbose`, `Debug`, `Information`, `Warning`, `Error`, `Fatal`, kis- és nagybetű nem számít. Beállítás
  nélkül a szint `Information`; éles üzemben a Microsoft csatornára a `Warning` jó választás.
- A fájl vagy a környezet változásai a következő induláskor érvényesek.
- Az Admin felületen az **App Konfiguráció > Log Szintek** oldalon van a **Szerver naplózási szintek felülírása**
  kapcsoló. Kikapcsolva a fenti szerverbeállítás érvényes. Bekapcsolva az oldalon választott három szint érvényes minden
  csomóponton a `ConfigSync` időközön belül, újraindítás nélkül. Minden módosítás a rendszergazda nevével együtt
  naplózódik.
- A kérésnaplók soha nem tartalmazzák a hitelesítő lekérdezési paraméterek értékét (`access_token`, hivatkozás-tokenek,
  OAuth `code` és `state`, és minden paraméter, amelynek nevében token, secret, auth, key, password vagy session
  szerepel); ezek helyén `***` áll.
- **Éles üzemben soha ne hagyja bekapcsolva a `Debug` vagy `Verbose` szintet:** sokkal több adatot írnak, akár
  személyes adatot is, és gyorsan megtöltik a lemezt.

#### Biztonsági beállítások

- **Aláírókulcsok és `PublicBaseUrl`:** lásd a fenti táblázatot.
- **Swagger:** a `Swagger:Enabled` (a gyári fájlban `true`) a `/swagger` címen szolgálja ki az API-leírást és a
  tesztfelületet; az API végpontjai így is hitelesítést kérnek. `false` értéknél minden `/swagger` útvonal 404-et ad.
  Ahol senkinek nincs rá szüksége, állítsa be: `Swagger__Enabled=false`.
- **Biztonsági fejlécek:** az Admin felületen, az **App Konfiguráció > Biztonsági fejlécek** oldalon állíthatók, és
  minden csomóponton érvényesek. Alapértelmezésben be van kapcsolva az `X-Frame-Options`, az
  `X-Content-Type-Options: nosniff`, a `Referrer-Policy: no-referrer`, a `Permissions-Policy` és egy
  `Content-Security-Policy`; a `Strict-Transport-Security` (HSTS) ki van kapcsolva. A HSTS-t akkor kapcsolja be, amikor
  az alkalmazás már csak HTTPS-en érhető el (alapértelmezett max-age 30 nap).
- **Bejelentkezési süti:** a `LoginSettings.CookieAuthenticationSettings.SecureCookie` értéke `true`: a böngészők csak
  HTTPS-en küldik a sütit. Az alkalmazást HTTPS-en szolgálja ki (TLS a fordított proxyn, a terheléselosztón vagy az
  Ingress-en).
- **CORS:** a gyári fájlban a `HttpSettings.Cors.AllowOrigin` értéke `http://localhost:4200` (a Frontend fejlesztői
  szervere). A portál ugyanarról az originről jön, mint az API, ezért nincs szüksége CORS-ra; ne nyissa meg `*`-ra.
- **Az Admin felületen megadott titkos értékek csak írhatók:** a felület és az API soha nem adja vissza őket, az üresen
  hagyott mező megtartja a tárolt értéket. Ha megváltoztatja, hova kerül egy titkos érték (SMTP szerver, egy File
  Storage végpontja, a Vault címe), ugyanabban a mentésben a titkos értéket is újra meg kell adni.
- **Munkamenetek:** a bejelentkezési sütiket védő kulcsok az adatbázisban vannak. Az adatbázist és a mentéseit ennek
  megfelelően védje.

#### Fordított proxy és továbbított fejlécek

A konténer a 8080-as porton sima HTTP-t beszél; a TLS egy fordított proxyn, terheléselosztón vagy a Kubernetes
Ingress-en végződik. Az alkalmazás az eredeti kliens címét, sémáját és hostját az `X-Forwarded-For`,
`X-Forwarded-Proto` és `X-Forwarded-Host` fejlécből veszi, és ezeket bármely forrástól elfogadja. Ezért:

- a proxy **állítsa be és írja felül** ezeket a fejléceket (a kliens által küldött értékeket soha ne adja tovább),
  nginx-nél:
  ```nginx
  proxy_set_header Host              $host;
  proxy_set_header X-Forwarded-Host  $host;
  proxy_set_header X-Forwarded-Proto $scheme;
  proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
  client_max_body_size 50m;
  proxy_read_timeout 600s;
  proxy_send_timeout 600s;
  ```
- a konténer portját csak a proxy felé tegye elérhetővé (`WSH_HTTP_PORT=127.0.0.1:8080`, ha a proxy ugyanazon a gépen
  fut), hogy a proxyt megkerülve senki ne érje el az alkalmazást.

A melléklet- és képhivatkozások és az OAuth `redirect_uri` a kérésből készül (a továbbított hostból és sémából); az
e-mailek hivatkozásai a `PublicBaseUrl` értékből. Az 50 MB-os feltöltési korlát és a 600 másodperces időkorlát a 25 MB-os
feltöltési darabokhoz igazodik (`TicketAttachment.UploadChunkSize`, `ImageConfiguration.ImageChunkSize`).

#### HTTPS a konténerben (opcionális)

Ha a TLS-nek magában a konténerben kell végződnie, adjon meg egy HTTPS figyelési címet, és a Kestrel szabványos
változóival egy tanúsítványt. Az indítószkriptek csak a 8080-as portot teszik elérhetővé, ezért kézi `docker run`
parancsot használjon (lásd [Futtatás a szkriptek nélkül](#futtatás-a-szkriptek-nélkül-kézi-telepítés)):

```bash
docker run -d --name worksmarthub --restart unless-stopped --stop-timeout 60 \
  -p 8443:8443 \
  -e HttpSettings__Urls__0=http://+:8080 -e HttpSettings__Urls__1=https://+:8443 \
  -e ASPNETCORE_Kestrel__Certificates__Default__Path=/certs/wsh.pfx \
  --env-file /opt/worksmarthub/worksmarthub.env \
  --mount type=bind,source=/opt/worksmarthub/wsh.pfx,target=/certs/wsh.pfx,readonly \
  -v worksmarthub-data:/app/data worksmarthub:23
```

Az `ASPNETCORE_Kestrel__Certificates__Default__Password=<pfx jelszó>` a `worksmarthub.env` fájlba kerüljön, ne a
parancssorba. A tanúsítványfájlt az uid 1001-nek olvasnia kell tudni.

#### Saját CA-tanúsítványok (kimenő TLS)

Az alkalmazás TLS-sel kapcsolódik kifelé: STARTTLS-es SMTP, LDAPS, Microsoft Entra ID és az OAuth szolgáltatók,
HashiCorp Vault, Számlázz.hu, Slack, Teams, a File Storage-ok objektumtárai, és a TLS-es külső adatbázis. Ha valamelyik
belső vagy önaláírt CA tanúsítványát mutatja, a kapcsolat addig sikertelen, amíg a konténer nem bízik meg abban a
CA-ban. Az alkalmazás az image operációs rendszerének tanúsítványtárát használja (`/etc/ssl/certs/ca-certificates.crt`).
A CA kétféleképpen adható hozzá:

**Származtatott image (az indítószkriptekkel működik).** Tegye a CA-fájlt (PEM, `.crt`) egy `Dockerfile` mellé:

```dockerfile
FROM worksmarthub:23
USER root
COPY internal-ca.crt /usr/local/share/ca-certificates/internal-ca.crt
RUN update-ca-certificates
USER appuser
```

```bash
docker build -t worksmarthub:23-ca .
sh worksmarthub-run.sh --version 23-ca --detach
```

Minden új verzióhoz készítse el újra.

**Csatolt tanúsítványcsomag (kézi `docker run`).** Fűzze hozzá a CA-t az image csomagjához, és az eredményt csak
olvashatóan csatolja a helyére:

```bash
docker run --rm --entrypoint cat worksmarthub:23 /etc/ssl/certs/ca-certificates.crt > ca-bundle.crt
cat internal-ca.crt >> ca-bundle.crt
# a docker run parancshoz:
#   --mount type=bind,source=/opt/worksmarthub/ca-bundle.crt,target=/etc/ssl/certs/ca-certificates.crt,readonly
```

Minden frissítéskor az új image-ből készítse el újra a csomagot, hogy a frissített nyilvános CA-k is benne legyenek.
Kubernetesen a chart elvégzi ezt az összefűzést (lásd [6. lépés](#6-lépés-saját-ca-tanúsítványok)). A CA-t a PKI
csapattól kérje; hogy egy szerver milyen láncot küld, így látható:
`openssl s_client -connect smtp.example.com:587 -starttls smtp -showcerts </dev/null`. Adatbázis-kapcsolatnál a
kapcsolati karakterláncban az ellenőrzés lazítható is (PostgreSQL `SSL Mode=Require`, SQL Server
`TrustServerCertificate=true`); a CA megbízhatóvá tétele a jobb megoldás.

#### Kimenő kapcsolatok

Az alkalmazás kliens is. Hogy mihez kapcsolódik, a beállításokon múlik:

| Cél | Port | Mikor |
|-----|------|-------|
| DNS | 53 | Mindig |
| Belső adatbázis | 5432 PostgreSQL, 1433 SQL Server, 3306 MySQL | SQLite-on kívül mindig |
| Redis vagy az adatbázis-cache | 6379, illetve az adatbázis portja | `CacheSettings.Type` `Redis` / `SqlServer` / `Postgres` / `MySql` |
| SMTP szerver | 587 (STARTTLS), 25 | `EmailSettings` és az e-mail értesítési csatornák. A 465-ös implicit TLS küldésre nem támogatott. |
| Slack (`slack.com`) | 443 | Slack értesítési csatornák |
| Microsoft Teams (Bot Framework, `smba.trafficmanager.net`, `login.microsoftonline.com`) | 443 | Teams értesítési csatornák |
| Számlázz.hu (`www.szamlazz.hu`) | 443 | Számlázás |
| File Storage hátterek: Amazon S3, Azure Blob, MinIO, Box, SharePoint, Google Cloud Storage | 443 (MinIO: a saját portja) | Az ezeken létrehozott File Storage-ok |
| HashiCorp Vault | a címe (gyakran 8200) | Vault szolgáltatás felhasználói katalógus |
| Microsoft Entra ID / Graph (`login.microsoftonline.com`, `graph.microsoft.com`) | 443 | `UserStore: AzureAD`, Microsoft OAuth |
| OAuth szolgáltatók (Okta, Google, egyedi) | 443 | `AuthType: OAuth` |
| LDAP / Active Directory tartományvezérlők | 389, 636 | `UserStore: LDAP` |
| AppleConnect | a címei | `AuthType: AppleConnect` |

A `UserStore: ActiveDirectory` és az `ActiveDirectory` bejelentkezés tartományba léptetett Windows szervert igényel, és
Linux-konténerben nem működik; ott `LDAP` (Active Directory változattal) vagy `AzureAD` használható.

### Az alkalmazás futtatása

#### Linux

```bash
cd docker/linux
sh worksmarthub-run.sh --version 23 --detach     # --detach nélkül előtérben fut, Ctrl+C állítja le
```

#### Windows

```powershell
cd docker\win
.\worksmarthub-run.ps1 -Version 23 -Detach
```

Nyissa meg a `http://<gép>:8080/` címet, és hozza létre az első felhasználót. `--version` / `-Version` nélkül a
szkriptek a `worksmarthub:latest` image-et futtatják; a `--image <hivatkozás>` / `-Image` bármely más image-et (pl.
registryből).

Amit az indítószkript tesz:

- ellenőrzi a Docker motort és az image-et, és nem indul el (78-as kilépési kód), ha azonos nevű konténer fut, vagy ha
  létezik egy leállított, `/app/data` kötet nélküli konténer (adatot tárolhat, lásd
  [Adatok kimentése egy konténerből](#adatok-kimentése-egy-konténerből)); a leállított, adatkötettel rendelkező
  konténer maradvány, és törli;
- `worksmarthub` nevű konténert indít (gépenként egy példány);
- a `worksmarthub-data` nevű kötetet a `/app/data` mappába csatolja (a Docker az első induláskor hozza létre, és
  belemásolja az image üres `FileStorage` és `Logs` mappáját);
- a 8080-as portot teszi elérhetővé, és beállítja a `HttpSettings__Urls__0=http://+:8080` értéket;
- csatolja az `appsettings.json`-t és átadja a `worksmarthub.env`-et, ha ezek a szkript mellett vannak;
- 60 másodpercet ad a leállásra (`--stop-timeout 60`): az alkalmazás 45 másodpercet hagy a háttérfolyamatainak, majd
  lezárja az adatbázist;
- előtérben a konténer leálláskor törlődik (`--rm`), és a szkript kivárja; `--detach` / `-Detach` esetén
  `unless-stopped` újraindítási szabállyal fut: a Docker összeomlás után és a démon indulásakor újraindítja, hacsak Ön
  nem állította le.

| Beállítás (környezeti változó) | Alapérték | Jelentés |
|--------------------------------|-----------|----------|
| `WSH_IMAGE` | `worksmarthub:latest` | Az image (a `--version` és az `--image` felülírja) |
| `WSH_CONTAINER_NAME` | `worksmarthub` | A konténer neve |
| `WSH_DATA_VOLUME` | `worksmarthub-data` | A nevesített kötet; Linuxon abszolút gépi mappa is lehet |
| `WSH_HTTP_PORT` | `8080` | A gépi port, vagy `cím:port`, pl. `127.0.0.1:8080`, hogy csak a gép loopback címén figyeljen |
| `WSH_DATA_MOUNT_OPTS` | (üres) | Csak Linuxon: további csatolási opciók, pl. `:Z` SELinuxos gépen |

A `--preflight-only` / `-PreflightOnly` csak az ellenőrzéseket futtatja, nem indít semmit. A konténer órája UTC, ezért
a háttérfolyamatok időpontjai (Admin felület, **App Konfiguráció > Háttérfolyamatok**) UTC szerintiek.

### Telepítés szolgáltatásként

#### Linux (systemd szolgáltatás)

A szkripteket olyan mappában tartsa, amelyet csak a root írhat, például `/opt/worksmarthub` (lásd
[A szkriptmappa védelme](#a-szkriptmappa-védelme)), az `appsettings.json` és a `worksmarthub.env` fájllal együtt:

```bash
sudo sh worksmarthub-service-install.sh --version 23
```

A szkript ellenőrzi a mappa jogosultságait, leállítja a futó szolgáltatást, lefuttatja az indítás előtti
ellenőrzéseket, megírja az `/etc/systemd/system/worksmarthub.service` fájlt, majd engedélyezi és elindítja. A
telepítéskor beállított `WSH_*` értékek (`sudo WSH_HTTP_PORT=8081 sh worksmarthub-service-install.sh ...`) bekerülnek a
unitba. A szolgáltatás:

- előtérben futtatja a szkriptmappából a `worksmarthub-run.sh` szkriptet (a mappát hagyja a helyén), a Docker
  szolgáltatás után (`docker.service`, snap csomagnál `snap.docker.dockerd.service`);
- kilépés után 10 másodperccel újraindítja, kivéve 78-as kilépési kódnál (sikertelen indítás előtti ellenőrzés, amelyen
  az újraindítás nem segít: `RestartPreventExitStatus=78`);
- `docker stop -t 60` paranccsal állítja le (`TimeoutStopSec=90`).

```bash
systemctl status worksmarthub      # állapot
systemctl restart worksmarthub     # újraindítás (az appsettings.json és a worksmarthub.env változásait is érvényesíti)
systemctl stop worksmarthub        # leállítás
journalctl -u worksmarthub -f      # a szolgáltatás naplója (a konténer konzolkimenete)
```

A `WSH_SERVICE_NAME` a szolgáltatás nevét változtatja meg. Frissítéshez futtassa újra a telepítőszkriptet az új
`--version` értékkel.

#### Windows (ütemezett feladat)

Rendszergazdaként, a szkriptmappában:

```powershell
.\worksmarthub-service-install.ps1 -Version 23
```

A szkript ellenőrzi a mappa jogosultságait, leállítja a meglévő feladatot és a konténerét, lefuttatja az indítás előtti
ellenőrzéseket, bekéri a feladatot futtató fiókot (a jelszót a Feladatütemező kapja meg, máshol nem tárolódik),
regisztrálja a `WorkSmartHub` feladatot, és elindítja. A feladat:

- nem interaktívan, a legmagasabb jogosultsággal futtatja a `worksmarthub-run.ps1 -Image <image>` parancsot a gép
  indulásakor (legfeljebb egy perc véletlen késleltetéssel) és minden bejelentkezéskor, mert a Docker Desktop csak egy
  felhasználó bejelentkezése után fut;
- bármeddig megvárja a Docker motort, és az indulási üzeneteit a szkript melletti `worksmarthub-task.log` fájlba írja;
- hiba esetén a Feladatütemező legfeljebb tízszer, percenként újraindítja.

A Docker Desktopnak automatikusan kell indulnia: **Settings > General > Start Docker Desktop when you sign in**.

```powershell
Get-ScheduledTask -TaskName WorkSmartHub | Get-ScheduledTaskInfo     # utolsó futás és eredménye
Stop-ScheduledTask -TaskName WorkSmartHub; docker stop worksmarthub  # leállítás
Start-ScheduledTask -TaskName WorkSmartHub                           # indítás
docker logs -f worksmarthub                                          # az alkalmazás naplója
```

**Csak a Docker újraindítási szabálya.** A `--detach` / `-Detach` elég, ha a Docker démon a gép indulásakor elindul. Ne
kombinálja a szolgáltatással vagy az ütemezett feladattal.

### A szolgáltatás eltávolítása

```bash
cd docker/linux
sudo sh worksmarthub-service-uninstall.sh
sudo sh worksmarthub-service-uninstall.sh --remove-image worksmarthub:23    # az image-et is törli
```

```powershell
cd docker\win
.\worksmarthub-service-uninstall.ps1                           # rendszergazdaként
.\worksmarthub-service-uninstall.ps1 -RemoveImage worksmarthub:23
```

A szolgáltatás vagy a feladat és a konténer törlődik. **Az adatkötet megmarad**, és a következő telepítés újra
használja. Az image-ek megmaradnak, hacsak meg nem nevez egyet, mert a helyben készült image-et nem lehet újra letölteni.
Az adatokat csak akkor törölje a `docker volume rm worksmarthub-data` paranccsal, ha mindet el akarja távolítani.

### Adatmegőrzés

#### Mi marad meg

Minden futás közbeni adat a `worksmarthub-data` kötetben van, amely a `/app/data` mappába csatolódik:

| Tartalom | A kötetben | Megjegyzés |
|----------|------------|------------|
| SQLite adatbázis (az alapértelmezett `InternalDbType: 0`, `Data Source=database.db;`) | `database.db`, `database.db-wal`, `database.db-shm` | A `/app/database.db` ide mutat. A `-wal` és `-shm` fájl az adatbázis része; mindig együtt másolja őket. |
| Fizikai File Storage (alapértelmezett gyökérútvonal: `FileStorage`) | `FileStorage/` | A `/app/FileStorage` ide mutat. A Physical háttérrel létrehozott File Storage-ok (Admin felület, **App Fájltárolók**) munkalap-mellékletei és alkatrészképei, valamint a File Storage nélküli munkajegyek számla PDF-jei (az automatikus **Számlák (automatikus)** tároló). |
| Naplófájlok | `Logs/` | A `/app/Logs` ide mutat. Napi fájlok, az Admin felületen is láthatók (**Naplófájlok**). A `docker logs` a konzolkimenetet mutatja. |
| Élő e-mail- és értesítéssablonok | `LiveEmailTemplates/`, `LiveNotificationTemplates/` | Induláskor jönnek létre; a hiányzó alapsablonok bekerülnek, a szerkesztett fájlokat semmi nem írja felül. |

A relatív útvonalak a köteten belülre mutatnak: `Data Source=database.db`, a `FileStorage` gyökérútvonal és a
`Logs/log-.txt`. A fizikai File Storage gyökérútvonala maradjon relatív (`FileStorage`, vagy más útvonal a `data/`
alatt): a konténer más részére mutató abszolút útvonal nem marad meg. Külső adatbázissal és külső File Storage
háttérrel a kötetben csak a naplók és a sablonok vannak.

Nincs a kötetben: az `appsettings.json` és a `worksmarthub.env` (a szkriptek mellett), valamint a licenc és a
bejelentkezési sütik kulcsai (az adatbázisban). Maga a konténer eldobható: bármikor törölhető és újra létrehozható, és
újraindítás, a gép újraindulása, összeomlás vagy frissítés soha nem visz el adatot.

**Sablon szerkesztése.** Másolja ki, szerkessze, másolja vissza. A következő e-mail már ezt használja, újraindítás
nélkül:

```bash
docker cp worksmarthub:/app/data/LiveEmailTemplates/ResetPassword.cshtml .
docker cp ResetPassword.cshtml worksmarthub:/app/data/LiveEmailTemplates/
```

A `docker cp` után a fájl a root tulajdonában marad; az alkalmazás csak olvassa. Az alapsablon visszaállításához
törölje a fájlt a mappából, és indítsa újra az alkalmazást.

#### A szkriptmappa védelme

A szolgáltatás minden induláskor rootként (Linux) vagy a legmagasabb jogosultsággal (Windows) futtatja az
indítószkriptet, és a mappában van az `appsettings.json` és a `worksmarthub.env` a titkos értékeivel. Aki ezeket a
fájlokat módosítani tudja, az irányítja az alkalmazást és a gépet, ezért a telepítőszkriptek **nem telepítenek, ha más
felhasználók írhatják a mappát**:

- **Linux:** a mappa, az indítószkript, az `appsettings.json` és a `worksmarthub.env` nem lehet a csoport vagy bárki
  által írható, és egyik szülőmappa sem lehet bárki által írható sticky bit nélkül. Root tulajdonú mappát használjon,
  például `/opt/worksmarthub` (`sudo chown -R root:root /opt/worksmarthub && sudo chmod -R go-w /opt/worksmarthub`);
  utána az `appsettings.json`-t adja az uid 1001 tulajdonába, ha az alkalmazásnak bele kell írnia az új kulcsokat.
  Soha ne telepítsen a `/tmp` mappából.
- **Windows:** a mappát és a fájlokat csak a Rendszergazdák, a SYSTEM és a telepítő felhasználó írhatja. A közvetlenül
  a `C:\` alatt létrehozott mappa örökli a *Hitelesített felhasználók: Módosítás* jogot, ezért elutasítja; előbb
  távolítsa el az öröklött jogokat:
  `icacls "C:\WorkSmartHub" /inheritance:r /grant:r "*S-1-5-32-544:(OI)(CI)F" "*S-1-5-18:(OI)(CI)F"`.

Az uid 1001 egy Linuxos gépen rendes helyi fiók is lehet (`getent passwd 1001`); az a fiók ekkor olvashatja az
alkalmazás tulajdonában lévő fájlokat, éppúgy, mint az alkalmazás.

#### Frissítés

1. Készítse el vagy töltse be az új image-et (`worksmarthub:24`), és készítsen mentést (lásd lent).
2. Indítsa el az új image-et ugyanazon a köteten:
   - Linux szolgáltatás: `sudo sh worksmarthub-service-install.sh --version 24`;
   - Windows feladat: `.\worksmarthub-service-install.ps1 -Version 24`;
   - kézi indítás: `docker stop worksmarthub`, majd `sh worksmarthub-run.sh --version 24 --detach`.
3. Az új verzió induláskor migrálja az adatbázist (a `docker logs -f worksmarthub` kimenetében `Migrating database` és
   `Migration complete` látható), és írható `appsettings.json` esetén beleírja az új beállításkulcsokat. A felhasználók
   bejelentkezve maradnak.

Korábbi verzióra visszatérni a frissítés előtt készült mentés visszaállításával lehet: az adatbázis visszafelé soha nem
migrálódik. Az új verzió változásnaplójában nézze meg, kell-e valamilyen lépés. `worksmarthub:latest` esetén
(`--version` nélkül) egy új build áthelyezi a címkét, és a szolgáltatás újraindítása az új image-et indítja.

#### Mentés és visszaállítás

Előbb állítsa le az alkalmazást: a write-ahead-log módú SQLite adatbázis futás közbeni másolata következetlen lehet. A
segédkonténer az alkalmazás image-ét használja, hálózat nélkül. Az archívum hitelesítő adatokat tartalmaz, ezért csak
Ön olvashatja.

```bash
# Linux: előbb leállítás (amelyik vonatkozik)
sudo systemctl stop worksmarthub      # szolgáltatás
docker stop worksmarthub              # kézi indítás
docker run --rm --network none -v worksmarthub-data:/app/data -v "$PWD":/backup --user "$(id -u):$(id -g)" \
  --entrypoint sh worksmarthub:23 -c 'umask 077; tar czf "/backup/worksmarthub-data-$(date +%F).tgz" -C /app/data .'
sudo systemctl start worksmarthub     # vagy futtassa újra az indítószkriptet
```

```powershell
# Windows: előbb leállítás (amelyik vonatkozik), olyan mappában, amelyet csak a rendszergazdák olvashatnak
Stop-ScheduledTask -TaskName WorkSmartHub; docker stop worksmarthub     # feladat
docker stop worksmarthub                                                # kézi indítás
docker run --rm --network none -v worksmarthub-data:/app/data -v "${PWD}:/backup" `
  --entrypoint tar worksmarthub:23 czf "/backup/worksmarthub-data-$(Get-Date -Format yyyy-MM-dd).tgz" -C /app/data .
Start-ScheduledTask -TaskName WorkSmartHub                              # vagy futtassa újra az indítószkriptet
```

**Visszaállítás** (leállított alkalmazással; a teljes kötetet lecseréli; a parancs törlés előtt végigolvassa az
archívumot). Windowson `-v "${PWD}:/backup:ro"` kell, a sortörésekhez pedig backtick:

```bash
docker run --rm --network none -u 0 --cap-drop ALL --cap-add CHOWN --cap-add DAC_OVERRIDE --cap-add FOWNER \
  -v worksmarthub-data:/app/data -v "$PWD":/backup:ro --entrypoint sh worksmarthub:23 \
  -c 'tar tzf /backup/worksmarthub-data-YYYY-MM-DD.tgz >/dev/null && find /app/data -mindepth 1 -delete && tar xzf /backup/worksmarthub-data-YYYY-MM-DD.tgz -C /app/data && chown -R 1001:1001 /app/data'
```

A segédkonténer csak azért fut rootként a konténeren belül, hogy olvassa az archívumot és az alkalmazás felhasználójának
adja a fájlokat, hálózat nélkül és csak a szükséges három képességgel. Csak saját készítésű archívumot állítson vissza.
Az `appsettings.json` és a `worksmarthub.env` fájlt külön mentse; külső adatbázist a saját eszközeivel mentsen.

> **A mentések hitelesítő adatokat tartalmaznak.** Az adatbázis a File Storage-kulcsokat, az e-mail-, értesítési és
> Számlázz.hu hitelesítő adatokat és a bejelentkezési sütik kulcsait olyan formában tárolja, amelyet az alkalmazás más
> adat nélkül is használni tud; az `appsettings.json` az aláírókulcsokat tartalmazza. A mentéseket korlátozott
> jogosultsággal és titkosítva tárolja, az ideiglenes másolatokat törölje.

#### A kötet védelme

- A nevesített kötet túléli a `docker stop`, `docker rm`, `docker rmi` parancsot, az image frissítését és az
  eltávolítószkripteket.
- Amíg a konténer le van állítva és törölve, a kötet használaton kívülinek számít: 23-asnál régebbi Docker Engine-en a
  `docker volume prune` és a `docker system prune --volumes` törli a használaton kívüli nevesített köteteket, 23-astól a
  `docker volume prune -a` is. A Docker Desktop **Clean / Purge data** és **Reset to factory defaults** művelete minden
  kötetet töröl. Ezek előtt készítsen mentést.
- Az összes alkalmazásadat szándékos törlése: `docker volume rm worksmarthub-data`, leállított alkalmazással.

#### Alternatíva: gépen lévő mappa a nevesített kötet helyett (Linux)

Ha az adatokat saját kezelésű mappában tartaná (külön lemezen, meglévő mentési feladat alatt), hozza létre **helyi
fájlrendszeren** (ne NFS-en vagy SMB-n: az SQLite write-ahead logjának helyi zárolás és osztott memória kell) mindkét
almappával, és adja az uid 1001 tulajdonába:

```bash
sudo mkdir -p /srv/worksmarthub/FileStorage /srv/worksmarthub/Logs
sudo chown -R 1001:1001 /srv/worksmarthub
sudo chmod 700 /srv/worksmarthub
sudo WSH_DATA_VOLUME=/srv/worksmarthub sh worksmarthub-service-install.sh --version 23
```

Az abszolút `WSH_DATA_VOLUME` bind mountként csatolódik. Az indítószkript ellenőrzi, hogy a mappa és mindkét almappa
létezik, és az uid 1001 a tulajdonos, különben nem indul el (az almappák nélkül a File Storage és a naplófájlok nem
működnének). 700-as móddal az indításnak rootként kell futnia (a szolgáltatás így fut). SELinuxos gépen állítsa be a
`WSH_DATA_MOUNT_OPTS=:Z` értéket is. Windowson nem ajánlott: az NTFS-ről csatolt mappa lassú, és az SQLite zárolása
rajta megbízhatatlan.

#### Több csomópont és magas rendelkezésre állás

Az adatkötet egy Docker gépen van. Több alkalmazáscsomópont (terheléselosztott gépek, Kubernetes replikák) akkor
használhat közös adatbázist, ha mindez teljesül:

| Rész | Több csomóponthoz | Több csomóponthoz nem |
|------|-------------------|-----------------------|
| Adatbázis | SQL Server, PostgreSQL, MySQL | SQLite |
| Cache | `Redis` vagy az adatbázis-cache (`SqlServer`, `Postgres`, `MySql`) | `InMemory` (a jogosultságok, a licencállapot, a törzsadatlisták és az OAuth bejelentkezési állapot csomópontonként eltérne; az alkalmazás induláskor naplózza ezt a tanácsot) |
| File Storage | S3, Azure Blob, MinIO, Box, SharePoint, Google Cloud Storage, vagy egy közös hálózati kötet | Physical helyi lemezen |
| Beállítások | minden csomóponton ugyanazok az `appsettings.json` értékek, az aláírókulcsok és a `PublicBaseUrl` is | |

Ekkor:

- **Az adatbázis-migrációk** induláskor csomópontok közötti zárolás alatt futnak (PostgreSQL advisory lock, SQL Server
  application lock, MySQL named lock): egy csomópont migrál, a többi vár, majd nem talál teendőt, új adatbázison is.
- **A munkamenetek** minden csomóponton érvényesek (a kulcsok az adatbázisban vannak).
- **Az ütemezett háttérfolyamatok minden alkalommal egyszer futnak az összes csomópont közül:** futás előtt a csomópont
  lefoglalja az alkalmat az adatbázisban, így az e-mailek, a Teams- és Slack-üzenetek és a Számlázz.hu hívások nem
  ismétlődnek. A **Run-once claim cleanup** folyamat törli a régi foglalásokat (alapértelmezésben bekapcsolva, naponta
  04:15-kor, 7 napot tart meg). Több csomóponton legfeljebb 1 napos időközöket használjon, és tartsa szinkronban az
  órákat.
- **Az Admin felületen tett beállításváltozások** a `ConfigSync` időközön (10 másodperc) belül minden csomóponthoz
  eljutnak.
- Az objektumtárak hitelesítő adatainak az olvasás és írás mellett **listázási és törlési** jog is kell, és minden
  telepítésnek saját bucket vagy előtag kell: az adatbázis másolata (visszaállított mentés, tesztkörnyezet) megtartja a
  File Storage definíciókat a hitelesítő adataikkal, ezért élesítése előtt irányítsa őket máshová.
- **Az élő sablonok** csomópontonként külön vannak, hacsak az adatmappa nem közös; a szerkesztett sablont másolja minden
  csomópontra.

#### Adatok kimentése egy konténerből

A kötet nélkül, kézzel indított konténer a konténeren belül tartja az adatbázist és a fájlokat, és a konténer törlése
ezeket is törli. Az indítószkript nem indul el, amíg létezik egy leállított, `/app/data` kötet nélküli `worksmarthub`
nevű konténer, és ilyet soha nem töröl. Előbb másolja az adatokat a kötetbe:

```bash
docker stop worksmarthub                        # ha fut; egy --rm kapcsolóval indított konténert ez töröl, lásd lent
mkdir -m 700 wsh-migrate
docker cp worksmarthub:/app/data/. wsh-migrate/
docker run --rm --network none -u 0 --cap-drop ALL --cap-add CHOWN --cap-add DAC_OVERRIDE --cap-add FOWNER \
  -v worksmarthub-data:/app/data -v "$PWD/wsh-migrate":/migrate:ro --entrypoint sh worksmarthub:23 \
  -c 'cp -a /migrate/. /app/data/ && mkdir -p /app/data/FileStorage /app/data/Logs && chown -R 1001:1001 /app/data'
```

- Az image mindent a `/app/data` alatt tart, így a `docker cp` mindent kimásol. A régebbi, e mappa nélküli image-ek a
  fájlokat itt tartották: `/app/database.db` (a `-wal` fájllal), `/app/FileStorage`, `/app/Logs`,
  `/app/wwwroot/LiveEmailTemplates`, `/app/wwwroot/LiveNotificationTemplates`: ezeket másolja a `wsh-migrate` mappába
  (az adatbázisfájlokat `docker cp -L` paranccsal).
- **Egy `--rm` kapcsolóval indított, futó konténer** leálláskor törlődik. Futás közben másoljon belőle, egy következetes
  pillanatkép után: `docker commit worksmarthub wsh-rescue` (rövid időre megállítja), `docker create --name wsh-rescue-c
  wsh-rescue`, és a `docker cp` parancsot a `wsh-rescue-c` konténerre futtassa.
- Indítsa el az új telepítést, ellenőrizze az adatokat, majd törölje a `wsh-migrate` mappát (hitelesítő adatokat
  tartalmaz), a mentő konténert és image-et, végül a régi konténert (`docker rm worksmarthub`).

Ha inkább üres adatbázissal indulna, a régi konténert törölje maga.

### Futtatás a szkriptek nélkül (kézi telepítés)

Ha az Önöknél érvényes szabályok nem engedik a szkripteinket, sima Docker parancsokkal ugyanez elérhető. A lényeg: fix
konténernév, az adatkötet, a gépről csatolt beállítások és egy újraindítási mechanizmus.

#### 1. lépés: A gép előkészítése

1. Telepítse a Dockert (Linuxon Docker Engine, Windowson Docker Desktop), és készítse el vagy töltse be az image-et.
2. Hozzon létre egy mappát a beállításoknak, amelyet csak a rendszergazdák írhatnak, például `/opt/worksmarthub`
   (root tulajdonú, 755-ös mód). Ebbe kerül az `appsettings.json` (opcionális; az uid 1001 tulajdonában, 600-as móddal,
   ha az alkalmazásnak bele kell írnia az új kulcsokat) és a `worksmarthub.env` (600-as mód).
3. Hozza létre egyszer az adatkötetet: `docker volume create worksmarthub-data`.

#### 2. lépés: A konténer indítása

Linux:

```bash
docker run -d --name worksmarthub --restart unless-stopped --stop-timeout 60 \
  -p 8080:8080 -e HttpSettings__Urls__0=http://+:8080 \
  --mount type=bind,source=/opt/worksmarthub/appsettings.json,target=/app/appsettings.json \
  --env-file /opt/worksmarthub/worksmarthub.env \
  -v worksmarthub-data:/app/data \
  worksmarthub:23
```

Windows (PowerShell):

```powershell
docker run -d --name worksmarthub --restart unless-stopped --stop-timeout 60 `
  -p 8080:8080 -e HttpSettings__Urls__0=http://+:8080 `
  --mount "type=bind,source=C:\Users\<admin>\WorkSmartHub\appsettings.json,target=/app/appsettings.json" `
  --env-file "C:\Users\<admin>\WorkSmartHub\worksmarthub.env" `
  -v worksmarthub-data:/app/data `
  worksmarthub:23
```

| Kapcsoló | Szerepe |
|----------|---------|
| `-d` | Háttérben fut. |
| `--name worksmarthub` | Fix név: véletlenül nem indul második példány, és a lenti parancsok így érik el. |
| `--restart unless-stopped` | A Docker összeomlás után és a démon indulásakor (a gép újraindulásakor) újraindítja, hacsak Ön nem állította le. |
| `--stop-timeout 60` | A `docker stop` legfeljebb 60 másodpercet vár: az alkalmazás 45 másodpercet hagy a háttérfolyamatainak, majd lezárja az adatbázist. |
| `-p 8080:8080` | A webes felület a gép 8080-as portján (az első szám; csak loopbackhez `127.0.0.1:8080:8080`). |
| `-e HttpSettings__Urls__0=http://+:8080` | A figyelési cím a konténerben; a port a `-p` konténer felőli oldala. |
| `--mount type=bind,...appsettings.json` | Opcionális: a saját beállításfájl a gépről. Nélküle a gyári fájl érvényes. |
| `--env-file ...` | Opcionális: beállítások és titkos értékek környezeti változóként; felülírják a fájlt. |
| `-v worksmarthub-data:/app/data` | A tartós adatkötet. |

#### 3. lépés: Indulás a gép indításakor

**Linux, A változat (a legegyszerűbb): a Docker újraindítási szabálya.** A `--restart unless-stopped` kapcsolóval és
induláskor engedélyezett Docker szolgáltatással (`sudo systemctl enable docker`) nincs más teendő.

**Linux, B változat: systemd unit.** Ne kombinálja a `--restart unless-stopped` kapcsolóval; ekkor a systemd kezeli az
életciklust. Hozza létre az `/etc/systemd/system/worksmarthub.service` fájlt:

```ini
[Unit]
Description=WorkSmartHub
After=docker.service
Requires=docker.service

[Service]
TimeoutStartSec=0
TimeoutStopSec=90
Restart=always
RestartSec=10
ExecStartPre=-/usr/bin/docker rm worksmarthub
ExecStart=/usr/bin/docker run --rm --name worksmarthub --stop-timeout 60 -p 8080:8080 -e HttpSettings__Urls__0=http://+:8080 --mount type=bind,source=/opt/worksmarthub/appsettings.json,target=/app/appsettings.json --env-file /opt/worksmarthub/worksmarthub.env -v worksmarthub-data:/app/data worksmarthub:23
ExecStop=/usr/bin/docker stop -t 60 worksmarthub

[Install]
WantedBy=multi-user.target
```

Az `ExecStart` előtérben futtatja a konténert (`-d` nélkül), hogy a systemd követni tudja; a `--rm` törli a leállt
konténert, így a következő indításkor nincs névütközés, az `ExecStartPre` pedig eltakarítja a szabálytalan leállás utáni
maradványt (ártalmatlanul hibát ad, és futó konténert soha nem állít le). A `docker` program valódi útvonalát használja
(`command -v docker`); snap csomagnál az `After=` és a `Requires=` sorban `snap.docker.dockerd.service` álljon. Ezután:

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now worksmarthub
journalctl -u worksmarthub -f
```

**Windows, A változat (ajánlott): a Docker újraindítási szabálya.** Kapcsolja be a **Start Docker Desktop when you sign
in** beállítást; a démon indulásakor minden `--restart unless-stopped` kapcsolóval indított konténert újraindít. A
Docker Desktop egy felhasználó bejelentkezése előtt nem fut.

**Windows, B változat: ütemezett feladat**, amely megvárja a motort, és elindítja a meglévő konténert (a Feladatütemező
nem próbálja újra a hibával kilépő programot, a Docker Desktopnak pedig a bejelentkezés után egy-két perc kell):

```powershell
$command = 'while ($true) { docker version *> $null; if ($LASTEXITCODE -eq 0) { break }; Start-Sleep -Seconds 15 }; docker start worksmarthub'
$action   = New-ScheduledTaskAction -Execute "powershell.exe" -Argument "-NoProfile -NonInteractive -Command `"$command`""
$triggers = @((New-ScheduledTaskTrigger -AtStartup), (New-ScheduledTaskTrigger -AtLogOn))
$settings = New-ScheduledTaskSettingsSet -StartWhenAvailable -ExecutionTimeLimit (New-TimeSpan -Hours 1)
Register-ScheduledTask -TaskName "WorkSmartHub" -Action $action -Trigger $triggers -Settings $settings
```

A feladat a regisztráló felhasználóként fut, akinek a `docker-users` csoport tagjának kell lennie. A `docker start` nem
csinál semmit, ha a konténer már fut.

#### 4. lépés: Mindennapi parancsok

| Feladat | Parancs |
|---------|---------|
| Naplók | `docker logs -f worksmarthub` |
| Leállítás / indítás | `docker stop worksmarthub` (legfeljebb 60 mp-et vár) / `docker start worksmarthub` |
| Az `appsettings.json` változásának érvényesítése | `docker restart worksmarthub` |
| A `worksmarthub.env` változásának érvényesítése | törlés és újraindítás (`docker stop worksmarthub && docker rm worksmarthub`, majd a 2. lépés): a környezeti változók a konténer létrehozásakor rögzülnek |
| Frissítés | `docker stop worksmarthub && docker rm worksmarthub`, majd a 2. lépés az új image-dzsel. A kötet megmarad. |
| Mentés / visszaállítás | Lásd [Mentés és visszaállítás](#mentés-és-visszaállítás). |
| Eltávolítás | `docker stop worksmarthub && docker rm worksmarthub`; ha az image-nek is mennie kell, `docker rmi worksmarthub:23`. A kötet megmarad. |

---

## Kubernetes

A `kubernetes-helm-chart` mappában van a `worksmarthub` Helm chart (chartverzió 1.0.0). Minden beállítás leírása a
[`kubernetes-helm-chart/values.yaml`](https://github.com/WorkWise-Solutions/WorkSmartHub-Docker-Kubernetes/blob/main/kubernetes-helm-chart/values.yaml) fájlban van.

### Kubernetes előfeltételek

- Egy futó fürt (EKS, AKS, GKE, saját üzemeltetésű; helyi teszthez minikube) és hozzá beállított `kubectl`.
- Helm 3.
- Az alkalmazás image-e ott, ahonnan a csomópontok elérik: a csomópont Docker démonjában építve (minikube), a
  csomópontokra betöltve, vagy egy, a fürt által elérhető registrybe feltöltve.
- Alapértelmezett StorageClass (vagy egy megnevezett) a PersistentVolumeClaim-ekhez.
- **ingress-nginx** vezérlő a chart Ingress-éhez; más vezérlőnél vagy service mesh esetén kapcsolja ki az Ingress-t
  ([8. lépés](#8-lépés-service-típusa-és-ingress)).
- Kimenő hozzáférés a Docker Hubhoz a `postgres:16-alpine`, `redis:7-alpine` és `busybox:1.38.0` image-hez, vagy ezek
  másolata a saját registryben ([Elszigetelt és korlátozott hálózatok](#elszigetelt-és-korlátozott-hálózatok)).

### Gyors kezdés

A chart alapértékeivel egyetlen fájl szerkesztése nélkül teljes telepítés indul:

```bash
bash build/build-image.sh --version 23 --minikube      # vagy töltse fel az image-et egy, a fürt által elérhető registrybe
helm install worksmarthub ./kubernetes-helm-chart --set app.image.tag=23
kubectl get pods -n worksmarthub -w
kubectl port-forward -n worksmarthub svc/worksmarthub 8080:80      # majd http://localhost:8080/
```

A `worksmarthub` névtérbe telepít:

| Összetevő | Mi ez |
|-----------|-------|
| Alkalmazás | Egy `worksmarthub:<címke>` pod `GET /health` próbákkal, `appsettings.json` ConfigMapből, adatkötet a `/app/data` mappában |
| Adatkötet | A `worksmarthub-data-claim` PersistentVolumeClaim (5 Gi, ReadWriteOnce, alapértelmezett StorageClass): fizikai File Storage, naplók, élő sablonok, és SQLite esetén az adatbázisfájl |
| PostgreSQL | `postgres:16-alpine`, egy replika, `postgres-data-claim` PVC (5 Gi). A chart `appsettings.json`-ja ezt választja (`InternalDbType: 2`, `Server=db`) |
| Redis | `redis:7-alpine`, egy replika, csak cache. A chart `appsettings.json`-ja ezt választja (`CacheSettings.Type: Redis`, `cache:6379`) |
| Ingress | ingress-nginx vezérlőhöz, feltöltési korlátokkal ([8. lépés](#8-lépés-service-típusa-és-ingress)) |
| NetworkPolicy-k | A beépített PostgreSQL-hez és Redishez csak a névtér podjai kapcsolódhatnak |

> **Változtassa meg az adatbázis jelszavát.** A beépített PostgreSQL a nyilvános alapértelmezett `user` felhasználóval
> és `password` jelszóval indul. Bármilyen, nem eldobható próbatelepítés előtt adjon meg sajátot az
> `internalDatabase.settings` alatt, és ugyanezt a `kubernetes-helm-chart/appsettings.json` kapcsolati
> karakterláncában (vagy egy Secretben), lásd [Adatbázisjelszó](#adatbázisjelszó). Később megváltoztatni csak az
> adatbázison belüli lépéssel lehet.

Ez a beállítás első telepítéshez és kipróbáláshoz való. Élesítés előtt állítsa be az aláírókulcsokat és a
`PublicBaseUrl` értéket is ([7. lépés](#7-lépés-hitelesítő-adatok-biztonságos-kezelése)), és menjen végig az
[Élesítési ellenőrzőlistán](#élesítési-ellenőrzőlista).

A módosításait saját values fájlban tartsa (`-f sajat-values.yaml`), és ezt őrizze meg a frissítésekhez; a lenti
lépések a kulcsokat mutatják.

### Hálózati és kapcsolódási követelmények

**A bejövő forgalmat** az Ingress (vagy a Service) kezeli: amint 80/443-on elérhetővé teszi az alkalmazást, a
felhasználók elérik. **A kimenő kapcsolatokat** az alkalmazás kezdeményezi; mindegyikhez két dolog kell: *hova
kapcsolódjon* (alkalmazásbeállítás: `appsettings.json`, Secretek vagy az Admin felület) és *elérheti-e a pod* (platform
beállítás, csak akkor kell, ha a kimenő forgalom korlátozott, vagy a cél olyan hálózaton van, amelyet a fürt nem ér el,
például egy helyi SMTP relay vagy LDAP szerver).

**Bejövő:**

| Port | Forrás | Szerepe |
|------|--------|---------|
| 80 / 443 | A felhasználók böngészői, API kliensek, a terheléselosztó | A portál és a REST API, ugyanabból a konténerből és portról |

A TLS az Ingress-en vagy a terheléselosztón végződik; a konténer a 8080-as porton figyel (`HttpSettings.Urls`), a
Service a 80-ason.

**Kimenő:** a [Kimenő kapcsolatok](#kimenő-kapcsolatok) táblázata érvényes, és image letöltéskor a konténer-registry
(443). A fürtön belüli szolgáltatásokat (a beépített adatbázist és cache-t) Service DNS-en éri el (`db:5432`,
`cache:6379`), ez a forgalom nem hagyja el a fürtöt. A pod külső célok felé irányuló forgalma a **csomópont** címére
fordítódik (source NAT), így a külső tűzfalak a csomópont IP-jét látják: a csomópontoknak (vagy egy külön
csomópontkészletnek, [9. lépés](#9-lépés-replikák-és-skálázás)) engedélyezze az egyes célokat.

**A kimenő forgalom korlátozása (opcionális).** NetworkPolicy-képes CNI-vel (Calico, Cilium) a névtérre
alapértelmezett tiltó kimenő szabály tehető, az alkalmazás podjaira pedig engedélyező lista. Az engedélyező listának
**mindent tartalmaznia kell, amit az alkalmazás használ**, különben leáll a működése:

```yaml
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: default-deny-egress
  namespace: worksmarthub
spec:
  podSelector: {}
  policyTypes: [Egress]
  egress: []
---
apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: worksmarthub-app-egress
  namespace: worksmarthub
spec:
  podSelector:
    matchLabels:
      app: worksmarthub-pod
  policyTypes: [Egress]
  egress:
  - ports:                                   # DNS
    - { protocol: UDP, port: 53 }
    - { protocol: TCP, port: 53 }
  - to:                                      # beépített PostgreSQL
    - podSelector: { matchLabels: { app: db, wsh-internal-service: db } }
    ports:
    - { protocol: TCP, port: 5432 }
  - to:                                      # beépített Redis
    - podSelector: { matchLabels: { app: cache, wsh-internal-service: cache } }
    ports:
    - { protocol: TCP, port: 6379 }
  - ports:                                   # Számlázz.hu, Slack, Teams, Entra ID, OAuth, objektumtárak
    - { protocol: TCP, port: 443 }
  - ports:                                   # SMTP (STARTTLS)
    - { protocol: TCP, port: 587 }
  # Vegye fel, amire a beállításainak szüksége van: külső adatbázis (1433/3306/5432) vagy cache (6379) ipBlock-ként,
  # LDAP (389/636), HashiCorp Vault (8200), SMTP a 25-ös porton, egy MinIO port.
```

Az alapértelmezett tiltó szabály a beépített PostgreSQL és Redis podjaira is vonatkozik, amelyeknek nincs szükségük
kimenő forgalomra. A NetworkPolicy névtérre szól; ha a fürt minden más alkalmazását távol kell tartani egy céltól, a
tűzfalszabályt egy külön csomópontkészletre szűkítse.

### 1. lépés: Névtér

```yaml
nameSpace: "worksmarthub"
installNameSpace: True
```

`installNameSpace: True` esetén a chart hozza létre a névteret, és a `helm uninstall` mindennel együtt törli. Ha a
névtér (és a benne létrehozott Secretek) a release-től függetlenül kell maradjon, hozza létre maga, és állítsa be az
`installNameSpace: False` értéket:

```bash
kubectl create namespace worksmarthub
helm install worksmarthub ./kubernetes-helm-chart --set app.image.tag=23 --set installNameSpace=False
```

Az útmutató parancsai a `worksmarthub` névteret használják; ha megváltoztatja, helyettesítse a sajátjával.

### 2. lépés: Az alkalmazás image-e

```yaml
app:
  image:
    repository: "worksmarthub"
    tag: "23"               # kötelező
  imagePullSecrets: []
global:
  imagePullPolicy: "IfNotPresent"
```

- Az `app.image.tag` **kötelező**; nélküle a chart nem renderel. Egy `sha256:...` alakú címke digestként szerepel
  (`repository@sha256:...`).
- Az `imagePullPolicy: IfNotPresent` (a chart minden konténerére) a csomóponton már meglévő image-et használja. A
  helyben készült image-nek erre szüksége van: `Always` esetén a kubelet registryt kérdez, és a pod `ErrImagePull`
  hibával leáll. A másik oldala: **egy csomópont a már meglévő címkét soha nem tölti le újra**, ezért minden buildnek
  új címke kell (a build szkript a verziót adja címkének), és a frissítés az új címkét állítja be. A `latest` címkét ne
  telepítse.
- **Az image eljuttatása a csomópontokra:** minikube-on annak démonjában építse (`build-image.sh --minikube`); más
  fürtön registry nélkül töltse be a tar fájlt minden csomópontra a csomópont konténer-futtatójával; registryvel töltse
  fel az image-et, és állítsa be az `app.image.repository` értéket (pl. `registry.example.com/worksmarthub`).
- **Privát registry:** hozzon létre egy pull secretet, és hivatkozzon rá:
  ```bash
  read -rs REGISTRY_PASSWORD      # gépelje be; nem jelenik meg és nem tárolódik
  kubectl create secret docker-registry regcred -n worksmarthub --docker-server=registry.example.com \
    --docker-username=<felhasználó> --docker-password="$REGISTRY_PASSWORD"
  ```
  ```yaml
  app:
    imagePullSecrets:
    - name: regcred
  ```

### 3. lépés: Belső adatbázis

#### A beépített PostgreSQL (alapértelmezés)

`postgres:16-alpine`, egy replika, a `postgres-data-claim` PVC-n (`internalDatabase.persistence`: 5 Gi, ReadWriteOnce,
alapértelmezett StorageClass), a nem root 70-es felhasználóként, `fsGroup: 70` beállítással. A Service-e `db:5432`, és
a chart `appsettings.json`-ja az `internalDatabase.settings` értékeivel kapcsolódik hozzá. Újraütemezés után is
megmarad, de egyetlen példány átállás (failover) nélkül, és a podja minden újraindításakor rövid ideig nem érhető el
(`Recreate` stratégia).

- `internalDatabase.persistence.storageClass`: tartós blokktároló osztály (`gp3`, `managed-csi`, `premium-rwo`);
  `existingClaim` saját kezelésű PVC-hez; `enabled: false` `emptyDir`-hez (az adat a poddal elvész; csak eldobható
  tesztekhez).
- Az `internalDatabase.fixDataPermissions: True` egy egyszeri, rootként futó init konténert ad hozzá, amely `chown`-nal
  rendbe teszi az adatmappát. Csak olyan tárolóhoz, amely figyelmen kívül hagyja az `fsGroup`-ot, és a kötetet root
  tulajdonban, szigorú jogokkal hozza létre; szabályozott fürtön hagyja kikapcsolva.
- `internalDatabase.image`: másolat a saját registryben vagy újabb címke. A konténerek uid 70-ként futnak, ez az Alpine
  változat postgres felhasználója; Debian alapú image-hez (uid 999) a `runAsUser` értéket a
  `templates/internaldb.yaml` fájlban és a `wait-for-db` init konténerben is módosítani kell. Egy meglévő adatbázis
  **főverziójának cseréje** nem helyben végezhető: a PostgreSQL nem indul el más főverzió adatmappáján, ezért mentés és
  visszatöltés kell.

#### Adatbázisjelszó

A PostgreSQL az **első** indulásakor (üres adatmappánál) az `internalDatabase.settings` értékeiből hozza létre a
felhasználót, a jelszót és az adatbázist (`user` / `password` / `worksmarthub`), és a chart `appsettings.json`-ja
ugyanezekkel kapcsolódik:

```json
"InternalDbType": 2,
"InternalDb": "Server=db;Port=5432;Database=worksmarthub;User id=user;Password=password;",
```

Ezek az alapértékek nyilvánosak. Az első telepítés előtt mindkét helyen adjon meg sajátot:

```yaml
internalDatabase:
  settings:
    userName: wsh
    password: <erős jelszó>
    dbName: worksmarthub
```

és a `kubernetes-helm-chart/appsettings.json` fájlban
`"InternalDb": "Server=db;Port=5432;Database=worksmarthub;User id=wsh;Password=<ugyanaz a jelszó>;"`, vagy inkább egy
Secret a `ConnectionStrings__InternalDb` kulccsal ([7. lépés](#7-lépés-hitelesítő-adatok-biztonságos-kezelése)); a
`values.yaml` és a ConfigMap egyszerű szövegként tárolja az értékeket.

Az `internalDatabase.settings` későbbi módosítása a meglévő adatbázist nem változtatja meg. Egy telepítés jelszavának
cseréjéhez előbb az adatbázisban változtassa meg, utána a values fájlban és a kapcsolati karakterláncban, majd
`helm upgrade`:

```bash
kubectl exec -n worksmarthub deploy/db-deployment -- psql -U user -d worksmarthub -c "ALTER USER \"user\" PASSWORD '<új jelszó>';"
```

Az alkalmazás podja a `wait-for-db` init konténerben várja meg a PostgreSQL-t. Ez a `values.yaml` adataival jelentkezik
be, és a naplójába írja, ha a PostgreSQL elutasítja őket (`kubectl logs -n worksmarthub <app pod> -c wait-for-db`); az
alkalmazás ekkor is elindul, az `appsettings.json` vagy egy Secret kapcsolati karakterláncával.

#### Külső adatbázis (élesre ajánlott)

Állítsa be az `internalDatabase.skipDeployment: True` értéket, és a kapcsolatot egy Secretben vagy a chart
`appsettings.json` fájljában adja meg. Felügyelt szolgáltatás (Amazon RDS, Azure Database, Google Cloud SQL) vagy saját
szerver:

| Adatbázis | `InternalDbType` | `InternalDb` példa |
|-----------|------------------|--------------------|
| SQL Server | 1 | `Data Source=sql.example.com;Initial Catalog=wsh;User id=wsh;Password=...;Connection Timeout=60;Encrypt=True;TrustServerCertificate=False;` |
| PostgreSQL | 2 | `Server=pg.example.com;Port=5432;Database=wsh;User id=wsh;Password=...;SSL Mode=Require;` |
| MySQL | 3 | `Server=mysql.example.com;Port=3306;Database=wsh;Uid=wsh;Pwd=...;SslMode=Required;` (és `MySqlServerVersion`, pl. `8.0.28`) |

- A `Schema` SQL Serveren és PostgreSQL-en egy sémába teszi a táblákat; MySQL-nél (és SQLite-nál) üres kell legyen.
- Az alkalmazás adatbázis-felhasználójának táblák létrehozására és módosítására is jogot kell adni: a migrációk minden
  induláskor futnak.
- Adatbázismotorok közötti átállás nincs beépítve; egy meglévő telepítés megtartja a motorját.

#### SQLite, egy replika

PostgreSQL és Redis nélküli kis telepítésnél az SQLite az adatkötetre kerül (ugyanaz, mint a
[`test-local/values-sqlite.yaml`](https://github.com/WorkWise-Solutions/WorkSmartHub-Docker-Kubernetes/blob/main/test-local/values-sqlite.yaml)):

```yaml
app:
  replicationFactor: 1
  env:
  - name: ConnectionStrings__InternalDbType
    value: "0"
  - name: ConnectionStrings__InternalDb
    value: "Data Source=database.db;"
  - name: CacheSettings__Type
    value: "InMemory"
  dataVolume:
    persistence:
      enabled: true
internalDatabase:
  skipDeployment: True
cacheSystem:
  skipDeployment: True
```

A chart elutasítja az SQLite-ot egynél több replikával, és adatkötet nélkül is (kivéve
`app.allowNonPersistentSqlite: true` esetén, eldobható tesztekhez). Blokktárolós StorageClass-t használjon, ne NFS-t.

### 4. lépés: Cache

A chart `redis:7-alpine` cache-t telepít (csak cache: nincs perzisztencia és jelszó; a NetworkPolicy-ja csak a névtér
podjait engedi), és a chart `appsettings.json`-ja ezt választja:

```json
"CacheSettings": {
  "Type": "Redis",
  "RedisCacheSettings": { "Configuration": "cache:6379", "InstanceName": "worksmarthub" }
}
```

- **Egynél több replikához közös cache kell:** `Redis` vagy adatbázis-cache. A chart elutasítja az `InMemory` értéket
  egynél több replikával. A memóriabeli cache podonként külön van, így a jogosultságok, a licencállapot, a
  törzsadatlisták és az OAuth bejelentkezési állapot podonként eltérne; az alkalmazás figyelmeztetést naplóz, ha
  Kubernetesen `InMemory` cache-sel fut.
- **Külső Redis** (Amazon ElastiCache, Azure Cache for Redis): `cacheSystem.skipDeployment: True`, és egy Secretben
  `CacheSettings__RedisCacheSettings__Configuration=redis.example.com:6380,password=...,ssl=true`.
- **Adatbázis-cache:** `CacheSettings__Type` `SqlServer`, `Postgres` vagy `MySql`, a hozzá tartozó
  `...CacheSettings__ConnectionString`, séma és táblanév értékkel (lásd `appsettings.json`).
- **Egy replika Redis nélkül:** `cacheSystem.skipDeployment: True` és `CacheSettings__Type=InMemory`.

Az alkalmazás podja a `wait-for-cache` init konténerben legfeljebb 5 percig várja a beépített Redist, így egy később
induló cache pod nem indítja újra az alkalmazást; 5 perc után az alkalmazás mindenképp elindul.

#### Konténer-image-ek és biztonsági szabályok

A chart kétféle image-et használ:

- **Az alkalmazás image-ét**, amelyet Ön készít a forrásból, támogatott Microsoft alap-image-re (ASP.NET Core 10.0
  Ubuntu 24.04 LTS-en), az aktuális operációsrendszer-biztonsági frissítésekkel (változatlan verzió újraépítésekor
  `--no-cache`).
- **Infrastruktúra image-eket:** `postgres:16-alpine` (`internalDatabase.image`), `redis:7-alpine` (`cacheSystem.image`),
  `busybox:1.38.0` (`busyboxImage`, a `wait-for-cache` és a `fix-db-permissions` init konténer). Ezek upstream
  image-ek, nem a termék részei; frissen tartásuk üzemeltetői feladat. Irányítsa őket a saját registryjére, vagy egy
  olyan újabb címkére, amely átmegy a szkennerén; a hivatkozás megváltoztatása `IfNotPresent` mellett is új letöltést
  jelent.

Egy szkenner-találatnál nézze meg, melyik image-hez tartozik: infrastruktúra image-nél egy újabb upstream címke
termékkiadás nélkül megoldja; az alkalmazás image-énél újraépítés (OS csomagok) vagy új verzió (alkalmazáscsomagok).

### 5. lépés: Alkalmazásbeállítások

**A `kubernetes-helm-chart/appsettings.json`** a gyári fájl, a charthoz szükséges négy módosítással: a beépített
PostgreSQL (`ConnectionStrings`), a beépített Redis (`CacheSettings`) és a `http://+:8080` figyelési cím. A chart a
`worksmarthub-config` ConfigMapbe teszi, és csak olvashatóan csatolja a `/app/appsettings.json` helyére; a módosítása
a következő `helm upgrade` során újraindítja az alkalmazás podját (checksum annotáció). Mivel a fájl csak olvasható, egy
újabb verzió új beállításkulcsai az alapértékükkel, memóriában működnek, és a naplóban
`appsettings.json is read-only` áll.

**Az `app.env`** egyszerű környezeti változókat állít be, amelyek felülírják a fájlt. Az értékek szövegek. Titkos
értéket soha ne tegyen ide (a Deploymentben egyszerű szövegként látszik); arra a
[Secretek](#7-lépés-hitelesítő-adatok-biztonságos-kezelése) valók.

```yaml
app:
  env:
  - name: PublicBaseUrl
    value: "https://wsh.example.com/"
  - name: Serilog__MinimumLevel__Override__Microsoft
    value: "Warning"
  - name: Swagger__Enabled
    value: "false"
  - name: UseDetailedExceptions
    value: "false"
```

Amit még érdemes átnézni: `UserSettings` és `LoginSettings` (Kubernetesen `Local`, `LDAP` vagy `AzureAD`; az
`ActiveDirectory` Windows gépet igényel), `EmailSettings`, a naplózási szintek (lásd
[Naplózási szintek](#naplózási-szintek)) és a biztonsági beállítások (lásd
[Biztonsági beállítások](#biztonsági-beállítások)). Az aláírókulcsok Secretbe valók.

#### Adatkötet és File Storage

Az `app.dataVolume.persistence` (alapértelmezésben bekapcsolva) a `worksmarthub-data-claim` PVC-t csatolja a
`/app/data` mappába, a Docker kötettel azonos szerkezettel ([Mi marad meg](#mi-marad-meg)):

```yaml
app:
  dataVolume:
    persistence:
      enabled: true
      size: 5Gi
      storageClass: ""          # "" = alapértelmezett; tartós, titkosított osztály
      accessMode: ReadWriteOnce
      existingClaim: ""
```

- Egy init konténer (`prepare-data`, az alkalmazás image-e, uid 1001) új köteten létrehozza a `FileStorage` és a `Logs`
  mappát; a pod `fsGroup: 1001` beállítása írási jogot ad az alkalmazásnak.
- ReadWriteOnce kötettel a Deployment `Recreate` stratégiára vált: a régi pod leáll, mielőtt az új elindul, ezért a
  frissítés rövid kieséssel jár.
- Kötet nélkül (`enabled: false`) a naplók, az élő sablonok és a fizikai File Storage minden poddal elvesznek.
- `helm uninstall` esetén a PVC a StorageClass visszanyerési szabályát követi; a megtartásához `Retain` vagy
  `existingClaim` kell.

**A File Storage-ok** az Admin felületen jönnek létre (**App Fájltárolók**, és munkaterületenként), nem az
`appsettings.json` fájlban. A **Physical** háttér az adatkötetre ír (gyökérútvonal `FileStorage`), és egy replikához
való. Több replikához külső háttér kell (S3, Azure Blob, MinIO, Box, SharePoint, Google Cloud Storage), vagy
ReadWriteMany adatkötet. Az objektumtárak hitelesítő adatainak listázási és törlési jog is kell, és minden telepítésnek
saját bucket vagy előtag.

**Élő sablon szerkesztése:**

```bash
POD=$(kubectl get pod -n worksmarthub -l app=worksmarthub-pod -o jsonpath='{.items[0].metadata.name}')
kubectl cp -n worksmarthub -c worksmarthub-container $POD:/app/data/LiveEmailTemplates/ResetPassword.cshtml ./ResetPassword.cshtml
# a fájl szerkesztése, majd:
kubectl cp -n worksmarthub -c worksmarthub-container ./ResetPassword.cshtml $POD:/app/data/LiveEmailTemplates/ResetPassword.cshtml
```

A következő e-mail már ezt használja. Az alapsablon visszaállításához törölje a fájlt (`kubectl exec ... -- rm <fájl>`)
és a podot.

### 6. lépés: Saját CA-tanúsítványok

Belső vagy önaláírt CA-t használó végpontok felé irányuló kimenő TLS-hez (lásd
[Saját CA-tanúsítványok](#saját-ca-tanúsítványok-kimenő-tls)) a chart az alkalmazáskonténer tanúsítványtárába fűzi a
saját CA-tanúsítványait:

```bash
kubectl create configmap wsh-ca-certs -n worksmarthub --from-file=internal-ca.crt=/path/to/internal-ca.crt
```

```yaml
customCaCerts:
  enabled: true
  configMapName: wsh-ca-certs     # vagy secretName: wsh-ca-certs
```

A `merge-ca-certs` init konténer (az alkalmazás image-e, uid 65534) a rendszer tanúsítványcsomagját és a ConfigMap
vagy Secret minden `*.crt` fájlját (PEM) egy `emptyDir`-be fűzi össze, amely csak olvashatóan a
`/etc/ssl/certs/ca-certificates.crt` helyére csatolódik. Alkalmazásbeállítás nem kell; a következő pod-indításkor
érvényes (a ConfigMap módosítása után `kubectl rollout restart -n worksmarthub deploy/worksmarthub-deployment`). Ez csak
a kimenő megbízhatóságra vonatkozik; a bejövő TLS az Ingress-en végződik.

### 7. lépés: Hitelesítő adatok biztonságos kezelése

Jelszót és kulcsot ne tartson az `appsettings.json` vagy a `values.yaml` fájlban: ezek titkosítatlanul egy ConfigMapbe
és a Helm release-be kerülnek. Tegye őket Kubernetes Secretekbe; a chart környezeti változóként adja át őket, és ezek
felülírják az `appsettings.json` értékeit. A chart soha nem hoz létre Secretet, csak hivatkozik rá.

**1. módszer: egy Secret összes kulcsa** (`secrets.envFromSecret`). Minden kulcs egy környezeti változó neve:

```bash
kubectl create namespace worksmarthub        # egyszer, ha nem a chart hozza létre (installNameSpace: False)
kubectl create secret generic wsh-secrets -n worksmarthub \
  --from-literal=ConnectionStrings__InternalDb='Server=pg.example.com;Port=5432;Database=wsh;User id=wsh;Password=<jelszó>;SSL Mode=Require;' \
  --from-literal=LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey="$(openssl rand -base64 48)" \
  --from-literal=TicketAttachment__DownloadLink__SymmetricSecurityKey="$(openssl rand -base64 48)" \
  --from-literal=ImageConfiguration__ImageLink__SymmetricSecurityKey="$(openssl rand -base64 48)" \
  --from-literal=EmailSettings__SmtpPassword='<smtp jelszó>'
```

```yaml
secrets:
  envFromSecret: "wsh-secrets"
```

Az érvénytelen környezetiváltozó-nevű kulcsok szó nélkül kimaradnak. `envFromSecret` mellett a chart nem látja, melyik
adatbázist és cache-t választja a Secret, ezért az SQLite és InMemory replika-ellenőrzései kimaradnak.

**2. módszer: egyes kulcsok** (`secrets.env`), más kulcsnevű Secretekhez:

```yaml
secrets:
  env:
  - name: ConnectionStrings__InternalDb
    secretName: wsh-db
    key: connection-string
  - name: LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey
    secretName: wsh-keys
    key: jwt
```

| `appsettings.json` útvonal | Környezeti változó |
|----------------------------|--------------------|
| `ConnectionStrings.InternalDb` | `ConnectionStrings__InternalDb` |
| `CacheSettings.RedisCacheSettings.Configuration` | `CacheSettings__RedisCacheSettings__Configuration` |
| `LoginSettings.JwtAuthenticationSettings.SymmetricSecurityKey` | `LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey` |
| `TicketAttachment.DownloadLink.SymmetricSecurityKey` | `TicketAttachment__DownloadLink__SymmetricSecurityKey` |
| `ImageConfiguration.ImageLink.SymmetricSecurityKey` | `ImageConfiguration__ImageLink__SymmetricSecurityKey` |
| `EmailSettings.SmtpPassword` | `EmailSettings__SmtpPassword` |
| `UserSettings.LdapSettings.Password` | `UserSettings__LdapSettings__Password` |
| `UserSettings.AzureADSettings.ClientSecret` | `UserSettings__AzureADSettings__ClientSecret` |
| `LoginSettings.OAuthSettings.Okta.AppSecret` (és `Google`, `Microsoft`, `Custom`) | `LoginSettings__OAuthSettings__Okta__AppSecret` |

A titkos értékeket a parancssorba gépelje, vagy a titokkezelője hozza létre a Secretet; ne tartsa őket fájlban. Az
**External Secrets Operator** HashiCorp Vaultból, AWS Secrets Managerből vagy Azure Key Vaultból szinkronizál egy
Secretet; az így létrejövő Secretre ugyanígy kell hivatkozni:

```yaml
apiVersion: external-secrets.io/v1beta1
kind: ExternalSecret
metadata:
  name: wsh-secrets
  namespace: worksmarthub
spec:
  refreshInterval: 1h
  secretStoreRef: { name: vault-backend, kind: ClusterSecretStore }
  target: { name: wsh-secrets }
  data:
  - secretKey: ConnectionStrings__InternalDb
    remoteRef: { key: secret/data/wsh/database, property: connection-string }
  - secretKey: LoginSettings__JwtAuthenticationSettings__SymmetricSecurityKey
    remoteRef: { key: secret/data/wsh/keys, property: jwt }
```

A környezeti változókat a konténer induláskor olvassa; egy Secret módosítása után indítsa újra a podokat:
`kubectl rollout restart -n worksmarthub deploy/worksmarthub-deployment`.

A beépített PostgreSQL `internalDatabase.settings.password` értéke a `values.yaml` fájlban marad (a PostgreSQL
közvetlenül olvassa); élesre inkább olyan külső adatbázist használjon, amelynek kapcsolati karakterlánca csak Secretben
van. A nem titkos beállítások (`InternalDbType`, `Schema`, `CacheSettings.Type`, `UserSettings`, naplózási szintek)
maradjanak az `appsettings.json` fájlban vagy az `app.env` alatt. Az adatbázis-kapcsolatokra kényszerítse a TLS-t:
PostgreSQL `SSL Mode=Require` (vagy `VerifyFull`), SQL Server `Encrypt=True;TrustServerCertificate=False`, MySQL
`SslMode=Required`.

### 8. lépés: Service típusa és Ingress

**A Service típusa** (`app.serviceType`) határozza meg, hogyan érhető el az alkalmazás a fürtön kívülről; a Service az
`advanced.app.servicePort` (80) porton figyel, és a 8080-as konténerportra továbbít.

| Típus | Honnan érhető el | Mikor |
|-------|------------------|-------|
| `ClusterIP` (alapérték) | A fürtön belülről | Ingress vagy service mesh mögött; teszthez `kubectl port-forward` |
| `NodePort` | `<csomópont IP>:<30000-32767>` | Gyors elérés ingress vezérlő nélkül; fürtszabályok gyakran tiltják |
| `LoadBalancer` | A platform által adott IP | Közvetlen elérés felhőben; belsőként az `app.serviceAnnotations` értékkel (`networking.gke.io/load-balancer-type: "Internal"`, `service.beta.kubernetes.io/aws-load-balancer-scheme: "internal"`, `service.beta.kubernetes.io/azure-load-balancer-internal: "true"`) |

Egy belépési pontot válasszon: az Ingress-t `ClusterIP`-vel, vagy egy `LoadBalancer`-t.

**Ingress** (alapértelmezésben `advanced.ingress.enabled: true`, `advanced.ingress.className: nginx`). Az
`app.hostName` a host szabályt adja (üresen: minden host). TLS:

```yaml
app:
  hostName: "wsh.example.com"
advanced:
  ingress:
    annotations:
      cert-manager.io/cluster-issuer: "your-issuer"
    tls:
    - hosts:
      - wsh.example.com
      secretName: wsh-tls
```

**Feltöltési korlátok és időkorlátok.** Az ingress-nginx alapértelmezésben 1 MB-os kéréstörzset fogad el, és 60
másodperc után lezárja a továbbított kérést, a munkalap-mellékletek és alkatrészképek viszont 25 MB-os darabokban
töltődnek fel. A chart beállítja:

```yaml
nginx.ingress.kubernetes.io/proxy-body-size: "50m"
nginx.ingress.kubernetes.io/proxy-read-timeout: "600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "600"
```

A saját `advanced.ingress.annotations` értékei ezek fölé kerülnek: azonos kulcsnál az Ön értéke érvényes, a többi
annotációja megmarad. Az Ingress annotációja erősebb a vezérlő ConfigMapjénél, ezért az ott megemelt korlátot itt is be
kell állítani. Ha a darabméretet megemeli (`TicketAttachment.UploadChunkSize`, `ImageConfiguration.ImageChunkSize`), a
`proxy-body-size` maradjon fölöttük. Más ingress vezérlők figyelmen kívül hagyják ezeket az annotációkat; nekik adja meg
ugyanezeket a korlátokat, és minden, a fürt előtt álló terheléselosztónak vagy WAF-nak is.

**Az Ingress kikapcsolása** (`advanced.ingress.enabled: false`) service mesh vagy saját útválasztás esetén: a
`worksmarthub` Service 80-as portjára irányítson, és állítsa be a továbbított fejléceket a
[Fordított proxy és továbbított fejlécek](#fordított-proxy-és-továbbított-fejlécek) szerint.

### 9. lépés: Replikák és skálázás

```yaml
app:
  replicationFactor: 1
  resources:
    requests: { memory: 512M, cpu: 250m }
    limits: { memory: 2000M, cpu: 2000m }
```

Egy replika (az alapérték) minden beállítással működik. **Egynél több replikához** mindegyik kell:

- közös adatbázis: a beépített PostgreSQL vagy külső (**az SQLite csak egy replikát támogat**);
- közös cache: Redis (az alapérték) vagy adatbázis-cache;
- minden pod által csatolható adatkötet: `accessMode: ReadWriteMany` RWX StorageClass-szal (NFS, EFS, Azure Files,
  Filestore), vagy adatkötet nélkül (`enabled: false`; a naplók és az élő sablonok ekkor podonként külön vannak);
- külső File Storage háttér a mellékletekhez és képekhez.

A chart nem renderel (a `helm install` és a `helm upgrade` üzenettel leáll), ha egynél több replika mellett
ReadWriteOnce adatkötet, SQLite vagy memóriabeli cache van beállítva; a `helm lint` ezt INFO sorként mutatja. A több
replika viselkedése (zárolt migrációk, munkamenetek, alkalmanként egyszer futó háttérfolyamatok) a
[Több csomópont és magas rendelkezésre állás](#több-csomópont-és-magas-rendelkezésre-állás) részben olvasható. A
replikákat egy preferált pod anti-affinity szórja szét a csomópontokon.

**Elhelyezés csomópontokon:** az `advanced.nodeConfiguration.appNodesConfiguration`, `dbNodesConfiguration` és
`cacheNodesConfiguration` a megfelelő podokra `nodeSelector`, `affinity` és `tolerations` értéket vesz át. Egy külön
csomópontkészlet az alkalmazásnak lehetővé teszi, hogy egy tűzfalszabály csak azokról a csomópontokról engedje a kimenő
kapcsolatait:

```yaml
advanced:
  nodeConfiguration:
    appNodesConfiguration:
      nodeSelector:
        role: wsh
      tolerations:
      - { key: role, operator: Equal, value: wsh, effect: NoSchedule }
```

Az itt megadott `affinity` a chart anti-affinity beállítását helyettesíti.

### 10. lépés: Telepítés

Ebből a repositoryból:

```bash
helm install worksmarthub ./kubernetes-helm-chart -f sajat-values.yaml --set app.image.tag=23
```

Előtte nézze meg az eredményt: `helm template worksmarthub ./kubernetes-helm-chart -f sajat-values.yaml --set
app.image.tag=23`. A `test-local` szkriptjei egy helyi fürtön ellenőrzik a chartot, mielőtt máshová telepítené
([test-local/README.md](https://github.com/WorkWise-Solutions/WorkSmartHub-Docker-Kubernetes/blob/main/test-local/README.md)).

### 11. lépés: Ellenőrzés

```bash
kubectl get pods -n worksmarthub
# worksmarthub-deployment-...  1/1 Running   (alkalmazás; init konténerek: prepare-data, wait-for-db, wait-for-cache)
# db-deployment-...            1/1 Running   (beépített PostgreSQL)
# cache-deployment-...         1/1 Running   (beépített Redis)

kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container
# ... Migrating database ... Applying migration '...' ... Migration complete

kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c wait-for-db      # PostgreSQL accepts the login from values.yaml.
kubectl get pvc,svc,ingress -n worksmarthub
```

Az első indulás minden migrációt lefuttat (kis fürtön körülbelül egy perc); a pod akkor Ready, amikor a `/health`
válaszol. Az alkalmazás megnyitása:

- Ingress-szel és hostnévvel: `https://wsh.example.com/`;
- Ingress-szel hostnév nélkül: az Ingress címe (`kubectl get ingress -n worksmarthub`);
- Ingress nélkül: `kubectl port-forward -n worksmarthub svc/worksmarthub 8080:80`, majd `http://localhost:8080/`.

Az első felhasználót a kezdőoldalon hozza létre.

### 12. lépés: A licenc aktiválása

A licencet az alkalmazásban kell feltölteni, és az adatbázisban tárolódik; Helm érték nincs hozzá. Túléli a pod
újraindítását és a frissítést, és minden replika ugyanazt a licencet olvassa.

**A portálon:** nyissa meg a **Licenc** oldalt (`/portal/license`), és válassza az **Új licenc fájl feltöltése**
gombot. Az oldal mutatja az állapotot, az ügyfelet, a kezdő, a lejárati és a lejárati figyelmeztetés dátumát.

**Ki tölthet fel.** Amíg az alkalmazásnak nincs érvényes licence (nincs, lejárt vagy sérült), bárki feltölthet egyet,
bejelentkezve vagy anélkül, így egy új telepítés az első felhasználó létrehozása előtt is licencelhető. Az érvényes
licencet, a lejárati figyelmeztetés időszakában lévőt is, csak **Super Admin** (a `SuperAdmin` jogosultság) cserélheti
le; más hívó `generic.not_authorized` hibát kap. Az érvénytelen licencfájlt az alkalmazás `license.error` hibával
utasítja el.

**API-n keresztül:**

```bash
# még nincs érvényes licenc: bejelentkezés nem kell
curl -X POST https://wsh.example.com/api/licensing/set \
  -H "Content-Type: application/octet-stream" --data-binary @license.key

# állapot (bejelentkezés nem kell)
curl https://wsh.example.com/api/licensing/status
```

Érvényes licenc API-n keresztüli cseréjéhez egy Super Admin személyes hozzáférési tokenje kell (a **Személyes
Hozzáférési Tokenek** oldalon hozható létre, `/portal/pat`). A refresh tokenjét cserélje access tokenre, és azt küldje
Bearer tokenként. Minden frissítés **új** refresh tokent ad vissza, az előző pedig érvényét veszti, ezért az újat
tárolja el:

```bash
RESPONSE=$(curl -s -X POST https://wsh.example.com/api/pats/refresh-token \
  -H "Content-Type: application/json" -d '{"refreshToken": "<refresh token>"}')
NEW_REFRESH_TOKEN=$(echo "$RESPONSE" | jq -r '.refreshToken.token')     # ezt tárolja a régi helyett
ACCESS_TOKEN=$(echo "$RESPONSE" | jq -r '.accessToken.token')

curl -X POST https://wsh.example.com/api/licensing/set \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/octet-stream" --data-binary @license.key
```

Az access token `?access_token=<access token>` paraméterként is küldhető; a fejléc távol tartja a hozzáférési
naplóktól. A személyes hozzáférési token csak API-hívásokat hitelesít, böngészős munkamenetet soha nem indít.

### Frissítés és visszaállás

```bash
bash build/build-image.sh --version 24 --minikube       # vagy töltse fel a worksmarthub:24-et a registryjébe
helm upgrade worksmarthub ./kubernetes-helm-chart -f sajat-values.yaml --set app.image.tag=24
kubectl rollout status -n worksmarthub deploy/worksmarthub-deployment
kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container | grep -E "Migrat|ERR|FTL"
```

- Előtte mentse az adatbázist (a parancsok az [Átköltözés környezetek között](#átköltözés-környezetek-között) részben).
- Ugyanazokat a values értékeket használja, mint a telepítéskor, és csak a címkét változtassa meg. A repository újabb
  verziója új chart-alapértékeket hozhat: frissítés előtt vesse össze a `values.yaml` és az `appsettings.json` fájlját a
  sajátjával.
- Az alkalmazás podja lecserélődik (ReadWriteOnce adatkötetnél előbb a régi pod áll le: rövid kiesés), induláskor
  migrálja az adatbázist, és megtartja az adatkötetet. Az adatbázis és a cache podja, a kötetek és a felhasználók
  munkamenetei megmaradnak.
- A chart `appsettings.json` fájljának módosítása is újraindítja az alkalmazás podját; egy Secret módosításához
  `kubectl rollout restart` kell.

**Visszaállás.** A `helm history worksmarthub` felsorolja a revíziókat; a `helm rollback worksmarthub <revízió>`
visszaállítja annak a revíziónak a manifestjét és image-ét. **Az adatbázis nem migrálódik vissza**: a korábbi verzió
ekkor az újabb sémán fut. Korábbi alkalmazásverzióra való visszatéréshez a frissítés előtt készült adatbázis-mentést
állítsa vissza.

**A frissítés előzetes kipróbálása.** A `test-local/upgrade-test.sh` minikube-on végigjátssza a folyamatot: telepítés
az A image-dzsel, adatok létrehozása (első felhasználó, egy második felhasználó, bejelentkezés, jelölőfájl az
adatkötetre, egy szerkesztett sablon), `helm upgrade` a B image-re, és ellenőrzi, hogy csak az alkalmazás podja
cserélődött (0 újraindítással), a PVC-k, az adatbázis és a cache podja megtartotta az UID-ját, az adatok és a frissítés
előtti bejelentkezés működnek, és lefutottak a migrációk; végül `helm rollback` és ugyanezek az ellenőrzések:

```bash
bash test-local/upgrade-test.sh --from 23 --to 24
```

### Átköltözés környezetek között

Egy telepítés költöztetéséhez (például Dockerről vagy Windows szerverről Kubernetesre, vagy másik fürtre) másolja át az
**adatbázist** és az **adatkötetet**; együtt a teljes állapotot tartalmazzák: felhasználók, munkaterületek, munkalapok,
ügyfelek, számlák, a File Storage és az értesítési csatornák definíciói, a licenc, a bejelentkezési kulcsok és az
auditnapló. A tárolt hitelesítő adatok az új telepítésen a régi gép bármilyen adata nélkül visszafejthetők.

- Maradjon **ugyanaz az adatbázismotor** (beépített átalakítás nincs), és az új oldalon **ugyanaz vagy újabb**
  alkalmazásverzió fusson; az első indulásakor migrálja a sémát.
- Használja **ugyanazokat az aláírókulcsokat** (`TicketAttachment.DownloadLink.SymmetricSecurityKey`,
  `ImageConfiguration.ImageLink.SymmetricSecurityKey`, `LoginSettings.JwtAuthenticationSettings.SymmetricSecurityKey`),
  különben a meglévő hivatkozások és tokenek nem működnek; a `PublicBaseUrl` legyen az új cím.
- Utána ne fusson a két telepítés ugyanazokkal a külső File Storage bucketekkel (lásd
  [Több csomópont és magas rendelkezésre állás](#több-csomópont-és-magas-rendelkezésre-állás)).

A beépített PostgreSQL-lel (előbb állítsa le az alkalmazást: `kubectl scale -n worksmarthub deploy/worksmarthub-deployment --replicas=0`):

```bash
# adatbázis ki a régi telepítésből és be az újba
kubectl exec -n worksmarthub deploy/db-deployment -- sh -c 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" -Fc' > wsh-db.dump
kubectl exec -i -n <új névtér> deploy/db-deployment -- sh -c 'pg_restore -U "$POSTGRES_USER" -d "$POSTGRES_DB" --clean --if-exists --no-owner' < wsh-db.dump

# adatkötet (amíg létezik alkalmazás pod, pl. közvetlenül azután, hogy az újat 1-re skálázta)
kubectl exec -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container -- tar czf - -C /app/data . > wsh-data.tgz
kubectl exec -i -n <új névtér> deploy/worksmarthub-deployment -c worksmarthub-container -- tar xzf - -C /app/data < wsh-data.tgz
```

Dockerről a kötet mentése ([Mentés és visszaállítás](#mentés-és-visszaállítás)) az adatarchívum, és egy SQLite
adatbázis is vele együtt költözik (az archívum `database.db` fájlja; az új oldalon az [SQLite](#sqlite-egy-replika)
értékeket használja). Az adatbázist az új alkalmazás első indulása előtt állítsa vissza, vagy indítsa el egyszer,
állítsa le, állítsa vissza, és indítsa újra. Utána törölje a mentés- és archívumfájlokat; hitelesítő adatokat
tartalmaznak.

### Eltávolítás

```bash
helm uninstall worksmarthub
```

- `installNameSpace: True` esetén (az alapérték) a névtér a release része, és mindennel együtt törlődik, a
  `worksmarthub-data-claim` és a `postgres-data-claim` PVC-vel is. Hogy az adatok megmaradnak-e, a StorageClass
  visszanyerési szabályán múlik: `Delete` (a gyakori) törli őket, `Retain` `Released` állapotban megtartja a
  PersistentVolume-okat.
- Megmarad: az `existingClaim`-ként megadott PVC, a saját magának létrehozott névtér (`installNameSpace: False`) a benne
  lévő Secretekkel (törlése: `kubectl delete namespace worksmarthub`), és az image-ek a csomópontokon.
- Előtte mentse az adatbázist és az adatkötetet (a parancsok az
  [Átköltözés környezetek között](#átköltözés-környezetek-között) részben).

### Élesítési ellenőrzőlista

Az alapértékek első telepítéshez valók, nem éles üzemhez. Élesítés előtt:

**Adatok és tartósság**
- [ ] **Külső, felügyelt adatbázis** mentéssel és időpontra visszaállítással, vagy legalább a beépített PostgreSQL
  rendszeres mentése ([3. lépés](#3-lépés-belső-adatbázis)). A beépített egyetlen példány, átállás nélkül.
- [ ] **Tartós StorageClass** titkosítással, és `Retain` vagy `existingClaim`, ahol az adatnak túl kell élnie a
  `helm uninstall` parancsot ([5. lépés](#5-lépés-alkalmazásbeállítások)).
- [ ] **A File Storage** a replikák számához illik: egy replikához Physical az adatkötetre, többhöz külső háttér.
- [ ] **Közös cache** (Redis), ha egynél több replika fut ([4. lépés](#4-lépés-cache)).

**Biztonság**
- [ ] Az **alapértelmezett adatbázisjelszó** megváltoztatva ([Adatbázisjelszó](#adatbázisjelszó)).
- [ ] **Saját aláírókulcsok** a `LoginSettings.JwtAuthenticationSettings`, `TicketAttachment.DownloadLink` és
  `ImageConfiguration.ImageLink` alatt, Secretből; induláskor nincs `SECURITY:` figyelmeztetés
  ([7. lépés](#7-lépés-hitelesítő-adatok-biztonságos-kezelése)).
- [ ] A **`PublicBaseUrl`** a nyilvános címre állítva.
- [ ] A hitelesítő adatok **Secretekben**, nem a `values.yaml` vagy az `appsettings.json` fájlban.
- [ ] **TLS** az Ingress-en érvényes tanúsítvánnyal; HSTS bekapcsolva a **Biztonsági fejlécek** oldalon; a Service
  `ClusterIP`.
- [ ] **TLS az adatbázis felé** (`SSL Mode=Require`, `Encrypt=True`, `SslMode=Required`).
- [ ] `UseDetailedExceptions` `false`; `Swagger:Enabled` `false`, ha nincs rá szükség.
- [ ] Az éles **identitásszolgáltató** (`LDAP` vagy `AzureAD`, vagy OAuth), ha nem helyi felhasználókkal fut.
- [ ] **NetworkPolicy** érvényesítés (képes CNI) és a biztonsági csapat által kért kimenő szabályok.

**Rendelkezésre állás és üzemeltetés**
- [ ] A **replikák** és az **erőforrások** méretezve; több replikánál minden többcsomópontos feltétel teljesül
  ([9. lépés](#9-lépés-replikák-és-skálázás)).
- [ ] **Naplógyűjtés** a standard kimenetről (`kubectl logs`) a naplózó rendszerbe; a naplózási szint `Information`
  vagy `Warning`.
- [ ] A **licenc** aktiválva ([12. lépés](#12-lépés-a-licenc-aktiválása)).
- [ ] Egy **frissítés** kipróbálva egy másolaton ([Frissítés és visszaállás](#frissítés-és-visszaállás)).

### Fontos tudnivalók

**Biztonsági környezet.** Minden konténer nem root felhasználóként, minden Linux-képesség elvételével és
jogosultság-emelés nélkül fut, minden podon `seccompProfile: RuntimeDefault` van, és az alkalmazás ServiceAccount-ja nem
csatol API tokent. Ez megfelel a `restricted` Pod Security Standardnek, kivéve az opcionális `fix-db-permissions` init
konténert:

| Konténer | UID | Megjegyzés |
|----------|-----|------------|
| Alkalmazás (`worksmarthub-container`) | 1001 | `appuser` |
| `prepare-data` (init, adatkötettel) | 1001 | Létrehozza a `FileStorage` és a `Logs` mappát |
| `wait-for-db` (init, beépített PostgreSQL-lel) | 70 | `psql` bejelentkezési ellenőrzés |
| `wait-for-cache` (init, beépített Redisszel) | 65534 | `nc` ellenőrzés, legfeljebb 5 percig |
| `merge-ca-certs` (init, `customCaCerts` mellett) | 65534 | PEM fájlok összefűzése |
| PostgreSQL | 70 | `fsGroup: 70` |
| Redis | 999 | |
| `fix-db-permissions` (init, csak `internalDatabase.fixDataPermissions: True` mellett) | 0 | A `CHOWN` kivételével minden képességet elvesz; alapértelmezésben ki van kapcsolva |

**Hálózati szabályok.** A beépített PostgreSQL és Redis bejövő NetworkPolicy-t kap
(`internalServicesNetworkPolicy.enabled`, alapértelmezésben bekapcsolva), amely csak a névtér podjait engedi be; az
`internalServicesNetworkPolicy.extraIngress` a névtéren kívüli forrásokat ad hozzá (például egy mentési feladat
névterét). A podokat az `app` címkével együtt a chart saját `wsh-internal-service: db` / `cache` címkéje alapján
választják ki, így soha nem érintik más alkalmazás podjait. A NetworkPolicy-kat csak az ezt támogató CNI érvényesíti
(Calico, Cilium, Weave Net).

**Próbák.** `GET /health` a 8080-as porton: az indulási próba 10 percet ad az első indulásra (migrációk), a készenléti
próba kiveszi a podot a Service-ből, ha nem válaszol, az élőségi próba pedig 2,5 perc válasz nélkül újraindítja. A
`terminationGracePeriodSeconds: 60` lefedi, hogy az alkalmazás 45 másodpercet hagy a háttérfolyamatainak leálláskor. A
PostgreSQL podnak `pg_isready` készenléti próbája, a Redis podnak TCP próbája van.

**Beállításváltozások:** a chart `appsettings.json` fájljának módosítása újraindítja az alkalmazás podját
(`checksum/config` annotáció).

### Elszigetelt és korlátozott hálózatok

Kimenő internet-hozzáférés nélkül:

1. **Az alkalmazás image-e:** ott készítse el, ahol a források vannak, `--save worksmarthub-23.tar`, és töltse be a
   csomópontokra, vagy töltse fel a belső registryjébe (`app.image.repository`).
2. **Infrastruktúra image-ek:** a `postgres:16-alpine`, `redis:7-alpine` és `busybox:1.38.0` image-et kívül töltse le,
   töltse fel a registryjébe, és állítsa be az `internalDatabase.image`, `cacheSystem.image` és `busyboxImage` értéket.
   A `wait-for-db` init konténer az `internalDatabase.image`, a `prepare-data` és a `merge-ca-certs` az alkalmazás
   image-ét használja.
   ```bash
   for i in postgres:16-alpine redis:7-alpine busybox:1.38.0; do docker pull $i; docker tag $i registry.example.com/$i; docker push registry.example.com/$i; done
   ```
3. **Letöltési szabály:** maradjon `IfNotPresent`, hogy a pod-újraindításhoz ne kelljen registry.
4. **Az alkalmazás saját kimenő kapcsolataihoz** (Számlázz.hu, Slack, Teams, Entra ID, objektumtárak) a
   [Kimenő kapcsolatok](#kimenő-kapcsolatok) céljai kellenek, különben az ezeket használó funkciók nem működnek.

---

## Állapotellenőrzés

A `GET /health` hitelesítés nélkül `200 {"status":"Healthy"}` választ ad, amint az alkalmazás kiszolgálja a kéréseket,
vagyis az indulási migrációk után. Mást nem érint: nincs adatbázishívás, nincs verzió- vagy csomópontadat. A chart próbái
ezt használják. Az image-ben nincs `HEALTHCHECK` utasítás, sem curl vagy wget; a benne lévő `bash` el tudja küldeni a
kérést, például Docker Compose-ban:

```yaml
healthcheck:
  test: ["CMD", "bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/8080 && printf 'GET /health HTTP/1.0\\r\\nHost: localhost\\r\\n\\r\\n' >&3 && grep -q '^HTTP/1.[01] 200' <&3"]
  interval: 30s
  timeout: 5s
  retries: 3
  start_period: 120s
```

Terheléselosztók és megfigyelőrendszerek a `GET /health` 200-as állapotkódját figyeljék. Az Admin felület állapotoldala
és a naplófájlok részletesebb adatot mutatnak a rendszergazdáknak.

## Hibaelhárítás

**Hol vannak a naplók.** Docker: `docker logs -f worksmarthub` (a szolgáltatásnál `journalctl -u worksmarthub -f`, az
ütemezett feladat indulásáról a Windows-szkript melletti `worksmarthub-task.log`). Kubernetes:
`kubectl logs -n worksmarthub deploy/worksmarthub-deployment -c worksmarthub-container -f`, az init konténereké
`-c prepare-data`, `-c wait-for-db`, `-c wait-for-cache`, `-c merge-ca-certs` kapcsolóval, egy összeomlott konténer
előző futásáé `--previous` kapcsolóval. A napi fájlok az adatkötet `Logs/` mappájában és az Admin felületen vannak
(**Naplófájlok**).

**Teendőt nem igénylő üzenetek az első induláskor PostgreSQL-lel.** Új, üres PostgreSQL adatbázison a naplóban
megjelenik a `Cannot load library libgssapi_krb5.so.2` (a PostgreSQL meghajtó az opcionális Kerberos könyvtárat keresi,
ami nincs az image-ben, és nélküle folytatja), valamint egyszer az `ERR Failed executing DbCommand ... SELECT
"MigrationId" ... FROM "__EFMigrationsHistory"` sor (a migrációs előzmény tábla még nem létezik; közvetlenül utána
létrejön, majd következnek az `Applying migration` sorok és a `Migration complete`). Már migrált adatbázisnál egyik
sor sem jelenik meg.

**Az indítószkript 78-as kóddal lép ki.** Egy indítás előtti ellenőrzés nem sikerült, és az üzenet megnevezi: hiányzik
az image, már fut egy ilyen nevű konténer, létezik egy adatkötet nélküli leállított konténer, vagy a gépi mappa nincs
előkészítve. A systemd szolgáltatás erre a kilépési kódra nem indít újra.

**A podok `Pending` állapotban maradnak.** `kubectl describe pod -n worksmarthub <pod>`: többnyire nincs kötve a PVC
(nincs alapértelmezett StorageClass, elírt `storageClass`, vagy egy ReadWriteOnce kötet még máshoz van csatolva), vagy
kevés a CPU vagy a memória a kérésekhez.

**`ErrImagePull` / `ImagePullBackOff`.** A csomóponton nincs meg az image: építse annak a csomópontnak a démonjába
(`--minikube`), töltse be oda, vagy töltse fel registrybe, és állítsa be az `app.image.repository` és az
`app.imagePullSecrets` értéket. Egy olyan címkével futtatott `helm upgrade`, amely nincs meg a csomópontokon, ugyanígy
hibát ad.

**Az adatbázis podja `CrashLoopBackOff` állapotban van.** `kubectl logs -n worksmarthub deploy/db-deployment`.
`Permission denied` az adatmappán: a tároló figyelmen kívül hagyja az `fsGroup`-ot; állítsa be az
`internalDatabase.fixDataPermissions: True` értéket, vagy használjon CSI osztályt. `database files are incompatible
with server`: az image főverziója eltér az adatmappáétól.

**Az alkalmazás podja újraindul, a naplóban `28P01: password authentication failed` áll.** Az adatbázis elutasította a
jelszót. A beépített PostgreSQL-nél az adatkötet korábban, más jelszóval jött létre (később megváltoztatták a values
fájlban, vagy megtartott kötetre telepítettek újra); a `wait-for-db` naplójából kiderül, hogy a `values.yaml` adatait is
elutasítja-e. Állítsa az adatbázis jelszavát a kapcsolati karakterláncban lévőre ([Adatbázisjelszó](#adatbázisjelszó)),
vagy állítsa vissza az eredetit; adatok nélküli új telepítésnél el is távolíthatja a release-t, törölheti a
`postgres-data-claim` PVC-t, és újratelepíthet.

**Az alkalmazás nem éri el az adatbázist.** A beépített adatbázis hostneve `db` (a Service), a portja 5432; a
kapcsolati karakterlánc adatainak egyezniük kell az `internalDatabase.settings` értékeivel. Külső adatbázisnál
ellenőrizze a podból a DNS-t (`kubectl exec ... -- getent hosts <host>`), a tűzfalat és a TLS-beállításokat.

**SQLite migrációs zárolás.** A migrációk zárolást használnak; SQLite-on ez egy sor a `__EFMigrationsLock` táblában, és
a migráció közben leállított folyamat (megölt konténer, csomóponthiba) bent hagyja ezt a sort. Az SQLite csak egy
csomópontot szolgál ki, ezért az alkalmazás az ilyen sort elavultnak tekinti: a következő induláskor törli, naplózza
(`Removed a stale SQLite migration lock left by an earlier start that did not finish migrating`), és migrál. SQL
Serveren, PostgreSQL-en és MySQL-en a zárolást az adatbázis-kapcsolat tartja, és azzal együtt megszűnik; egy második
csomópont megvárja, amíg az első befejezi a migrációt.

**A pod nem lesz Ready / a próbák sikertelenek.** A `kubectl describe pod` mutatja a próbák eredményét. A próbák a
8080-as port `/health` címét hívják; a figyelési címnek (`HttpSettings.Urls` vagy `HttpSettings__Urls__0`) ezt a portot
kell használnia. Az első induláskor az indulási próba legfeljebb 10 percig várja a migrációkat; a lassabb indulás (nagy
adatbázis, lassú lemez) újraindításként és az eseményekben `Startup probe failed` üzenetként jelenik meg.

**`appsettings.json is read-only` a naplóban.** Csak tájékoztatás: a fájl csak olvashatóan van csatolva (Kubernetesen
mindig), vagy az uid 1001 nem tudja írni. Egy újabb verzió új beállításkulcsai az alapértékükkel, memóriában működnek;
ha más érték kell, vegye fel őket a saját fájljába.

**`SECURITY:` figyelmeztetések induláskor.** Egy aláírókulcs még a gyári értéken van, vagy a `PublicBaseUrl` üres; lásd
[Az első éles használat előtt beállítandók](#az-első-éles-használat-előtt-beállítandók).

**A feltöltés 413 Request Entity Too Large hibával leáll.** Egy proxy elutasította a kéréstörzset. Ebben a sorrendben
ellenőrizze: az `advanced.ingress.annotations` alatt megadott `proxy-body-size` értéket (az Öné érvényes), a saját
kezelésű Ingress-t vagy vezérlőt (az ingress-nginx alapértéke 1 MB), a Docker előtti fordított proxyt
(`client_max_body_size`), és minden terheléselosztót vagy WAF-ot. Az nginx nevét viselő 413-as oldal proxytól jön, nem
az alkalmazástól. A 60 másodperc utáni 504 a proxy olvasási időkorlátja.

**Sikertelen kimenő TLS (`The remote certificate is invalid`, `unable to get local issuer certificate`).** A végpont
CA-ja nem megbízható: adja hozzá ([Saját CA-tanúsítványok](#saját-ca-tanúsítványok-kimenő-tls),
[6. lépés](#6-lépés-saját-ca-tanúsítványok)).

**Frissítés után a böngésző az előző verziót mutatja.** A szerver a kezdőoldalt `Cache-Control: no-cache` fejléccel
küldi, így a böngésző minden betöltéskor ellenőrzi, és az új portált kapja; a szkript- és stíluscsomagok fájlneve
tartalmi hash-t tartalmaz. Az a böngésző, amely egy olyan régebbi build kezdőoldalát tárolta el, amely még nem küldte
ezt a fejlécet, addig tartja meg, amíg a gyorsítótára le nem jár vagy ki nem ürítik.

**Az Ingress nem működik.** Ellenőrizze a vezérlőt (`kubectl get pods -n ingress-nginx`) és az osztályt
(`advanced.ingress.className`). Más vezérlő vagy service mesh esetén kapcsolja ki a chart Ingress-ét, és a
`worksmarthub` Service 80-as portjára irányítson.
