Helyi tesztelés és telepítés¶

Ez az oldal bemutatja, hogyan próbálhatja ki a DiKAS-t saját maga, hogyan telepítheti helyben, és hogyan üzemeltetheti fejlesztési célra. Az oldal integrátoroknak, rendszergazdáknak és fejlesztőknek szól.

A DiKAS helyi üzemeltetésére két út van:

Változat	Alkalmas	Ráfordítás
A — ISO-appliance virtuális gépben	Valósághű próbaüzem, mint egy valódi pénztárhardveren	Csekély
B — Fejlesztői környezet (`dotnet` + `ng`)	API-fejlesztés, testreszabás, hibakeresés	Nagyobb

Csak gyorsan megnézné a pénztárt?

Ha a DiKAS-t csak kötelezettség nélkül szeretné kipróbálni, az A változat (ISO virtuális gépben) a leggyorsabb út egy teljes pénztárhoz. Virtuális gép nélküli, tisztán API-/frontend-bemutatóhoz a lentebb leírt demópénztár alkalmas (SQLite + demóadatok, egyetlen parancs).

Rendszerkövetelmények¶

Szerver / VM¶

Egyidejűleg aktív pénztárak/kliensek	Minimum	Ajánlott
Legfeljebb 5	2 GB RAM, 2 mag	4 GB RAM, 2 mag
6–20	4 GB RAM, 2 mag	4 GB RAM, 4 mag
Több mint 20	4 GB RAM, 4 mag	8 GB RAM-tól, 4 mag; a terhelés szerint méretezve

A létrehozott felhasználók és munkaállomások nem foglalnak tartósan további szerverteljesítményt. A méretezésnél az egyidejűleg aktív kliensek, a kiegészítő szolgáltatások és a nagy kimutatások vagy adatimportok számítanak.

Merevlemez / virtuális lemez¶

Felhasználás	Minimum	Ajánlott
ISO-appliance a virtuális gépben	20 GB (operációs rendszer + adatbázis + demóadatok)	32 GB
Fejlesztői környezet	SDK-tól/eszközöktől függően kb. 10–15 GB	20 GB

Ökölszabály az ISO-s virtuális géphez

Az ISO-appliance kipróbálásához 2 GB RAM és 20 GB lemez elegendő. Hosszabb üzemhez vagy ötnél több egyidejűleg aktív klienshez 4 GB RAM ajánlott. Sok bizonylatkép, helyi biztonsági mentés vagy hosszú megőrzés esetén a lemeznek ennek megfelelően nagyobbnak kell lennie.

A változat: ISO-appliance virtuális gépben¶

A DiKAS-appliance egy kész, bootolható, Arch Linux (archiso) alapú operációsrendszer-képfájl. Már tartalmazza a DikasArch alkalmazást (.NET 10) és az adatbázist — ideális arra, hogy a DiKAS-t valósághű körülmények között tesztelje anélkül, hogy operációs rendszert kellene telepítenie.

Az ISO letöltése¶

Az aktuális ISO-képfájl (jelenleg kb. 1,1 GB, UEFI és BIOS módban is bootol) itt érhető el:

https://dikas.de/iso/dikas.iso

A.1 — Hyper-V (Windows)¶

A Hyper-V a Windows Pro/Enterprise és a Windows Server része. Ügyfélüzemhez a részletesebb A DiKAS virtuális gépként Windows alatt útmutató érvényes. Ott különösen fontos a külső virtuális kapcsoló, valamint a 2. generáció kikapcsolt Secure Boottal.

Lépésről lépésre (Hyper-V-kezelő, grafikus felület):

