Lokales Testing & Installation¶

Diese Seite zeigt, wie Sie DiKAS selbst ausprobieren, lokal installieren und für die Entwicklung betreiben. Sie richtet sich an Integratoren, Administratoren und Entwickler.

Es gibt zwei Wege, DiKAS lokal zu betreiben:

Variante	Geeignet für	Aufwand
A — ISO-Appliance in einer VM	Realistischer Probebetrieb wie auf echter Kassen-Hardware	Gering
B — Entwickler-Setup (`dotnet` + `ng`)	API-Entwicklung, Anpassungen, Debugging	Höher

Nur schnell die Kasse anschauen?

Wenn Sie DiKAS nur unverbindlich testen möchten, ist Variante A (ISO in einer VM) der schnellste Weg zu einer vollständigen Kasse. Für eine reine API-/Frontend-Demo ohne VM eignet sich die Demo-Kasse weiter unten (SQLite + Demo-Daten, ein einziger Befehl).

Systemvoraussetzungen¶

Server / VM¶

Gleichzeitig aktive Kassen/Clients	Minimum	Empfohlen
Bis 5	2 GB RAM, 2 Kerne	4 GB RAM, 2 Kerne
6–20	4 GB RAM, 2 Kerne	4 GB RAM, 4 Kerne
Mehr als 20	4 GB RAM, 4 Kerne	ab 8 GB RAM, 4 Kerne; nach Last dimensionieren

Angelegte Benutzer und Arbeitsplätze belegen nicht dauerhaft zusätzliche Serverleistung. Für die Dimensionierung zählen gleichzeitig aktive Clients, Zusatzdienste und große Auswertungen oder Datenimporte.

Festplatte / virtuelle Disk¶

Einsatz	Minimum	Empfohlen
ISO-Appliance in der VM	20 GB (Betriebssystem + Datenbank + Demo-Daten)	32 GB
Entwickler-Setup	je nach SDK/Tooling, ca. 10–15 GB	20 GB

Faustregel für die ISO-VM

Für die ISO-Appliance reichen zum Ausprobieren 2 GB RAM und 20 GB Disk. Für längeren Betrieb oder mehr als fünf gleichzeitig aktive Clients sind 4 GB RAM empfehlenswert. Bei vielen Belegbildern, lokalen Sicherungen oder langer Aufbewahrung muss die Disk entsprechend größer sein.

Variante A: ISO-Appliance in einer VM¶

Die DiKAS-Appliance ist ein fertiges, bootfähiges Betriebssystem-Image auf Basis von Arch Linux (archiso). Es bringt die DikasArch-Anwendung (.NET 10) und die Datenbank bereits mit — ideal, um DiKAS unter realistischen Bedingungen zu testen, ohne ein Betriebssystem aufzusetzen.

ISO herunterladen¶

Das aktuelle ISO-Image (derzeit ca. 1,1 GB, bootet sowohl per UEFI als auch BIOS) liegt unter:

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

Woraus besteht die Appliance?

Das Image wird im Repo dikasiso gebaut (sh make.sh). Die eigentliche Kassen-Anwendung ist dikasarch (Arch-Paket dikasarch10-*.pkg.tar.zst, .NET 10). Für den Testbetrieb müssen Sie davon nichts selbst bauen — laden Sie einfach die fertige ISO.

A.1 — Hyper-V (Windows)¶

Hyper-V ist auf Windows Pro/Enterprise und Windows Server enthalten. Für Kundenbetrieb gilt die ausführlichere Anleitung DiKAS als virtuelle Maschine unter Windows. Besonders wichtig sind dort der externe virtuelle Switch sowie Generation 2 mit ausgeschaltetem Secure Boot.

Schritt für Schritt (Hyper-V-Manager, grafisch):

Hyper-V-Manager öffnen → rechts Neu → Virtueller Computer.
Generation 2 wählen und anschließend unter Einstellungen → Sicherheit Secure Boot deaktivieren (das ISO ist nicht für den Microsoft-Secure-Boot-Schlüssel signiert).
Arbeitsspeicher: 2048 MB (oder mehr, siehe Systemvoraussetzungen). „Dynamischen Arbeitsspeicher" können Sie aktiviert lassen.
Virtuelle Festplatte: neue VHDX mit 20 GB anlegen.
Als Netzwerkverbindung einen externen virtuellen Switch wählen; ohne ihn ist die Kasse von anderen Geräten im lokalen Netz nicht erreichbar.
Installationsoptionen: „Von bootfähiger CD/DVD-ROM installieren" → Imagedatei (.iso) → dikas.iso auswählen.
VM starten und mit der VM verbinden.

Alternativ per PowerShell (als Administrator):

# 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"

