Local Testing & Installation¶

This page shows how you can try out DiKAS yourself, install it locally, and run it for development. It is aimed at integrators, administrators, and developers.

There are two ways to run DiKAS locally:

Variant	Suitable for	Effort
A — ISO appliance in a VM	Realistic trial operation, like on real POS hardware	Low
B — Developer setup (`dotnet` + `ng`)	API development, customization, debugging	Higher

Just Want to Take a Quick Look at the POS?

If you just want to try DiKAS out without obligation, variant A (ISO in a VM) is the fastest way to a complete POS. For a pure API/frontend demo without a VM, the demo POS further below is a good fit (SQLite + demo data, a single command).

System Requirements¶

Server / VM¶

Variant	Minimum	Recommended
Small business (1–2 tills)	2 GB RAM, 2 cores	4 GB RAM, 4 cores
Medium business (3–5 tills)	4 GB RAM, 4 cores	8 GB RAM, 4 cores
Large business (5+ tills)	8 GB RAM, 4 cores	16 GB RAM, 8 cores

Disk / Virtual Disk¶

Use	Minimum	Recommended
ISO appliance in the VM	20 GB (operating system + database + demo data)	40 GB
Developer setup	depending on SDK/tooling, approx. 10–15 GB	20 GB

Rule of Thumb for the ISO VM

For trying out the ISO appliance, 2 GB RAM (1–2 tills) and 20 GB disk are sufficient. For several simultaneous tills or longer trial operation, 4 GB RAM or more is recommended — use the table above as a guide.

Variant A: ISO Appliance in a VM¶

The DiKAS appliance is a ready-made, bootable operating system image based on Arch Linux (archiso). It already comes with the DikasArch application (.NET 10) and the database — ideal for testing DiKAS under realistic conditions without setting up an operating system.

Downloading the ISO¶

The current ISO image (approx. 500 MB–1 GB, boots via both UEFI and BIOS) is located at:

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

What Is the Appliance Made Of?

The image is built in the dikasiso repo (sh make.sh). The actual POS application is dikasarch (Arch package dikasarch10-*.pkg.tar.zst, .NET 10). For test operation, you don't need to build any of this yourself — simply download the ready-made ISO.

A.1 — Hyper-V (Windows)¶

Hyper-V is included in Windows 10/11 Pro and Windows Server (enable the "Hyper-V" feature).

Step by step (Hyper-V Manager, GUI):

Open Hyper-V Manager → on the right, New → Virtual Machine.
Select Generation 1 (BIOS boot, works fine with archiso). Generation 2 (UEFI) also works — in that case Secure Boot must be disabled (the ISO is not signed for the Microsoft Secure Boot key).
Memory: 2048 MB (or more, see system requirements). You can leave "Dynamic Memory" enabled.
Virtual hard disk: create a new VHDX with 20 GB.
Installation options: "Install an operating system from a bootable image file" → Image file (.iso) → select dikas.iso.
Start the VM and connect to it.

Alternatively via PowerShell (as administrator):

# Generation 1 (BIOS) - simplest approach
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

If you use a Generation 2 VM, Secure Boot must be off, otherwise the ISO won't boot:

Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off

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

VirtualBox is free and runs on all major operating systems.

Step by step (GUI):

New → name DiKAS, type Linux, version Arch Linux (64-bit).
Memory: 2048 MB or more.
Hard disk: "Create a virtual hard disk now" → VDI → dynamically allocated → 20 GB.
Select the VM → Settings → Storage → insert the ISO dikas.iso into the optical drive.
(Optional) System → Motherboard → Enable EFI, if you want to test UEFI — the ISO also boots fine in standard BIOS mode.
Start the VM.

Alternatively via the command line (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)¶

On a Linux host (Debian/Ubuntu/Arch), the ISO boots most easily with KVM/QEMU, optionally in a convenient way via virt-manager.

Installing virtualization:

# 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

