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

Variante	Minimum	Empfohlen
Kleiner Betrieb (1–2 Kassen)	2 GB RAM, 2 Kerne	4 GB RAM, 4 Kerne
Mittlerer Betrieb (3–5 Kassen)	4 GB RAM, 4 Kerne	8 GB RAM, 4 Kerne
Großer Betrieb (5+ Kassen)	8 GB RAM, 4 Kerne	16 GB RAM, 8 Kerne

Festplatte / virtuelle Disk

Einsatz	Minimum	Empfohlen
ISO-Appliance in der VM	20 GB (Betriebssystem + Datenbank + Demo-Daten)	40 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 (1–2 Kassen) und 20 GB Disk. Für mehrere gleichzeitige Kassen oder längeren Probebetrieb sind 4 GB RAM und mehr empfehlenswert — orientieren Sie sich an der Tabelle oben.

---

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 (ca. 500 MB–1 GB, bootet sowohl per UEFI als auch BIOS) liegt unter:

https://s3.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 10/11 Pro und Windows Server enthalten (Feature „Hyper-V" aktivieren).

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

1. Hyper-V-Manager öffnen → rechts Neu → Virtueller Computer.
2. Generation 1 wählen (BIOS-Boot, problemlos mit archiso). Generation 2 (UEFI) funktioniert ebenfalls — dann muss Secure Boot deaktiviert werden (das ISO ist nicht für den Microsoft-Secure-Boot-Schlüssel signiert).
3. Arbeitsspeicher: 2048 MB (oder mehr, siehe Systemvoraussetzungen). „Dynamischen Arbeitsspeicher" können Sie aktiviert lassen.
4. Virtuelle Festplatte: neue VHDX mit 20 GB anlegen.
5. Installationsoptionen: „Von bootfähiger CD/DVD-ROM installieren" → Imagedatei (.iso) → dikas.iso auswählen.
6. VM starten und mit der VM verbinden.

Alternativ per PowerShell (als Administrator):

# Generation 1 (BIOS) - einfachster Weg
New-VM -Name "DiKAS" -Generation 1 -MemoryStartupBytes 2GB `
  -NewVHDPath "C:\VMs\DiKAS.vhdx" -NewVHDSizeBytes 20GB
Set-VM -Name "DiKAS" -ProcessorCount 2
Add-VMDvdDrive -VMName "DiKAS" -Path "C:\ISOs\dikas.iso"
Start-VM -Name "DiKAS"

Generation 2 + Secure Boot

Falls Sie eine Generation-2-VM verwenden, muss Secure Boot aus sein, sonst bootet das ISO nicht:

Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off

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

VirtualBox ist kostenlos und läuft auf allen großen Betriebssystemen.

Schritt für Schritt (grafisch):

1. Neu → Name DiKAS, Typ Linux, Version Arch Linux (64-bit).
2. Arbeitsspeicher: 2048 MB oder mehr.
3. Festplatte: „Jetzt eine virtuelle Festplatte erzeugen" → VDI → dynamisch → 20 GB.
4. VM markieren → Ändern → Massenspeicher → beim optischen Laufwerk das ISO dikas.iso einlegen.
5. (Optional) System → Hauptplatine → EFI aktivieren, falls Sie UEFI testen möchten — das ISO bootet aber auch im Standard-BIOS-Modus.
6. VM starten.

Alternativ per Kommandozeile (VBoxManage):

VBoxManage createvm --name "DiKAS" --ostype "ArchLinux_64" --register
VBoxManage modifyvm "DiKAS" --memory 2048 --cpus 2 --nic1 nat
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

Nach dem Booten installiert/startet die Appliance DiKAS auf dem virtuellen System. Anschließend ist die Kasse im Browser erreichbar.

TODO — Erststart-Details der Appliance

Die genaue lokale Adresse/Port der Appliance nach dem Start, der Installationsablauf auf die virtuelle Disk und die Erstanmeldung waren zum Zeitpunkt dieser Doku nicht verifiziert und sind hier als Platzhalter markiert. Bitte aus der Appliance-/dikasiso-Dokumentation ergänzen (z. B. „Kasse erreichbar unter http://<VM-IP>:<Port>, Anmeldung mit …").

---

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) die TSE anhängen:

# Host-Adresse = Gateway der VM (bei NAT üblicherweise 10.0.2.2,
# sonst die IP des Host im Netz)
sudo usbip attach -r 10.0.2.2 -b 1-2

DiKAS erkennt den TSE-Stick per Hotplug, bindet ihn ein und nutzt ihn ab sofort für die Beleg-Signierung — eine weitere Einstellung ist nicht nötig. In den TSE-Einstellungen der Kasse erscheint die TSE als verbunden.

3. Später wieder lösen (am Host):

sudo usbip unbind -b 1-2

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