Pruebas locales e instalación¶

Esta página muestra cómo puede probar DiKAS usted mismo, instalarlo localmente y utilizarlo para el desarrollo. Está dirigida a integradores, administradores y desarrolladores.

Existen dos formas de operar DiKAS de forma local:

Variante	Adecuada para	Esfuerzo
A — Appliance ISO en una VM	Funcionamiento de prueba realista, como en hardware de caja real	Bajo
B — Configuración de desarrollador (`dotnet` + `ng`)	Desarrollo de API, adaptaciones, depuración	Mayor

¿Solo quiere echar un vistazo rápido a la caja?

Si solo desea probar DiKAS sin compromiso, la variante A (ISO en una VM) es el camino más rápido hacia una caja completa. Para una demo puramente de API/frontend sin VM, más abajo encontrará la caja de demostración (SQLite + datos de demostración, un único comando).

Requisitos del sistema¶

Servidor / VM¶

Variante	Mínimo	Recomendado
Negocio pequeño (1–2 cajas)	2 GB de RAM, 2 núcleos	4 GB de RAM, 4 núcleos
Negocio mediano (3–5 cajas)	4 GB de RAM, 4 núcleos	8 GB de RAM, 4 núcleos
Negocio grande (5+ cajas)	8 GB de RAM, 4 núcleos	16 GB de RAM, 8 núcleos

Disco duro / disco virtual¶

Uso	Mínimo	Recomendado
Appliance ISO en la VM	20 GB (sistema operativo + base de datos + datos de demostración)	40 GB
Configuración de desarrollador	según el SDK/herramientas, aprox. 10–15 GB	20 GB

Regla general para la VM ISO

Para probar la appliance ISO bastan 2 GB de RAM (1–2 cajas) y 20 GB de disco. Para varias cajas simultáneas o un funcionamiento de prueba más prolongado, se recomiendan 4 GB de RAM o más — oriéntese por la tabla anterior.

Variante A: appliance ISO en una VM¶

La appliance DiKAS es una imagen de sistema operativo lista y arrancable, basada en Arch Linux (archiso). Ya incluye la aplicación DikasArch (.NET 10) y la base de datos — ideal para probar DiKAS en condiciones realistas sin tener que instalar un sistema operativo.

Descargar la ISO¶

La imagen ISO actual (aprox. 500 MB–1 GB, arranca tanto por UEFI como por BIOS) se encuentra en:

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

¿De qué se compone la appliance?

La imagen se construye en el repositorio dikasiso (sh make.sh). La aplicación de caja propiamente dicha es dikasarch (paquete Arch dikasarch10-*.pkg.tar.zst, .NET 10). Para el funcionamiento de prueba no necesita construir nada de esto usted mismo — simplemente descargue la ISO ya lista.

A.1 — Hyper-V (Windows)¶

Hyper-V está incluido en Windows 10/11 Pro y Windows Server (active la característica «Hyper-V»).

Paso a paso (Administrador de Hyper-V, gráfico):

Abrir el Administrador de Hyper-V → a la derecha Nuevo → Equipo virtual.
Elegir Generación 1 (arranque BIOS, sin problemas con archiso). La Generación 2 (UEFI) también funciona — entonces hay que desactivar el Arranque seguro (la ISO no está firmada con la clave de Arranque seguro de Microsoft).
Memoria: 2048 MB (o más, véase Requisitos del sistema). Puede dejar activada la «Memoria dinámica».
Disco duro virtual: crear un nuevo VHDX de 20 GB.
Opciones de instalación: «Instalar desde CD/DVD-ROM de arranque» → Archivo de imagen (.iso) → seleccionar dikas.iso.
Iniciar la VM y conectarse a ella.

Alternativamente mediante PowerShell (como administrador):

# Generación 1 (BIOS) - la vía más sencilla
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"

Generación 2 + Arranque seguro

Si utiliza una VM de Generación 2, el Arranque seguro debe estar desactivado; de lo contrario, la ISO no arranca:

Set-VMFirmware -VMName "DiKAS" -EnableSecureBoot Off

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