Generation 2 + Secure Boot aus

In einer Generation-2-VM muss Secure Boot aus sein, sonst bootet das ISO nicht:

Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off

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

VirtualBox ist unter Windows vor allem für Windows Home vorgesehen, weil Hyper-V dort nicht verfügbar ist. Für Kundenbetrieb gilt die ausführlichere Anleitung DiKAS als virtuelle Maschine unter Windows.

Schritt für Schritt (grafisch):

Neu → Name DiKAS, Typ Linux, Version Arch Linux (64-bit).
Arbeitsspeicher: 2048 MB oder mehr.
Festplatte: „Jetzt eine virtuelle Festplatte erzeugen" → VDI → dynamisch → 20 GB.
VM markieren → Ändern → Massenspeicher → beim optischen Laufwerk das ISO dikas.iso einlegen.
Ändern → Netzwerk → Adapter 1: Netzwerkbrücke statt NAT wählen und den physischen Ethernet-/WLAN-Adapter auswählen. Nur so ist die Kasse aus dem lokalen Netz erreichbar.
(Optional) System → Hauptplatine → EFI aktivieren, falls Sie UEFI testen möchten — das ISO bootet aber auch im Standard-BIOS-Modus.
VM starten.

Alternativ per Kommandozeile (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-Host (KVM/QEMU)¶

Auf einem Linux-Host (Debian/Ubuntu/Arch) bootet das ISO am einfachsten mit KVM/QEMU, optional komfortabel über virt-manager.

Virtualisierung installieren:

# 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

VM anlegen und ISO booten (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

Oder direkt mit QEMU (ohne libvirt):

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 testen (OVMF)

Soll die VM per UEFI booten, ergänzen Sie bei virt-install --boot uefi bzw. bei QEMU eine OVMF-Firmware (-bios /usr/share/OVMF/OVMF_CODE.fd). Das ISO unterstützt beide Boot-Modi.

Erststart der Appliance¶

Im Bootmenü DiKAS Install auswählen. Dieser Weg formatiert die virtuelle Festplatte ohne weitere Nachfrage, installiert die Appliance und startet sie anschließend neu.
Das ISO aus dem virtuellen DVD-Laufwerk entfernen, damit die VM künftig von der virtuellen Festplatte startet.
In der Oberfläche Kasse installieren wählen und den Installationsschlüssel eingeben.
Die Kasse ist im lokalen Netz unter https://<IP-Adresse-der-VM> erreichbar. Die selbstsignierte Zertifikatswarnung beim ersten Aufruf einmalig bestätigen.

Die IP-Adresse vergibt der Router. Sie steht in dessen Geräteliste; unter Hyper-V kann sie zusätzlich mit folgendem PowerShell-Befehl angezeigt werden:

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

Für den Kundenbetrieb einschließlich Autostart, Netzwerk und Hardware gilt die Windows-VM-Anleitung.

TSE in der VM (USB/IP)¶

Läuft DiKAS in einer VM und soll eine Hardware-TSE (Swissbit-USB-Stick) nutzen, wird der Stick vom Host (dem Rechner, an dem er steckt) über USB/IP in die VM durchgereicht. DiKAS in der VM erkennt und mountet die TSE anschließend automatisch.

Wann brauche ich das?

Nur bei einer Hardware-TSE (Swissbit) in einer VM. Bei einer Cloud-TSE (fiskaly) ist keine USB-Durchreiche nötig — die läuft komplett über das Internet. Auf echter Kassen-Hardware (Mini-PC) steckt der TSE-Stick direkt am Gerät, ganz ohne USB/IP.

1. Am Host (Linux) den USB/IP-Dienst starten und die TSE freigeben:

# usbip-Werkzeuge installieren (Beispiel Debian/Ubuntu)
sudo apt install usbip

# USB/IP-Server starten
sudo usbipd -D

# angeschlossene USB-Geräte auflisten und die Swissbit-TSE finden (VID:PID 1370:0505)
usbip list -l

# die TSE über ihre Bus-ID freigeben (z. B. 1-2)
sudo usbip bind -b 1-2

2. In der VM (DiKAS-Appliance) das Gerät anhängen:

In DikasArch das Zahnrad → USB / IP öffnen.
Die IP-Adresse des Rechners eintragen, der das USB-Gerät freigibt.
Geräte suchen und beim gewünschten Gerät Verbinden wählen.

DikasArch lädt das benötigte Gast-Modul, bindet das Gerät ein und speichert die Verbindung. Nach einem Neustart versucht DikasArch automatisch, sie wiederherzustellen. Das Gerät lässt sich auf derselben Seite wieder trennen; anschließend kann seine Freigabe am Host aufgehoben werden.

Im Dauerbetrieb

Für den produktiven Dauerbetrieb ist die echte Kassen-Hardware (Mini-PC mit direkt angestecktem TSE-Stick) oder die Cloud-TSE die robustere Wahl. Die USB/IP-Durchreiche eignet sich vor allem für Test- und Übergangs-Setups.

Variante B: Entwickler-Setup (`dotnet` + `ng`)¶

Für API-Entwicklung und Anpassungen werden Backend (.NET 10) und Frontend (Angular) getrennt gestartet.

Voraussetzungen:

.NET 10 SDK (dotnet)
Node.js 24 + npm
(optional) CouchDB als Datenbank — alternativ SQLite (siehe unten)

Backend starten¶

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: Build-Workaround

Auf Arch-basierten Systemen schlägt der Build evtl. mit NU1101 (arch-x64 AppHost) fehl. Ergänzen Sie dann -p:UseAppHost=false:

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

Frontend starten¶

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

Der Dev-Server leitet /api, /hubs, /rest und /version automatisch an das Backend auf Port 5015 weiter.

Immer über das Frontend testen

Öffnen Sie die Anwendung über http://localhost:4200 (nicht direkt über das Backend auf 5015) — nur so greift die Proxy-Weiterleitung der API-Aufrufe.

Demo-Kasse starten¶

Die Demo-Kasse befüllt eine leere Datenbank mit realistischen Beispieldaten (Artikel, Tische, Personal, Umsätze) und ist der schnellste Weg zu einer bedienbaren Kasse.

Minimal-Demo mit SQLite (ein Befehl)¶

Eine vollständige Gastro-Demo ganz ohne CouchDB — das Backend legt automatisch eine SQLite-Datei (dikas.db) an und seedet sie:

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

Anschließend das Frontend starten (siehe Variante B) und im Browser anmelden.

Migrations-frei

Das SQLite-Schema wird beim Start automatisch erzeugt und abgeglichen (SqlDbInitService) — Sie müssen keine Datenbank-Migration ausführen.

Demo-Modi¶

Der gewünschte Datensatz wird über die Umgebungsvariable DemoSeed__Mode gewählt:

`DemoSeed__Mode`	Branche / Inhalt
`basic`	Kiosk / Bäckerei (Direktverkauf)
`gastro` (Standard)	Restaurant mit Tischen
`delivery`	Lieferservice
`club`	Disco / Club
`full`	Vollausstattung — alle Module aktiv

Anmeldung¶

Feld	Wert
Benutzer	`admin`
Passwort	`admin`

Seed läuft nur bei leerer Datenbank

Die Demo-Daten werden nur in eine leere Datenbank eingespielt. Zum erneuten Seeden (z. B. anderer Modus) brauchen Sie eine frische Datenbank:

SQLite: Datei dikas.db im Content-Root löschen.
CouchDB: einen neuen CouchDb__DatabasePrefix setzen (oder die bestehenden DBs löschen).

Danach das Backend mit dem gewünschten DemoSeed__Mode neu starten.

Lokale API-Entwicklung¶

Eckdaten¶

	Wert
API-Basis-URL	`http://localhost:5015/api/v1/`
Swagger / OpenAPI	`http://localhost:5015/swagger` (nur in Debug-Builds)
Health-Check	`GET http://localhost:5015/healthz`
Standard-Datenbank	CouchDB unter `http://localhost:5984`
Alternative DB	SQLite — Env `Database__Provider=Sqlite` (Datei `dikas.db` im Content-Root)

Authentifizierung (JWT)¶

Die API verwendet JWT-Bearer-Token. Ein Token wird über den Login-Endpoint angefordert und gilt 480 Minuten (8 Stunden).

1. Token anfordern:

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

Der Token steht in der Antwort unter data.accessToken. In ein Shell-Variable übernehmen:

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. Authentifizierten Aufruf ausführen — Token im Authorization-Header mitgeben:

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

3. Health-Check (ohne Anmeldung):

curl http://localhost:5015/healthz

Endpunkte erkunden

Alle verfügbaren Endpunkte samt Parametern und Beispiel-Antworten finden Sie interaktiv unter http://localhost:5015/swagger (Debug-Build). Eine erklärende Übersicht bietet außerdem die REST API-Seite.

Token abgelaufen?

Läuft der Token nach 8 Stunden ab, kann sich der App-Zustand im Browser eigenartig verhalten. Einfach ausloggen und neu anmelden bzw. ein neues Token anfordern.

Nächste Schritte¶

Installation & Deployment — produktive Installation per ISO
Datenbank — CouchDB vs. SQLite, Konfiguration
REST API — vollständige API-Dokumentation
API-Referenz (Swagger) — interaktive Endpoint-Übersicht