Nyissa meg a Hyper-V-kezelőt → jobb oldalon Új → Virtuális gép.
Válassza a 2. generációt, majd a Beállítások → Biztonság alatt kapcsolja ki a Secure Bootot (az ISO nincs aláírva a Microsoft Secure Boot-kulcsával).
Memória: 2048 MB (vagy több, lásd a rendszerkövetelményeket). A „Dinamikus memória“ bekapcsolva maradhat.
Virtuális merevlemez: hozzon létre egy új, 20 GB-os VHDX-et.
Hálózati kapcsolatként válasszon egy külső virtuális kapcsolót; enélkül a pénztár a helyi hálózat többi eszközéről nem érhető el.
Telepítési beállítások: „Operációs rendszer telepítése rendszerindító CD/DVD-ROM-ról“ → Képfájl (.iso) → válassza ki a dikas.iso fájlt.
Indítsa el a virtuális gépet, és csatlakozzon hozzá.

Másik lehetőség PowerShell-lel (rendszergazdaként):

# Generation 2 (UEFI), Secure Boot fuer das DiKAS-ISO ausschalten
New-VM -Name "DiKAS" -Generation 2 -MemoryStartupBytes 2GB `
  -NewVHDPath "C:\VMs\DiKAS.vhdx" -NewVHDSizeBytes 20GB `
  -SwitchName "DiKAS-Netzwerk"
Set-VM -Name "DiKAS" -ProcessorCount 2
Add-VMDvdDrive -VMName "DiKAS" -Path "C:\ISOs\dikas.iso"
Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off
Set-VMFirmware -VMName "DiKAS" -FirstBootDevice (Get-VMDvdDrive -VMName "DiKAS")
Start-VM -Name "DiKAS"

2. generáció + Secure Boot kikapcsolva

2. generációs virtuális gépben a Secure Bootot ki kell kapcsolni, különben az ISO nem bootol:

Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off

A.2 — VirtualBox (Windows / macOS / Linux)¶

Windows alatt a VirtualBox elsősorban a Windows Home kiadáshoz készült, mert ott a Hyper-V nem érhető el. Ügyfélüzemhez a részletesebb A DiKAS virtuális gépként Windows alatt útmutató érvényes.

Lépésről lépésre (grafikus felület):

Új → név: DiKAS, típus: Linux, verzió: Arch Linux (64-bit).
Memória: 2048 MB vagy több.
Merevlemez: „Virtuális merevlemez létrehozása most“ → VDI → dinamikus → 20 GB.
Jelölje ki a virtuális gépet → Módosítás → Háttértár → az optikai meghajtóba helyezze be a dikas.iso képfájlt.
Módosítás → Hálózat → 1. adapter: NAT helyett válassza a Hálózati híd lehetőséget, és válassza ki a fizikai Ethernet-/WLAN-adaptert. Csak így érhető el a pénztár a helyi hálózatról.
(Opcionális) Rendszer → Alaplap → EFI engedélyezése, ha UEFI-t szeretne tesztelni — az ISO azonban a szabványos BIOS-módban is bootol.
Indítsa el a virtuális gépet.

Másik lehetőség parancssorból (VBoxManage):

VBoxManage createvm --name "DiKAS" --ostype "ArchLinux_64" --register
VBoxManage modifyvm "DiKAS" --memory 2048 --cpus 2 --nic1 bridged --bridgeadapter1 "Ethernet"
VBoxManage createhd --filename "DiKAS.vdi" --size 20480
VBoxManage storagectl "DiKAS" --name "SATA" --add sata --controller IntelAhci
VBoxManage storageattach "DiKAS" --storagectl "SATA" \
  --port 0 --device 0 --type hdd --medium "DiKAS.vdi"
VBoxManage storageattach "DiKAS" --storagectl "SATA" \
  --port 1 --device 0 --type dvddrive --medium "dikas.iso"
VBoxManage startvm "DiKAS"

A.3 — Linux-gazdagép (KVM/QEMU)¶

Linux-gazdagépen (Debian/Ubuntu/Arch) az ISO a legegyszerűbben KVM/QEMU-val bootol, kényelmesen akár a virt-manager segítségével is.

Virtualizáció telepítése:

# Debian / Ubuntu
sudo apt install qemu-kvm libvirt-daemon-system virtinst virt-manager

