Test locale e installazione¶

Questa pagina mostra come provare DiKAS da soli, installarlo in locale e gestirlo per lo sviluppo. È rivolta a integratori, amministratori e sviluppatori.

Esistono due modi per gestire DiKAS in locale:

Variante	Adatta per	Impegno
A — Appliance ISO in una VM	Prova realistica come su un hardware di cassa reale	Basso
B — Configurazione per sviluppatori (`dotnet` + `ng`)	Sviluppo API, personalizzazioni, debugging	Maggiore

Vuole solo dare un'occhiata rapida alla cassa?

Se desidera solo provare DiKAS senza impegno, la Variante A (ISO in una VM) è la strada più rapida verso una cassa completa. Per una semplice demo API/frontend senza VM è adatta la cassa demo più sotto (SQLite + dati demo, un unico comando).

Requisiti di sistema¶

Server / VM¶

Variante	Minimo	Consigliato
Attività piccola (1–2 casse)	2 GB RAM, 2 core	4 GB RAM, 4 core
Attività media (3–5 casse)	4 GB RAM, 4 core	8 GB RAM, 4 core
Attività grande (5+ casse)	8 GB RAM, 4 core	16 GB RAM, 8 core

Disco fisso / disco virtuale¶

Uso	Minimo	Consigliato
Appliance ISO nella VM	20 GB (sistema operativo + database + dati demo)	40 GB
Configurazione per sviluppatori	a seconda di SDK/strumenti, ca. 10–15 GB	20 GB

Regola pratica per la VM ISO

Per l'appliance ISO bastano, per provare, 2 GB di RAM (1–2 casse) e 20 GB di disco. Per più casse contemporanee o un funzionamento di prova più lungo si consigliano 4 GB di RAM e oltre — si orienti alla tabella qui sopra.

Variante A: appliance ISO in una VM¶

L'appliance DiKAS è un'immagine di sistema operativo pronta e avviabile, basata su Arch Linux (archiso). Include già l'applicazione DikasArch (.NET 10) e il database — ideale per provare DiKAS in condizioni realistiche senza dover installare un sistema operativo.

Scaricare l'ISO¶

L'immagine ISO attuale (ca. 500 MB–1 GB, si avvia sia in UEFI sia in BIOS) si trova qui:

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

Di cosa è composta l'appliance?

L'immagine viene costruita nel repository dikasiso (sh make.sh). L'applicazione di cassa vera e propria è dikasarch (pacchetto Arch dikasarch10-*.pkg.tar.zst, .NET 10). Per il test non deve costruire nulla di questo da sé — basta scaricare l'ISO già pronta.

A.1 — Hyper-V (Windows)¶

