Requisitos
Qué instala HWD POS, qué sistemas operativos se admiten y qué equipo y red necesita.
HWD POS es un sistema en PHP nativo: no usa framework, ni Composer, ni Node, ni Docker. Eso reduce la instalación a tres piezas obligatorias y algunas opcionales. Los instaladores lo configuran todo; esta página explica para qué sirve cada pieza, para que pueda planificar el servidor y entender el resumen final del instalador.
Piezas obligatorias
| Pieza | Versión | Para qué sirve en HWD POS |
|---|---|---|
| PHP | 8.2 o superior (funciona desde 8.1, pero el asistente exige 8.2) | Es el sistema en sí. Se instalan dos formas del mismo PHP: FPM, que atiende las páginas que abre el navegador, y CLI, que ejecuta los dos servicios de fondo (impresión y complementos) y las tareas de mantenimiento. |
| MariaDB | 10.4 o superior (o MySQL 8) | Guarda todo: productos, existencias, clientes, cotizaciones, facturas, caja, créditos y auditoría. Las actualizaciones del sistema usan ADD COLUMN IF NOT EXISTS, que MySQL 5.x no entiende: por debajo de 10.4 las actualizaciones fallan a medias. |
| Servidor web | Apache 2.4 o Nginx 1.18+ | Recibe las visitas y le pasa a PHP-FPM lo que corresponde al sistema. Su document root debe apuntar a la carpeta public/, nunca a la raíz del proyecto. |
Por qué public/ y no la raíz
Dentro del proyecto están la configuración (con la contraseña de la base), los respaldos y el código. Con el document root en public/, nada de eso es alcanzable desde la red aunque alguien adivine el nombre del archivo. Los instaladores lo configuran así y además bloquean explícitamente los archivos .env, .sql, .md, .sh y .lock.
Extensiones de PHP
Los instaladores las instalan todas. El asistente del navegador las vuelve a comprobar y las muestra con ✓ / ✗ antes de dejar continuar.
| Extensión | ¿Obligatoria? | Qué deja de funcionar sin ella |
|---|---|---|
| pdo_mysql | Sí | Nada funciona: es la conexión con la base de datos. |
| mbstring | Sí | El texto con acentos y con ñ se corta o se corrompe (nombres de clientes y productos, búsquedas). |
| curl | Sí | Todo lo que sale a internet: activación de la licencia, comprobación de actualizaciones, facturación fiscal, Yappy, correo por SMTP y el asistente de ayuda. |
| zip | Recomendada | Instalar y actualizar complementos, aplicar actualizaciones del sistema, importar clientes y productos desde planilla y exportar a Excel. |
| gd | Recomendada | La marca de agua del documento A4 y la firma del cliente en la entrega. |
| xml | Recomendada | Leer las planillas de importación de clientes y productos. |
| opcache | Recomendada | Nada deja de funcionar, pero el sistema va notablemente más lento: cada página se vuelve a compilar en cada visita. |
| sodium | Recomendada | Verifica la firma de la licencia. Si falta, se usa el respaldo incluido: funciona igual, solo más lento. |
| pcntl (solo en CLI) | Recomendada | Sin ella, los dos servicios de fondo no pueden recoger el código nuevo por su cuenta tras una actualización; hay que reiniciarlos a mano. |
Piezas opcionales
| Pieza | Para qué sirve | Si no está |
|---|---|---|
| CUPS | Imprimir en impresoras A4 (inyección o láser) y en impresoras de red por IPP/AirPrint. | Las impresoras térmicas (ESC/POS, 80 mm y 58 mm) siguen funcionando: no pasan por CUPS. |
| Google Chrome (o Chromium) | Convertir a PDF el documento A4 completo (la factura y la cotización con su diseño). En Ubuntu/Debian (amd64) el instalador pone Google Chrome desde su paquete oficial, porque el chromium-browser de Ubuntu es solo un paso hacia Snap y, sin snapd, no funciona aunque el comando exista. | La impresión tipo «recibo» sigue funcionando; el documento A4 con diseño no se puede generar. |
| Typesense | Buscador tolerante a errores de escritura en todas las búsquedas. Vea Búsqueda con Typesense. | Se usa la búsqueda por SQL de siempre. No hace falta configurarlo. |
Con WITH_PRINTING=no el instalador omite CUPS y Chrome/Chromium. Es lo indicado en un servidor que no imprime, por ejemplo uno que solo aloja la base de datos.
Servicios de fondo
El instalador deja dos servicios en funcionamiento:
| Servicio | Qué hace | Cómo comprobarlo |
|---|---|---|
hwpos-print | Imprime, uno por uno, los documentos que el sistema pone en cola. | systemctl status hwpos-print |
hwpos-plugins | Ejecuta el trabajo en segundo plano de los complementos (por ejemplo, enviar el correo al cliente desde el servidor, sin que el vendedor espere). | systemctl status hwpos-plugins |
Los dos deben quedar activos y habilitados (arranque automático). El resumen final del instalador los verifica.
Sistemas operativos admitidos
Hay un instalador por familia de sistema, con las mismas preguntas, los mismos modos y el mismo resumen final.
| Sistema | Versiones | Instalador |
|---|---|---|
| Ubuntu Server (recomendado) | 24.04 LTS (recomendada), 22.04 LTS | install-ubuntu.sh |
| Debian | 12 | install-ubuntu.sh |
| AlmaLinux | 9 (recomendada), 8 | install-almalinux.sh |
| Rocky Linux / RHEL / CentOS Stream | 9, 8 | install-almalinux.sh |
Todos los sistemas de la tabla sirven y quedan igual de funcionales al terminar.
Aun así, recomendamos Ubuntu Server 24.04 LTS, porque es el sistema sobre el que principalmente se configura y se prueba HWD POS. Trae PHP 8.3 en sus repositorios oficiales, necesita menos pasos manuales y, si algo sale mal, se diagnostica más rápido. La regla práctica: si todavía puede elegir el sistema del servidor, elija Ubuntu. Si el servidor ya existe y usa AlmaLinux, Rocky, RHEL o CentOS, instale ahí sin problema: está admitido y tiene su propio instalador. Lea antes las notas para AlmaLinux.
No admitidos: Windows Server (el sistema usa servicios de systemd, rutas de impresión de Linux y pcntl) y cualquier Linux con PHP anterior a 8.1.
Equipo
| Mínimo | Recomendado (tienda con 3–8 terminales) | |
|---|---|---|
| Procesador | 2 núcleos | 4 núcleos |
| Memoria | 2 GB | 4 GB o más |
| Disco | 20 GB | 40 GB SSD |
| Sistema | 64 bits | 64 bits |
La memoria determina cuántas ventas simultáneas aguanta el servidor. El instalador calcula el número de procesos de PHP a razón de unos 60 MB por proceso, con un mínimo de 10 y un máximo de 80, y siempre lo deja por debajo del límite de conexiones de la base de datos (300). Con 2 GB salen unos 33 procesos; con 4 GB, unos 68. Ese número se puede consultar y ajustar después en Sistema → Capacidad de conexiones y con hwdpanel (opción 19).
El disco crece sobre todo por tres cosas: los respaldos de la base, las fotos de productos y las fotos y firmas de entrega. 40 GB dan holgura para años en una ferretería normal.
Máquinas virtuales (Proxmox y similares)
- VM (KVM) o contenedor LXC: un LXC pesa menos, pero pasar una impresora USB a un LXC exige un contenedor privilegiado y un bind mount de
/dev/usb/lp0. En una VM se usa el paso de USB (en Proxmox: Hardware → Add → USB Device). - Lo más simple: impresoras de red (IP). Evitan por completo el paso de USB: el servicio de impresión imprime por el socket 9100 (térmica) o por una cola IPP/AirPrint (A4). Recomendado en entornos virtualizados.
- Recursos típicos para una tienda: 2 vCPU, 2–4 GB de RAM, 20 GB de disco.
- Dé a la VM o al contenedor una IP fija en la LAN para que las terminales y tablets se conecten.
Red
| Requisito | Detalle |
|---|---|
| IP fija en la red local | Las terminales, tablets e impresoras apuntan al servidor por su IP. Si cambia, hay que reconfigurarlas. Fíjela en el servidor o resérvela en el router. |
| Salida a internet | Necesaria para activar la licencia, buscar actualizaciones y enviar correo. No hace falta que el servidor sea accesible desde internet. |
| Puerto del sitio abierto en la red local | 80 por omisión. Vea Instalación por red. |
| Puerto 3306 | Solo si la base de datos está en otro servidor. Ábralo únicamente hacia la IP del servidor web. |
No es obligatorio publicar el servidor en internet: todo funciona en la red local. Publicarlo solo hace falta si quiere entrar desde fuera de la tienda, y en ese caso conviene agregar HTTPS (por ejemplo, con Let's Encrypt). Los instaladores no configuran HTTPS.
Antes de instalar
- Un servidor limpio con uno de los sistemas admitidos.
- Acceso como
rooto consudo. - Conexión a internet desde el servidor (pruebe con
ping -c2 3r.com.pa). - La clave de activación y el código de cliente que le entregó el proveedor.
Después continúe con la instalación por red.