# Arch / CachyOS
sudo pacman -S qemu-full libvirt virt-install virt-manager

Virtuális gép létrehozása és az ISO bootolása (virt-install):

virt-install \
  --name dikas \
  --memory 2048 \
  --vcpus 2 \
  --disk path=/var/lib/libvirt/images/dikas.qcow2,size=20 \
  --cdrom /pfad/zu/dikas.iso \
  --os-variant archlinux \
  --graphics spice

Vagy közvetlenül QEMU-val (libvirt nélkül):

qemu-img create -f qcow2 dikas.qcow2 20G
qemu-system-x86_64 -enable-kvm -m 2048 -smp 2 \
  -drive file=dikas.qcow2,if=virtio \
  -cdrom dikas.iso -boot d

UEFI tesztelése (OVMF)

Ha a virtuális gépnek UEFI-vel kell bootolnia, a virt-install parancsot egészítse ki a --boot uefi kapcsolóval, QEMU esetén pedig adjon meg egy OVMF-firmware-t (-bios /usr/share/OVMF/OVMF_CODE.fd). Az ISO mindkét bootmódot támogatja.

Az appliance első indítása¶

A bootmenüben válassza a DiKAS Install pontot. Ez az út további kérdés nélkül formázza a virtuális merevlemezt, telepíti az appliance-t, majd újraindítja.
Vegye ki az ISO-t a virtuális DVD-meghajtóból, hogy a virtuális gép a jövőben a virtuális merevlemezről induljon.
A felületen válassza a Pénztár telepítése lehetőséget, és adja meg a telepítési kulcsot.
A pénztár a helyi hálózatban a https://<IP-Adresse-der-VM> címen érhető el. Az első megnyitáskor egyszer erősítse meg az önaláírt tanúsítványra vonatkozó figyelmeztetést.

Az IP-címet a router osztja ki. Ez a router eszközlistájában látható; Hyper-V alatt emellett a következő PowerShell-paranccsal is megjeleníthető:

Get-VMNetworkAdapter -VMName "DiKAS" | Select-Object -ExpandProperty IPAddresses

Ügyfélüzemhez — beleértve az automatikus indítást, a hálózatot és a hardvert — a Windows-VM útmutató érvényes.

B változat: fejlesztői környezet (`dotnet` + `ng`)¶

API-fejlesztéshez és testreszabáshoz a backend (.NET 10) és a frontend (Angular) külön indul.

Előfeltételek:

.NET 10 SDK (dotnet)
Node.js 24 + npm
(opcionális) CouchDB adatbázisként — helyette SQLite is használható (lásd lent)

A backend indítása¶

cd Dikas.Api
dotnet build Dikas.Api.Web/Dikas.Api.Web.csproj
dotnet run --project Dikas.Api.Web --urls http://localhost:5015

Arch Linux / CachyOS: kerülőmegoldás a buildhez

Arch-alapú rendszereken a build esetleg NU1101 (arch-x64 AppHost) hibával meghiúsul. Ilyenkor egészítse ki a -p:UseAppHost=false kapcsolóval:

dotnet build Dikas.Api.Web/Dikas.Api.Web.csproj -p:UseAppHost=false
dotnet run --project Dikas.Api.Web --urls http://localhost:5015 -p:UseAppHost=false

A frontend indítása¶

cd dikas-next
npm ci
npx ng serve dikas-web --port 4200

A fejlesztői szerver az /api, /hubs, /rest és /version hívásokat automatikusan továbbítja az 5015-ös porton futó backendnek.

Mindig a frontenden keresztül teszteljen

Az alkalmazást a http://localhost:4200 címen nyissa meg (ne közvetlenül az 5015-ös porton futó backenden keresztül) — csak így működik az API-hívások proxy-továbbítása.

A demópénztár indítása¶

A demópénztár egy üres adatbázist valósághű mintaadatokkal tölt fel (termékek, asztalok, személyzet, forgalom), és ez a leggyorsabb út egy kezelhető pénztárhoz.