Creating the VM and booting the ISO (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

Or directly with QEMU (without 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

Testing UEFI (OVMF)

If the VM should boot via UEFI, add --boot uefi to virt-install, or an OVMF firmware for QEMU (-bios /usr/share/OVMF/OVMF_CODE.fd). The ISO supports both boot modes.

First Boot of the Appliance¶

After booting, the appliance installs/starts DiKAS on the virtual system. The POS is then reachable in the browser.

TODO — Appliance First-Boot Details

The exact local address/port of the appliance after startup, the installation process onto the virtual disk, and the first login were not verified at the time of writing this documentation and are marked here as a placeholder. Please fill in from the appliance/dikasiso documentation (e.g. "POS reachable at http://<VM-IP>:<Port>, log in with …").

TSE in the VM (USB/IP)¶

If DiKAS runs in a VM and needs to use a hardware TSE (Swissbit USB stick), the stick is passed through from the host (the computer it's plugged into) into the VM via USB/IP. DiKAS in the VM then automatically detects and mounts the TSE.

When Do I Need This?

Only with a hardware TSE (Swissbit) in a VM. With a cloud TSE (fiskaly), no USB pass-through is needed — it runs entirely over the internet. On real POS hardware (mini PC), the TSE stick plugs directly into the device, with no USB/IP at all.

1. On the host (Linux), start the USB/IP service and release the TSE:

# install usbip tools (example for Debian/Ubuntu)
sudo apt install usbip

# start the USB/IP server
sudo usbipd -D

# list connected USB devices and find the Swissbit TSE (VID:PID 1370:0505)
usbip list -l

# release the TSE via its bus ID (e.g. 1-2)
sudo usbip bind -b 1-2

2. In the VM (DiKAS appliance), attach the TSE:

# host address = the VM's gateway (usually 10.0.2.2 with NAT,
# otherwise the host's IP on the network)
sudo usbip attach -r 10.0.2.2 -b 1-2

DiKAS detects the TSE stick via hotplug, mounts it, and uses it from that point on for signing receipts — no further configuration is needed. In the POS's TSE settings, the TSE appears as connected.

3. To disconnect it again later (on the host):

sudo usbip unbind -b 1-2

For Ongoing Operation

For productive, ongoing operation, real POS hardware (mini PC with a directly attached TSE stick) or a cloud TSE is the more robust choice. USB/IP pass-through is mainly suited to test and transitional setups.

Variant B: Developer Setup (`dotnet` + `ng`)¶

For API development and customization, the backend (.NET 10) and frontend (Angular) are started separately.

Prerequisites:

.NET 10 SDK (dotnet)
Node.js 24 + npm
(optional) CouchDB as the database — alternatively SQLite (see below)

Starting the Backend¶

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

On Arch-based systems, the build may fail with NU1101 (arch-x64 AppHost). In that case, add -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

Starting the Frontend¶

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

The dev server automatically forwards /api, /hubs, /rest, and /version to the backend on port 5015.

Always Test Through the Frontend

Open the application via http://localhost:4200 (not directly via the backend on 5015) — only this way does the proxy forwarding of the API calls take effect.

Starting the Demo POS¶

The demo POS fills an empty database with realistic sample data (articles, tables, staff, revenue) and is the fastest way to a working POS.

Minimal Demo with SQLite (One Command)¶

A complete restaurant demo entirely without CouchDB — the backend automatically creates a SQLite file (dikas.db) and seeds it:

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

Then start the frontend (see variant B) and log in in the browser.

Migration-Free

The SQLite schema is automatically created and reconciled at startup (SqlDbInitService) — you don't need to run any database migration.

Demo Modes¶

The desired dataset is chosen via the environment variable DemoSeed__Mode:

`DemoSeed__Mode`	Industry / Content
`basic`	Kiosk / bakery (direct sale)
`gastro` (default)	Restaurant with tables
`delivery`	Delivery service
`club`	Disco / club
`full`	Full setup — all modules active

Field	Value
Username	`admin`
Password	`admin`

Seeding Only Runs on an Empty Database

The demo data is only loaded into an empty database. To seed again (e.g. a different mode), you need a fresh database:

SQLite: delete the file dikas.db in the content root.
CouchDB: set a new CouchDb__DatabasePrefix (or delete the existing DBs).

Then restart the backend with the desired DemoSeed__Mode.

Local API Development¶

Key Facts¶

	Value
API base URL	`http://localhost:5015/api/v1/`
Swagger / OpenAPI	`http://localhost:5015/swagger` (only in debug builds)
Health check	`GET http://localhost:5015/healthz`
Default database	CouchDB at `http://localhost:5984`
Alternative DB	SQLite — env `Database__Provider=Sqlite` (file `dikas.db` in the content root)

Authentication (JWT)¶

The API uses JWT bearer tokens. A token is requested via the login endpoint and is valid for 480 minutes (8 hours).

1. Request a token:

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

The token is found in the response under data.accessToken. Store it in a shell variable:

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. Make an authenticated call — pass the token in the Authorization header:

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

3. Health check (without logging in):

curl http://localhost:5015/healthz

Exploring the Endpoints

You can find all available endpoints, along with parameters and example responses, interactively at http://localhost:5015/swagger (debug build). The REST API page also offers an explanatory overview.

Token Expired?

If the token expires after 8 hours, the app state in the browser may behave oddly. Simply log out and log in again, or request a new token.

Next Steps¶

Installation & Deployment — production installation via ISO
Database — CouchDB vs. SQLite, configuration
REST API — complete API documentation
API Reference (Swagger) — interactive endpoint overview