Hyper-V è incluso in Windows 10/11 Pro e Windows Server (attivare la funzionalità „Hyper-V").

Passo per passo (Gestione Hyper-V, grafica):

Aprire Gestione Hyper-V → a destra Nuovo → Computer virtuale.
Scegliere Generazione 1 (avvio BIOS, funziona senza problemi con archiso). Anche la Generazione 2 (UEFI) funziona — in tal caso va disattivato Secure Boot (l'ISO non è firmata per la chiave Secure Boot di Microsoft).
Memoria: 2048 MB (o più, vedi requisiti di sistema). La „Memoria dinamica" può restare attivata.
Disco rigido virtuale: creare un nuovo VHDX da 20 GB.
Opzioni di installazione: „Installa il sistema operativo da CD/DVD-ROM avviabile" → file immagine (.iso) → selezionare dikas.iso.
Avviare la VM e connettersi ad essa.

In alternativa tramite PowerShell (come amministratore):

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

Generazione 2 + Secure Boot

Se utilizza una VM di Generazione 2, Secure Boot deve essere disattivato, altrimenti l'ISO non si avvia:

Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off

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

VirtualBox è gratuito e funziona su tutti i principali sistemi operativi.

Passo per passo (grafico):

Nuova → nome DiKAS, tipo Linux, versione Arch Linux (64-bit).
Memoria: 2048 MB o più.
Disco fisso: „Crea ora un disco fisso virtuale" → VDI → dinamico → 20 GB.
Selezionare la VM → Modifica → Archiviazione → nell'unità ottica inserire l'ISO dikas.iso.
(Facoltativo) Sistema → Scheda madre → Attiva EFI, se desidera provare l'UEFI — l'ISO si avvia comunque anche in modalità BIOS standard.
Avviare la VM.

In alternativa da riga di comando (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 — Host Linux (KVM/QEMU)¶

Su un host Linux (Debian/Ubuntu/Arch) l'ISO si avvia più facilmente con KVM/QEMU, facoltativamente in modo più comodo tramite virt-manager.

Installare la virtualizzazione:

# 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

Creare la VM e avviare l'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

Oppure direttamente con QEMU (senza 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

Provare l'UEFI (OVMF)

Se la VM deve avviarsi tramite UEFI, aggiunga in virt-install --boot uefi oppure in QEMU un firmware OVMF (-bios /usr/share/OVMF/OVMF_CODE.fd). L'ISO supporta entrambe le modalità di avvio.

Primo avvio dell'appliance¶

Dopo l'avvio, l'appliance installa/avvia DiKAS sul sistema virtuale. Successivamente la cassa è raggiungibile nel browser.

TODO — Dettagli sul primo avvio dell'appliance

L'indirizzo/porta locale esatta dell'appliance dopo l'avvio, il processo di installazione sul disco virtuale e il primo accesso non erano verificati al momento della stesura di questa documentazione e sono qui contrassegnati come segnaposto. Si prega di integrare dalla documentazione dell'appliance/dikasiso (ad es. „cassa raggiungibile su http://<IP-VM>:<porta>, accesso con …").

TSE nella VM (USB/IP)¶

Se DiKAS gira in una VM e deve utilizzare una TSE hardware (chiavetta USB Swissbit), la chiavetta viene passata dall'host (il computer su cui è inserita) alla VM tramite USB/IP. DiKAS nella VM riconosce e monta quindi automaticamente la TSE.

Quando mi serve?

Solo con una TSE hardware (Swissbit) in una VM. Con una TSE cloud (fiskaly) non è necessario alcun passaggio USB — funziona completamente tramite internet. Su hardware di cassa reale (mini PC) la chiavetta TSE è collegata direttamente al dispositivo, senza alcun bisogno di USB/IP.

1. Sull'host (Linux) avviare il servizio USB/IP e condividere la TSE:

# 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. Nella VM (appliance DiKAS) collegare la TSE:

# 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 riconosce la chiavetta TSE tramite hotplug, la integra e la utilizza da subito per la firma dei giustificativi — non è necessaria alcuna ulteriore impostazione. Nelle impostazioni TSE della cassa la TSE compare come collegata.

3. Per staccarla di nuovo in seguito (sull'host):

sudo usbip unbind -b 1-2

Nel funzionamento continuativo

Per il funzionamento produttivo continuativo, l'hardware di cassa reale (mini PC con chiavetta TSE collegata direttamente) o la TSE cloud sono la scelta più robusta. Il passaggio USB/IP è adatto soprattutto per configurazioni di test e transitorie.

Variante B: configurazione per sviluppatori (`dotnet` + `ng`)¶

Per lo sviluppo API e le personalizzazioni, backend (.NET 10) e frontend (Angular) vengono avviati separatamente.

Prerequisiti:

.NET 10 SDK (dotnet)
Node.js 24 + npm
(facoltativo) CouchDB come database — in alternativa SQLite (vedi sotto)

Avviare il 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: soluzione per la build

Su sistemi basati su Arch, la build può fallire con NU1101 (arch-x64 AppHost). Aggiunga in tal caso -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

Avviare il frontend¶

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

Il server di sviluppo inoltra automaticamente /api, /hubs, /rest e /version al backend sulla porta 5015.

Testare sempre tramite il frontend

Apra l'applicazione tramite http://localhost:4200 (non direttamente tramite il backend sulla porta 5015) — solo così si applica l'inoltro proxy delle chiamate API.

Avviare la cassa demo¶

La cassa demo popola un database vuoto con dati di esempio realistici (articoli, tavoli, personale, fatturato) ed è la via più rapida verso una cassa utilizzabile.

Demo minima con SQLite (un comando)¶

Una demo gastro completa senza alcun bisogno di CouchDB — il backend crea automaticamente un file SQLite (dikas.db) e lo popola:

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

Successivamente avviare il frontend (vedi Variante B) e accedere nel browser.

Senza migrazioni

Lo schema SQLite viene creato e allineato automaticamente all'avvio (SqlDbInitService) — non deve eseguire alcuna migrazione del database.

Modalità demo¶

Il set di dati desiderato si sceglie tramite la variabile d'ambiente DemoSeed__Mode:

`DemoSeed__Mode`	Settore / Contenuto
`basic`	Chiosco / panetteria (vendita diretta)
`gastro` (predefinito)	Ristorante con tavoli
`delivery`	Servizio di consegna
`club`	Discoteca / club
`full`	Dotazione completa — tutti i moduli attivi

Accesso¶

Campo	Valore
Utente	`admin`
Password	`admin`

Il seed viene eseguito solo su database vuoto

I dati demo vengono inseriti solo in un database vuoto. Per rieseguire il seed (ad es. con un'altra modalità) serve un database nuovo:

SQLite: eliminare il file dikas.db nella content root.
CouchDB: impostare un nuovo CouchDb__DatabasePrefix (oppure eliminare i database esistenti).

Successivamente riavviare il backend con il DemoSeed__Mode desiderato.

Sviluppo API locale¶

Dati essenziali¶

	Valore
URL base dell'API	`http://localhost:5015/api/v1/`
Swagger / OpenAPI	`http://localhost:5015/swagger` (solo nelle build di debug)
Health-Check	`GET http://localhost:5015/healthz`
Database predefinito	CouchDB su `http://localhost:5984`
Database alternativo	SQLite — env `Database__Provider=Sqlite` (file `dikas.db` nella content root)

Autenticazione (JWT)¶

L'API utilizza token JWT Bearer. Un token viene richiesto tramite l'endpoint di login ed è valido 480 minuti (8 ore).

1. Richiedere il token:

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

Il token si trova nella risposta sotto data.accessToken. Per riprenderlo in una variabile di shell:

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. Eseguire una chiamata autenticata — passare il token nell'header Authorization:

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

3. Health-Check (senza accesso):

curl http://localhost:5015/healthz

Esplorare gli endpoint

Tutti gli endpoint disponibili con parametri ed esempi di risposta si trovano in modo interattivo su http://localhost:5015/swagger (build di debug). Una panoramica esplicativa è offerta anche dalla pagina REST API.

Token scaduto?

Se il token scade dopo 8 ore, lo stato dell'app nel browser può comportarsi in modo strano. Basta disconnettersi e accedere di nuovo oppure richiedere un nuovo token.

Prossimi passi¶

Installazione e deployment — installazione produttiva tramite ISO
Database — CouchDB vs. SQLite, configurazione
REST API — documentazione API completa
Riferimento API (Swagger) — panoramica interattiva degli endpoint