Minimális demó SQLite-tal (egy parancs)¶

Teljes vendéglátós demó CouchDB nélkül — a backend automatikusan létrehoz egy SQLite-fájlt (dikas.db), és feltölti mintaadatokkal:

cd Dikas.Api
env Database__Provider=Sqlite \
    DemoSeed__Mode=gastro \
    ASPNETCORE_ENVIRONMENT=Development \
  dotnet run --project Dikas.Api.Web --urls http://localhost:5015

Ezután indítsa el a frontendet (lásd a B változatot), és jelentkezzen be a böngészőben.

Migráció nélkül

Az SQLite-séma indításkor automatikusan létrejön és egyeztetésre kerül (SqlDbInitService) — adatbázis-migrációt nem kell futtatnia.

Demómódok¶

A kívánt adatkészletet a DemoSeed__Mode környezeti változóval lehet kiválasztani:

`DemoSeed__Mode`	Ágazat / tartalom
`basic`	Trafik / pékség (közvetlen értékesítés)
`gastro` (alapértelmezett)	Étterem asztalokkal
`delivery`	Házhozszállítás
`club`	Diszkó / klub
`full`	Teljes felszereltség — minden modul aktív

Bejelentkezés¶

Mező	Érték
Felhasználó	`admin`
Jelszó	`admin`

A mintaadatok csak üres adatbázisba kerülnek

A demóadatok csak üres adatbázisba töltődnek be. Az újbóli feltöltéshez (pl. másik módban) friss adatbázisra van szükség:

SQLite: törölje a dikas.db fájlt a content-root könyvtárban.
CouchDB: állítson be új CouchDb__DatabasePrefix értéket (vagy törölje a meglévő adatbázisokat).

Ezután indítsa újra a backendet a kívánt DemoSeed__Mode értékkel.

Helyi API-fejlesztés¶

Alapadatok¶

	Érték
API alap-URL	`http://localhost:5015/api/v1/`
Swagger / OpenAPI	`http://localhost:5015/swagger` (csak debug buildben)
Állapotellenőrzés (health check)	`GET http://localhost:5015/healthz`
Alapértelmezett adatbázis	CouchDB a `http://localhost:5984` címen
Alternatív adatbázis	SQLite — környezeti változó: `Database__Provider=Sqlite` (`dikas.db` fájl a content-root könyvtárban)

Hitelesítés (JWT)¶

Az API JWT Bearer-tokeneket használ. A tokent a bejelentkezési végponton lehet igényelni, és 480 percig (8 óráig) érvényes.

1. Token igénylése:

curl -s http://localhost:5015/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}'

A token a válaszban a data.accessToken alatt található. Átvétele egy shell-változóba:

TOKEN=$(curl -s http://localhost:5015/api/v1/auth/login \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin"}' \
  | python3 -c 'import sys,json; print(json.load(sys.stdin)["data"]["accessToken"])')

2. Hitelesített hívás végrehajtása — a tokent az Authorization fejlécben adja át:

curl -s http://localhost:5015/api/v1/articles \
  -H "Authorization: Bearer $TOKEN"

3. Állapotellenőrzés (bejelentkezés nélkül):

curl http://localhost:5015/healthz

Végpontok felfedezése

Az összes elérhető végpontot paraméterekkel és példaválaszokkal együtt interaktívan a http://localhost:5015/swagger címen találja (debug build). Magyarázó áttekintést a REST API oldal is nyújt.

Lejárt a token?

Ha a token 8 óra után lejár, az alkalmazás állapota a böngészőben furcsán viselkedhet. Egyszerűen jelentkezzen ki, majd be újra, vagy igényeljen új tokent.

Következő lépések¶

Telepítés és üzembe helyezés — éles telepítés ISO-val
Adatbázis — CouchDB vs. SQLite, konfiguráció
REST API — teljes API-dokumentáció
API-referencia (Swagger) — interaktív végpont-áttekintés