VirtualBox es gratuito y funciona en todos los sistemas operativos principales.

Paso a paso (gráfico):

Nueva → Nombre DiKAS, Tipo Linux, Versión Arch Linux (64 bits).
Memoria: 2048 MB o más.
Disco duro: «Crear un disco duro virtual ahora» → VDI → dinámico → 20 GB.
Seleccionar la VM → Configuración → Almacenamiento → introducir la ISO dikas.iso en la unidad óptica.
(Opcional) Sistema → Placa base → activar EFI, si desea probar UEFI — la ISO también arranca en el modo BIOS estándar.
Iniciar la VM.

Alternativamente por línea de comandos (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)¶

En un host Linux (Debian/Ubuntu/Arch), la forma más sencilla de arrancar la ISO es con KVM/QEMU, opcionalmente de forma cómoda a través de virt-manager.

Instalar la virtualización:

# 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

Crear la VM y arrancar la ISO (virt-install):

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

O directamente con QEMU (sin 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

Probar UEFI (OVMF)

Si la VM debe arrancar por UEFI, añada --boot uefi en virt-install o un firmware OVMF en QEMU (-bios /usr/share/OVMF/OVMF_CODE.fd). La ISO admite ambos modos de arranque.

Primer arranque de la appliance¶

Tras arrancar, la appliance instala/inicia DiKAS en el sistema virtual. A continuación, la caja es accesible desde el navegador.

TODO — Detalles del primer arranque de la appliance

La dirección/puerto local exacta de la appliance tras el arranque, el proceso de instalación en el disco virtual y el primer inicio de sesión no estaban verificados en el momento de esta documentación y se marcan aquí como marcador de posición. Complételo con la documentación de la appliance/de dikasiso (p. ej. «caja accesible en http://<IP-VM>:<puerto>, inicio de sesión con …»).

TSE en la VM (USB/IP)¶

Si DiKAS se ejecuta en una VM y desea utilizar una TSE de hardware (llave USB Swissbit), la llave se pasa desde el host (el equipo en el que está conectada) a la VM mediante USB/IP. DiKAS en la VM reconoce y monta la TSE automáticamente a continuación.

¿Cuándo lo necesito?

Solo en el caso de una TSE de hardware (Swissbit) en una VM. Con una Cloud-TSE (fiskaly) no hace falta ningún reenvío USB — esta funciona completamente a través de Internet. En hardware de caja real (mini-PC), la llave TSE se conecta directamente al dispositivo, sin USB/IP.

1. En el host (Linux), iniciar el servicio USB/IP y liberar la TSE:

# instalar las herramientas usbip (ejemplo Debian/Ubuntu)
sudo apt install usbip

# iniciar el servidor USB/IP
sudo usbipd -D

# listar los dispositivos USB conectados y encontrar la TSE Swissbit (VID:PID 1370:0505)
usbip list -l

# liberar la TSE mediante su ID de bus (p. ej. 1-2)
sudo usbip bind -b 1-2

2. En la VM (appliance DiKAS), conectar la TSE:

# dirección del host = puerta de enlace de la VM (con NAT habitualmente 10.0.2.2,
# si no, la IP del host en la red)
sudo usbip attach -r 10.0.2.2 -b 1-2

DiKAS reconoce la llave TSE mediante hotplug, la vincula y la utiliza a partir de ese momento para la firma de comprobantes — no hace falta ningún otro ajuste. En la configuración de TSE de la caja, la TSE aparece como conectada.

3. Desvincularla más tarde (en el host):

sudo usbip unbind -b 1-2

En funcionamiento continuo

Para el funcionamiento productivo continuo, la opción más robusta es el hardware de caja real (mini-PC con la llave TSE conectada directamente) o la Cloud-TSE. El reenvío por USB/IP es adecuado sobre todo para configuraciones de prueba y transición.

Variante B: configuración de desarrollador (`dotnet` + `ng`)¶

Para el desarrollo de la API y las adaptaciones, el backend (.NET 10) y el frontend (Angular) se inician por separado.

Requisitos previos:

SDK de .NET 10 (dotnet)
Node.js 24 + npm
(opcional) CouchDB como base de datos — alternativamente SQLite (véase más abajo)

Iniciar el 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: solución alternativa para el build

En sistemas basados en Arch, el build puede fallar con NU1101 (AppHost arch-x64). En ese caso, añada -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

Iniciar el frontend¶

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

El servidor de desarrollo reenvía automáticamente /api, /hubs, /rest y /version al backend en el puerto 5015.

Pruebe siempre a través del frontend

Abra la aplicación en http://localhost:4200 (no directamente en el backend en el puerto 5015) — solo así funciona el reenvío proxy de las llamadas a la API.

Iniciar la caja de demostración¶

La caja de demostración rellena una base de datos vacía con datos de ejemplo realistas (artículos, mesas, personal, ventas) y es la vía más rápida hacia una caja operativa.

Demo mínima con SQLite (un solo comando)¶

Una demo completa de hostelería sin necesidad de CouchDB — el backend crea automáticamente un archivo SQLite (dikas.db) y lo puebla:

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

A continuación, inicie el frontend (véase la variante B) e inicie sesión en el navegador.

Sin migraciones

El esquema de SQLite se genera y concilia automáticamente al iniciar (SqlDbInitService) — no tiene que ejecutar ninguna migración de base de datos.

Modos de demostración¶

El conjunto de datos deseado se elige mediante la variable de entorno DemoSeed__Mode:

`DemoSeed__Mode`	Sector / contenido
`basic`	Quiosco / panadería (venta directa)
`gastro` (predeterminado)	Restaurante con mesas
`delivery`	Servicio de entrega
`club`	Discoteca / club
`full`	Equipamiento completo — todos los módulos activos

Inicio de sesión¶

Campo	Valor
Usuario	`admin`
Contraseña	`admin`

El seed solo se ejecuta con la base de datos vacía

Los datos de demostración solo se cargan en una base de datos vacía. Para volver a poblarla (p. ej. con otro modo), necesita una base de datos nueva:

SQLite: eliminar el archivo dikas.db en el directorio raíz del contenido.
CouchDB: establecer un nuevo CouchDb__DatabasePrefix (o eliminar las bases de datos existentes).

A continuación, reinicie el backend con el DemoSeed__Mode deseado.

Desarrollo local de la API¶

Datos clave¶

	Valor
URL base de la API	`http://localhost:5015/api/v1/`
Swagger / OpenAPI	`http://localhost:5015/swagger` (solo en compilaciones Debug)
Comprobación de estado	`GET http://localhost:5015/healthz`
Base de datos predeterminada	CouchDB en `http://localhost:5984`
Base de datos alternativa	SQLite — variable de entorno `Database__Provider=Sqlite` (archivo `dikas.db` en el directorio raíz del contenido)

Autenticación (JWT)¶

La API utiliza un token JWT Bearer. El token se solicita a través del endpoint de inicio de sesión y es válido durante 480 minutos (8 horas).

1. Solicitar el token:

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

El token se encuentra en la respuesta bajo data.accessToken. Guardarlo en una variable de 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. Realizar una llamada autenticada — incluir el token en la cabecera Authorization:

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

3. Comprobación de estado (sin inicio de sesión):

curl http://localhost:5015/healthz

Explorar los endpoints

Todos los endpoints disponibles, con sus parámetros y ejemplos de respuesta, se encuentran de forma interactiva en http://localhost:5015/swagger (compilación Debug). La página API REST ofrece además una descripción general explicativa.

¿Token caducado?

Si el token caduca tras 8 horas, el estado de la aplicación en el navegador puede comportarse de forma extraña. Simplemente cierre sesión y vuelva a iniciarla, o solicite un token nuevo.

Próximos pasos¶

Instalación y despliegue — instalación productiva mediante ISO
Base de datos — CouchDB frente a SQLite, configuración
API REST — documentación completa de la API
Referencia de la API (Swagger) — descripción general interactiva de los endpoints