VIVAitwiki - Contribuciones del usuario [es]

Instalacion cartelia 10

2026-07-13T10:26:50Z

Alfredo.rodriguez: /* Configuración desde el portal de administración de Cartelia */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>).
<br>
Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* <code>''Administración > Configuración > Red''</code>: establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* <code>''Administración > Configuración''</code>, pestaña <code>'''Configuración'''</code>, campo <code>'''"Clave secreta de CMS"'''</code>: es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* <code>''Administración > Configuración''</code>, pestaña <code>'''Configuración'''</code>, campo <code>'''"Ubicación de la biblioteca"'''</code>: verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* <code>''Administración > Configuración''</code>, pestaña <code>'''Red'''</code> (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
'''⚠️ ATENCION !!'''
'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>).<br> Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.
</div>

Instalacion cartelia 10

2026-07-13T10:25:10Z

Alfredo.rodriguez: /* Configuración desde el portal de administración de Cartelia */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>).
<br>
Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* <code>''Administración > Configuración > Red''</code>: establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
'''⚠️ ATENCION !!'''
'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>).<br> Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.
</div>

Instalacion cartelia 10

2026-07-13T10:19:14Z

Alfredo.rodriguez: /* Ficheros de configuración del producto */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>).
<br>
Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
'''⚠️ ATENCION !!'''
'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>).<br> Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.
</div>

Instalacion cartelia 10

2026-07-13T10:18:59Z

Alfredo.rodriguez: /* Ficheros de configuración del producto */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>).
Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
'''⚠️ ATENCION !!'''
'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>).<br> Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.
</div>

Instalacion cartelia 10

2026-07-13T10:05:49Z

Alfredo.rodriguez: /* Firewall (/etc/firewall/) */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
'''⚠️ ATENCION !!'''
'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>).<br> Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.
</div>

Instalacion cartelia 10

2026-07-13T10:05:28Z

Alfredo.rodriguez: /* Firewall (/etc/firewall/) */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
'''⚠️ ATENCION !!'''
'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.
</div>

Instalacion cartelia 10

2026-07-13T10:04:25Z

Alfredo.rodriguez: /* Diagnósticos */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

Operacion cartelia

2026-07-13T10:03:12Z

Alfredo.rodriguez:

= Instalación =
[[Instalacion_cartelia | Instalacion de cartelia]]

= Diagnósticos =

== Comandos de diagnóstico ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</pre>

== Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}
<br>

= Procedimientos básicos =

== Modificar textos idioma ==

'''Herramientas necesarias''':

* poedit (https://poedit.com/); nos permitirá:
** Descompilar fichero ".mo" (el que entiende cartelia) existente a ".po" para modificar textos de idioma
*** Se hace con la herramienta <code>C:\Program Files\Poedit\GettextTools\bin\msgunfmt.exe</code>
*** Ejemplo invocación: <code>msgunfmt.exe "C:\cartelia\locale\es.mo" -o "C:\cartelia\locale\es.po" </code> (las carpetas cambiarán en cada caso)
* Ver las traducciones para un fichero ".po"
* Modificar y "compilar" a fichero ".mo"
'''La herramienta poedit es de uso sencillo y no requiere de instrucciones específicas para personal técnico de mdtel'''

<br>

'''Instrucciones para cambiar mensajes'''
:ejemplo para idioma español
:entre paréntesis perfil que puede realizar la tarea con seguridad
#.- (SAT) Obtener el fichero ".mo" original de /var/www/html/cartelia/locale/es.mo; este es un fichero "compilado"
#.- (PU) Descompilar el fichero con la herramienta msgunfmt
#.- (PU) Modificar mensajes con "poedit" y compilar
#.- (SAT) Subir el fichero modificado a /var/www/html/cartelia/locale/es.mo

[[Category:tecnico]]
[[Category:administrador]]
[[Category:Cartelia]]

Operacion cartelia

2026-07-13T10:02:45Z

Alfredo.rodriguez: /* Instalación */

= Instalación =
[[Instalacion_cartelia | Instalacion de cartelia]]

= Diagnósticos =

== Comandos de diagnóstico ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</pre>

== Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}
<br>

== Procedimientos básicos ==

=== Modificar textos idioma ===

'''Herramientas necesarias''':

* poedit (https://poedit.com/); nos permitirá:
** Descompilar fichero ".mo" (el que entiende cartelia) existente a ".po" para modificar textos de idioma
*** Se hace con la herramienta <code>C:\Program Files\Poedit\GettextTools\bin\msgunfmt.exe</code>
*** Ejemplo invocación: <code>msgunfmt.exe "C:\cartelia\locale\es.mo" -o "C:\cartelia\locale\es.po" </code> (las carpetas cambiarán en cada caso)
* Ver las traducciones para un fichero ".po"
* Modificar y "compilar" a fichero ".mo"
'''La herramienta poedit es de uso sencillo y no requiere de instrucciones específicas para personal técnico de mdtel'''

<br>

'''Instrucciones para cambiar mensajes'''
:ejemplo para idioma español
:entre paréntesis perfil que puede realizar la tarea con seguridad
#.- (SAT) Obtener el fichero ".mo" original de /var/www/html/cartelia/locale/es.mo; este es un fichero "compilado"
#.- (PU) Descompilar el fichero con la herramienta msgunfmt
#.- (PU) Modificar mensajes con "poedit" y compilar
#.- (SAT) Subir el fichero modificado a /var/www/html/cartelia/locale/es.mo

[[Category:tecnico]]
[[Category:administrador]]
[[Category:Cartelia]]

Instalacion cartelia 10

2026-07-13T09:36:18Z

Alfredo.rodriguez:

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= Diagnósticos =

== Comandos de diagnóstico ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</pre>

== Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:35:42Z

Alfredo.rodriguez: /* Comandos de diagnóstico */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= Diagnósticos =

== Comandos de diagnóstico ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</pre>

== Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:35:24Z

Alfredo.rodriguez: /* Firewall (/etc/firewall/) */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</pre>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= Diagnósticos =

== Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:34:43Z

Alfredo.rodriguez: /* 5. Diagnósticos */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= Diagnósticos =

== Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:34:22Z

Alfredo.rodriguez: /* 3. Personalización del sistema operativo (dentro de la VM) */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:34:04Z

Alfredo.rodriguez: /* 2. Arquitectura */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== 3.3 Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:33:47Z

Alfredo.rodriguez: /* 1. Introducción */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== 3.3 Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:33:36Z

Alfredo.rodriguez: /* 4. Configuración */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= 1. Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== 3.3 Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:32:49Z

Alfredo.rodriguez: /* 3.3 Verificación de la instalación */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= 1. Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== 3.3 Verificación de la instalación ==

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</pre>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= 4. Configuración =

== 4.1 Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== 4.2 Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== 4.3 Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== 4.4 Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:32:28Z

Alfredo.rodriguez: /* 3.2 Arranque del producto Cartelia */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= 1. Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</pre>

== 3.3 Verificación de la instalación ==

<syntaxhighlight lang="bash">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</syntaxhighlight>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= 4. Configuración =

== 4.1 Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== 4.2 Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== 4.3 Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== 4.4 Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia 10

2026-07-13T09:31:59Z

Alfredo.rodriguez: /* 3.1 Personalización de identidad y red */

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= 1. Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</pre>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<syntaxhighlight lang="bash">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</syntaxhighlight>

== 3.3 Verificación de la instalación ==

<syntaxhighlight lang="bash">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</syntaxhighlight>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= 4. Configuración =

== 4.1 Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== 4.2 Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== 4.3 Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== 4.4 Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Archivo:Cartelia-arquitectura.png

2026-07-13T09:29:13Z

Alfredo.rodriguez:

Instalacion cartelia 10

2026-07-13T09:28:20Z

Alfredo.rodriguez: Página creada con «Instalación de Cartelia 1.0 --- = 1. Introducción = '''Cartelia''' es el producto de cartelería digital (di…»

[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
---

= 1. Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<syntaxhighlight lang="bash">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</syntaxhighlight>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<syntaxhighlight lang="bash">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</syntaxhighlight>

== 3.3 Verificación de la instalación ==

<syntaxhighlight lang="bash">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</syntaxhighlight>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= 4. Configuración =

== 4.1 Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== 4.2 Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== 4.3 Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== 4.4 Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia

2026-07-13T09:27:55Z

Alfredo.rodriguez:

[[Instalacion_cartelia_10 | Manual de instalación de cartelia 1.0]]
<br>

Instalacion cartelia

2026-07-13T09:25:11Z

Alfredo.rodriguez: Página reemplazada por «== Manual de instalación de cartelia 1.0 == Instalación de Cartelia 1.0 <br>»

== Manual de instalación de cartelia 1.0 ==
[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>

Instalacion cartelia

2026-07-13T09:24:46Z

Alfredo.rodriguez:

== Manual de instalación de cartelia 1.0 ==
[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>

---

{{DISPLAYTITLE:Cartelia — Despliegue de máquina virtual base (Debian 13 / KVM-QEMU)}}

= Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= Arquitectura =

== Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= Personalización del sistema operativo (dentro de la VM) =

== Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<syntaxhighlight lang="bash">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</syntaxhighlight>

== Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<syntaxhighlight lang="bash">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</syntaxhighlight>

== Verificación de la instalación ==

<syntaxhighlight lang="bash">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</syntaxhighlight>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= Configuración =

== Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= Diagnósticos =

== Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia

2026-07-13T09:23:16Z

Alfredo.rodriguez:

== Manual de instalación de cartelia 1.0 ==
[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>

---

{{DISPLAYTITLE:Cartelia — Despliegue de máquina virtual base (Debian 13 / KVM-QEMU)}}

= 1. Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<syntaxhighlight lang="bash">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</syntaxhighlight>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<syntaxhighlight lang="bash">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</syntaxhighlight>

== 3.3 Verificación de la instalación ==

<syntaxhighlight lang="bash">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</syntaxhighlight>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= 4. Configuración =

== 4.1 Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== 4.2 Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== 4.3 Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== 4.4 Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Instalacion cartelia

2026-07-13T09:22:42Z

Alfredo.rodriguez: /* Manual de instalación de cartelia 1.0 */

== Manual de instalación de cartelia 1.0 ==
[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>

---

{{DISPLAYTITLE:Cartelia — Despliegue de máquina virtual base (Debian 13 / KVM-QEMU)}}

'''Documentación técnica de proceso'''<br/>
Versión del documento: 1.0 · Producto: Cartelia 1.0<br/>
Fecha: 09/07/2026 · Responsable: Iván Matarrubias

__TOC__

= 1. Introducción =

'''Cartelia''' es el producto de cartelería digital (digital signage) de la compañía.

El presente documento describe el procedimiento de despliegue de una nueva instancia de Cartelia partiendo de una '''máquina virtual base''' con las siguientes características:

* Sistema operativo: '''Debian 13 (trixie)'''.
* Hipervisor: '''KVM/QEMU''' (gestionado mediante <code>libvirt</code>/<code>virsh</code> o <code>virt-manager</code>).
* Software preinstalado: '''Cartelia 1.0''', instalado en <code>/var/www/html/cartelia</code>.

'''Punto de partida''': la máquina base se entrega totalmente operativa, con Cartelia instalado de forma nativa sobre Apache + PHP y la base de datos MariaDB local ya creada e inicializada.

'''Restricciones conocidas''':

* La plantilla base '''no debe arrancarse nunca en producción sin personalizar''': contiene identidad de máquina, claves SSH y secretos del CMS compartidos con cualquier otra copia de la plantilla.
* Los players (pantallas) se autentican contra el CMS mediante la clave del servidor (''CMS Key'') y la URL del CMS; cualquier cambio posterior de IP/FQDN o de claves obliga a volver a autorizar los displays.

= 2. Arquitectura =

== 2.1 Esquema general del despliegue ==

[[File:Cartelia-arquitectura.png|thumb|center|900px|Esquema general del despliegue de Cartelia sobre KVM/QEMU]]

El CMS está instalado de forma nativa sobre el sistema operativo: Apache 2 con PHP como servidor web del portal, MariaDB local como base de datos y el servicio XMR ejecutándose como unidad de systemd.

== 2.2 Flujo del proceso de despliegue ==

# El técnico de sistemas clona la plantilla base en el host KVM/QEMU (disco <code>qcow2</code> + definición de dominio libvirt).
# En el primer arranque del clon, se personaliza la identidad del sistema operativo: <code>machine-id</code>, hostname, claves SSH de host, red, zona horaria y credenciales locales.
# Se personaliza el producto Cartelia: URL pública del CMS, secretos y contraseñas de base de datos, clave del servidor (''CMS Key''), dirección pública de XMR y personalización de marca.
# Se verifican los servicios, la conectividad de los players y el acceso al portal de administración.
# La máquina queda registrada en inventario/monitorización y se entrega.

== 2.3 Componentes principales ==

{| class="wikitable"
! Componente !! Función
|-
| '''Portal Cartelia''' || Interfaz de administración de contenidos, layouts, programaciones y pantallas. Servida por Apache 2 + PHP.
|-
| '''MariaDB (local)''' || Almacena la configuración, usuarios, programaciones y metadatos de medios del CMS. Servicio nativo del sistema.
|-
| '''XMR (Cartelia Message Relay)''' || Canal push que permite al CMS enviar órdenes inmediatas a los players (recarga de contenido, capturas, reinicio). Servicio <code>xibo-xmr.service</code>. Los players se conectan por WebSocket a la ruta <code>/xmr</code> del vhost de Apache, que reenvía a <code>ws://127.0.0.1:8080</code>; el puerto 9505/TCP queda además permitido en el firewall para el modo de publicación directa.
|-
| '''Biblioteca de medios''' || <code>/var/lib/cartelia/library/</code>: directorio donde el CMS guarda los ficheros multimedia subidos (configurado en ''Administración > Configuración > Ubicación de la biblioteca'' y alineado con la directiva <code>XSendFilePath</code> de los vhosts).
|-
| '''libvirt / KVM-QEMU''' || Capa de virtualización que aloja la VM.
|}

== 2.4 Dependencias e integraciones externas ==

* '''DNS''': registro A/AAAA del FQDN del CMS (imprescindible si los players usan nombre en lugar de IP).
* '''NTP''': sincronización horaria; las programaciones de contenido dependen de la hora del sistema.
* '''SMTP''' (opcional): relay de correo para notificaciones del CMS, si el cliente lo requiere. Se configura en el portal (''Administración > Configuración'', pestaña '''Mantenimiento''').
* '''Certificados TLS''': siempre certificados válidos, nunca autofirmados. Si el cliente dispone de certificado propio para el FQDN, lo aporta él; en caso contrario se emite con Let's Encrypt.

= 3. Personalización del sistema operativo (dentro de la VM) =

== 3.1 Personalización de identidad y red ==

Todos los comandos se ejecutan como <code>root</code> desde la consola de <code>virsh</code> en el primer arranque.

<syntaxhighlight lang="bash">
# Paso 1: regenerar las claves SSH de host (las de la plantilla son comunes a todos los clones)
rm -f /etc/ssh/ssh_host_*
dpkg-reconfigure openssh-server
systemctl restart ssh

# Paso 2: hostname y resolución local
hostnamectl set-hostname <nombre-del-entorno>
sed -i "s/127.0.1.1.*/127.0.1.1\t<nombre-del-entorno> <FQDN-del-CMS>/" /etc/hosts

# Paso 3: configuración de red (ifupdown, /etc/network/interfaces)

# Paso 4: zona horaria y hora (NTP)
vi /etc/systemd/timesyncd.conf.d/local.conf

# Paso 5: actualización de paquetes del SO
apt update && apt upgrade -y
</syntaxhighlight>

== 3.2 Arranque del producto Cartelia ==

El CMS ya viene instalado y operativo en la máquina base; en esta fase únicamente debe verificarse el arranque de los servicios nativos tras la personalización de red:

<syntaxhighlight lang="bash">
systemctl status apache2 mariadb
systemctl status xibo-xmr.service

# Si algún servicio no arranca tras el cambio de red/hostname:
systemctl restart apache2
journalctl -u apache2 -n 50 --no-pager
</syntaxhighlight>

== 3.3 Verificación de la instalación ==

<syntaxhighlight lang="bash">
# El portal responde en local (la máquina base publica en HTTP; ver 4.3 para HTTPS)
curl -Is http://localhost/ | head -1 # esperado: HTTP/1.1 200 OK (o 302 a /login)

# Puertos de servicio a la escucha
ss -tlnp | grep -E ':(80|9505)\b'

# Resolución del FQDN desde un puesto cliente
getent hosts <FQDN-del-CMS>
</syntaxhighlight>

Acceso final: abrir <code>http://<FQDN-del-CMS>/</code> en el navegador y validar la pantalla de login de Cartelia (o <code>https://</code> si se ha habilitado el vhost TLS, ver 4.3).

= 4. Configuración =

== 4.1 Ficheros de configuración del producto ==

La instalación es nativa (Apache + PHP + MariaDB local); estos son los ficheros que el SAT debe revisar/personalizar en cada clon:

'''<code>settings.php</code> del CMS''' (<code>/var/www/html/cartelia/web/settings.php</code>):

{| class="wikitable"
! Parámetro !! Descripción !! Acción en el despliegue
|-
| <code>$dbhost</code> || Host de MariaDB (normalmente <code>localhost</code>) || No cambiar
|-
| <code>$dbname</code>, <code>$dbuser</code> || Base de datos y usuario del CMS || No cambiar salvo política del cliente
|-
| <code>$dbpass</code> || Contraseña del usuario del CMS en MariaDB || No cambiar
|-
| <code>SECRET_KEY</code> || Clave secreta de la instalación (cifrado interno) || Actualmente no se regenera: se mantiene el valor de la máquina base en todos los despliegues
|}

'''XMR''' (<code>xibo-xmr.service</code>, unidad en <code>/etc/systemd/system/xibo-xmr.service</code>): ejecuta <code>/var/www/html/cartelia/vendor/bin/xmr.phar</code> con PHP como usuario <code>www-data</code>, con reinicio automático (<code>Restart=always</code>). Sockets por defecto: WebSocket para players en <code>127.0.0.1:8080</code>, expuesto a través del proxy <code>/xmr</code> del vhost de Apache, y publicación interna del CMS en <code>tcp://127.0.0.1:50001</code>.

Tras cualquier cambio: <code>systemctl restart xibo-xmr.service</code>.

'''Apache''': la máquina base incluye dos vhosts en <code>/etc/apache2/sites-available/</code>:

* <code>cartelia_http.conf</code> (habilitado por defecto): sirve el portal en el puerto 80. En la máquina base el <code>ServerName</code> es la IP de la propia máquina; en cada cliente debe actualizarse al FQDN definitivo. Incluye el proxy WebSocket de XMR (<code>ProxyPass /xmr ws://127.0.0.1:8080</code>), <code>XSendFile</code> para la entrega de medios y una exclusión de mod_security (<code>SecRuleRemoveById 920350</code>).
* <code>cartelia_https.conf</code> (deshabilitado por defecto): vhost TLS preparado para clientes con FQDN y certificado. Su activación se describe en la sección 4.3.

Validar siempre con <code>apache2ctl configtest</code> antes de <code>systemctl reload apache2</code>.

== 4.2 Configuración desde el portal de administración de Cartelia ==

Acceder con el usuario '''<code>admin</code>''' y la contraseña estándar de la máquina base (conocida por el SAT; no se documenta aquí) y cambiar dicha contraseña de inmediato, ya que es común a todos los clones. A continuación:

* ''Administración > Configuración > Red'': establecer la dirección del CMS (<code>CMS Address</code>) con el FQDN definitivo. Los players usan este valor para conectarse.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Clave secreta de CMS"''': es la clave que debe introducirse en cada player para autenticarlo contra el CMS. En un clon es idéntica a la de la máquina base (y, por tanto, conocida por cualquier otro despliegue), así que debe sustituirse por una clave nueva y única en cada cliente.
* ''Administración > Configuración'', pestaña '''Configuración''', campo '''"Ubicación de la biblioteca"''': verificar que mantiene el valor <code>/var/lib/cartelia/library/</code>; no cambiarlo, ya que debe coincidir con la directiva <code>XSendFilePath</code> de los vhosts de Apache.
* ''Administración > Configuración'', pestaña '''Red''' (sección XMR): establecer la dirección pública de XMR como <code>ws://<FQDN-del-CMS>/xmr</code> (o <code>wss://<FQDN-del-CMS>/xmr</code> si está activo el vhost HTTPS). Los players se conectan por WebSocket a través del proxy de Apache; el puerto 9505 permanece abierto en el firewall únicamente como vía alternativa de publicación directa.

Los cambios de claves y direcciones obligan a volver a autorizar los displays que estuvieran dados de alta en la máquina base (en un despliegue nuevo no debería haber ninguno; si los hubiera, eliminarlos).

== 4.3 Configuración a nivel de sistema operativo ==

{| class="wikitable"
! Elemento !! Fichero / mecanismo !! Acción
|-
| Firewall || <code>firewall.service</code> → ejecuta <code>/etc/firewall/firewall.sh</code>, parametrizado por <code>/etc/firewall/vars.sh</code> || Editar <code>vars.sh</code> en cada despliegue (ver 4.4): la IP local está fijada a la de la máquina base y debe cambiarse junto con la red del cliente
|-
| fail2ban || <code>/etc/fail2ban/jail.d/</code> || Verificar jail de <code>sshd</code> activo tras el cambio de IP
|-
| Certificado TLS / HTTPS || Vhost <code>cartelia_https.conf</code> incluido de serie (deshabilitado) || Certificado siempre válido, nunca autofirmado: lo aporta el cliente si dispone de él o se emite con Let's Encrypt (<code>certbot certonly</code> para el FQDN; requiere el puerto 80 alcanzable desde internet y renovación automática vía timer de certbot). Instalar certificado y clave en <code>/etc/ssl/cartelia/</code> (o apuntar las directivas <code>SSL*</code> a <code>/etc/letsencrypt/live/<FQDN>/</code>), ajustar <code>ServerName</code>, <code>a2enmod ssl proxy_wstunnel headers</code>, <code>a2ensite cartelia_https</code>, <code>apache2ctl configtest</code> y <code>systemctl reload apache2</code>. Activar después la redirección HTTP→HTTPS en <code>cartelia_http.conf</code> y actualizar en el portal la CMS Address (<code>https://<FQDN></code>) y la dirección de XMR (<code>wss://<FQDN>/xmr</code>)
|-
| Rotación de logs || <code>logrotate</code> || Verificar
|}

== 4.4 Firewall (<code>/etc/firewall/</code>) ==

El firewall se implementa con nftables mediante dos ficheros, ejecutados en el arranque por <code>firewall.service</code>:

{| class="wikitable"
! Fichero !! Función
|-
| <code>/etc/firewall/firewall.sh</code> || Reglas nftables: acepta 80, 443 y 9505 (XMR) hacia la IP local/flotante, 22 solo desde <code>RED_GESTION</code>, checks pasivos de Zabbix (10050) desde el servidor Zabbix, ICMP y tráfico establecido; el resto de entrada se descarta (<code>drop</code>).
|-
| <code>/etc/firewall/vars.sh</code> || Variables de entorno que parametrizan las reglas.
|}

Variables de <code>vars.sh</code> a ajustar en cada despliegue:

{| class="wikitable"
! Variable !! Valor en la máquina base !! Acción en el despliegue
|-
| <code>ETH</code> || <code>ens3</code> || Cambiar solo si la interfaz del clon tiene otro nombre (<code>ip a</code>)
|-
| <code>IP_LOC</code> || IP de la máquina base || Cambiar siempre a la IP del cliente (debe coincidir con la configurada en la sección 3.1, paso 3)
|-
| <code>IP_FLO</code> || Igual a <code>IP_LOC</code> (sin IP flotante) || Mantener igual a <code>IP_LOC</code> salvo despliegue con alta disponibilidad
|-
| <code>RED_DATOS</code> || Red corporativa de la máquina base || Ajustar al direccionamiento del cliente
|-
| <code>RED_GESTION</code> || Red corporativa de la máquina base || Ajustar a la red desde la que se accede por SSH; es la única red con acceso al puerto 22
|}

Aplicación y verificación de cambios:

<syntaxhighlight lang="bash">
# Aplicar (corta y recrea todas las reglas; las conexiones establecidas se mantienen)
/etc/init.d/firewall start

# Verificar reglas cargadas y contadores
/etc/init.d/firewall status

# Verificación remota mínima tras el cambio (desde RED_GESTION)
ssh <usuario>@<IP-del-servidor> # el 22 debe seguir accesible
curl -Is http://<IP-del-servidor>/ | head -1
</syntaxhighlight>

{{Aviso|'''Riesgo operativo''': editar <code>IP_LOC</code> o <code>RED_GESTION</code> con valores erróneos y ejecutar el script '''puede dejar la máquina inaccesible por SSH''' (la política final es <code>drop</code>). Realizar siempre el cambio con una consola de <code>virsh console</code> abierta como vía de recuperación.}}

= 5. Diagnósticos =

== 5.1 Comandos de diagnóstico ==

<syntaxhighlight lang="bash">
# Estado general de la VM desde el host de virtualización
virsh dominfo cartelia-<nombre-del-entorno>
virsh domifaddr cartelia-<nombre-del-entorno>

# Dentro de la VM — estado de servicios
systemctl status apache2 mariadb
systemctl status xibo-xmr.service
journalctl -u apache2 -n 100 --no-pager
journalctl -u xibo-xmr.service -n 100 --no-pager

# Conexión a la base de datos del CMS
mysql -u <usuario-cms> -p -e "SELECT COUNT(*) FROM display;" <bbdd-cms>

# Firewall: reglas activas y contadores por regla
/etc/init.d/firewall status

# Conectividad de los puertos de producto
ss -tlnp | grep -E ':(80|443|9505)\b'

# Prueba del API de players (XMDS): debe responder el WSDL
curl -s "http://localhost/xmds.php?wsdl" | head -5

# Comprobar identidad correcta del clon (no debe coincidir con la plantilla)
cat /etc/machine-id
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
</syntaxhighlight>

== 5.2 Ficheros de log ==

{| class="wikitable"
! Fichero / origen !! Contenido !! Rotación
|-
| Portal ''Administración > Avanzado > Log'' || Log de aplicación del CMS (registro de players, errores XMDS) || Gestionada por la tarea de mantenimiento del CMS
|-
| <code>/var/log/apache2/cartelia_access.log</code>, <code>/var/log/apache2/cartelia_error.log</code> (y <code>cartelia_ssl_*.log</code> con el vhost HTTPS activo) || Accesos y errores del servidor web (portal y API XMDS de players) || logrotate estándar de apache2
|-
| <code>journalctl -u xibo-xmr.service</code> || Log del servicio XMR || journald
|-
| <code>journalctl -u ssh</code>, <code>/var/log/fail2ban.log</code> || Seguridad de acceso al SO || Estándar journald / logrotate
|}

== 5.3 Errores comunes y soluciones ==

{| class="wikitable"
! Síntoma / mensaje !! Causa probable !! Solución
|-
| El portal no carga tras el clonado || La red de la VM no se personalizó o la interfaz cambió de nombre || Revisar <code>ip a</code>, <code>/etc/network/interfaces.d/</code>, y el bridge asignado en libvirt
|-
| Los players no consiguen registrarse || <code>CMS Address</code> o <code>CMS Secret Key</code> incorrectos, o 80/443 filtrados || Verificar sección 4.2 y <code>vars.sh</code> del firewall (4.4); probar <code>curl</code> al XMDS desde la red de players
|-
| Los players se registran pero no reciben órdenes push || Dirección pública de XMR errónea, proxy <code>/xmr</code> no operativo o <code>xibo-xmr</code> caído || Verificar <code>ws(s)://<FQDN>/xmr</code> en el portal, <code>systemctl status xibo-xmr.service</code> y el módulo <code>proxy_wstunnel</code> de Apache; reiniciar XMR
|-
| Aviso de certificado en el navegador || Certificado de la plantilla aún instalado || Sustituir por el certificado del FQDN del entorno
|-
| Dos clones aparecen como la misma máquina en DHCP/monitorización || <code>machine-id</code> no regenerado || Ejecutar <code>rm -f /etc/machine-id && systemd-machine-id-setup</code> y reiniciar
|-
| El CMS no conecta con la base de datos tras cambiar contraseñas || Contraseña cambiada en <code>settings.php</code> pero no en MariaDB (o viceversa) || Sincronizar ambas (ver sección 4.1)
|-
| Sin acceso SSH tras personalizar el firewall || <code>RED_GESTION</code> o <code>IP_LOC</code> erróneas en <code>vars.sh</code> con política final <code>drop</code> || Entrar por <code>virsh console</code>, corregir <code>vars.sh</code> y re-ejecutar <code>/etc/firewall/firewall.sh</code>
|-
| La hora de las programaciones no coincide || Zona horaria o NTP sin configurar || <code>timedatectl set-timezone Europe/Madrid</code> y verificar <code>timedatectl status</code>
|}

Archivo:Cartelia-despliegue-vm-documentacion-tecnica.pdf

2026-07-13T08:28:41Z

Alfredo.rodriguez:

Instalacion cartelia

2026-07-13T08:28:27Z

Alfredo.rodriguez: /* Manual de instalación de cartelia 1.0 */

== Manual de instalación de cartelia 1.0 ==
[[:Media:cartelia-despliegue-vm-documentacion-tecnica.pdf|Instalación de Cartelia 1.0]]
<br>

Omnisuite videoCan

2026-07-13T08:26:36Z

Alfredo.rodriguez:

== Qué es Videocan ==

Videocan es una plataforma de vídeo que dota de '''videocanal''' a un contact center basado en OmniSuite. Permite que una interacción que entra como '''chat''' a través de '''OpenChannel''' se convierta, en la práctica, en una '''videollamada de audio y vídeo''' entre un usuario externo y un agente.

La idea central es sencilla: la llamada '''no es una llamada de audio tradicional''' (no interviene Asterisk en ningún punto). El usuario y el agente acaban entrando en la '''misma sala de videoconferencia''' (hoy basada en Jitsi Meet, comercialmente "Vybite Meet"), y todo el control de cola, enrutado y atención del agente se apoya en la infraestructura existente de OmniSuite vía OpenChannel.

Puntos clave del alcance funcional actual:
* Solo hay '''audio y vídeo'''. No hay compartición de pantalla.
* El '''chat está desactivado''': si se quisiera, debería salir por OpenChannel, no por Meet, así que de momento no se usa.
* Sustituye a la solución anterior basada en '''Vydao''', que se ha reemplazado por '''Meet'''.

=== Contexto: qué es un OpenChannel ===

OpenChannel es el mecanismo de OmniSuite para meter un '''canal de chat''' dentro del contact center. Lo que se inicia es, técnicamente, una '''interacción de chat''' que se encola, hereda todos los procesos típicos de OmniSuite (colas, prioridades, asignación) y acaba siendo atendida por un agente. Videocan se apoya en ese canal de chat para transportar al agente el enlace de la videollamada.

----

== Flujo funcional ==

=== Llamada entrante (usuario → agente) ===

# Un usuario, desde una aplicación web, un navegador o una '''app móvil''' (que internamente abre una página web), introduce una serie de datos y pulsa '''"Iniciar videollamada"'''.
# Ese evento desencadena '''dos cosas en paralelo''':
#* '''Lado usuario:''' se le crea una '''sala de Meet''' y queda en la pantalla de espera de la sala ("esperando conexión").
#* '''Lado OmniSuite:''' se genera una '''interacción de chat por OpenChannel''' que se encola y llega a un agente.
# El agente (logueado en OmniSuite con sus canales) recibe el aviso de interacción en cola. Al aceptarla se le abre una pestaña tipo chat con un mensaje del estilo ''"Nueva llamada de [Nombre], pulsa aquí para unirte"'' y una '''URL'''.
# Esa URL '''no es una URL de Meet''': es una URL del '''API de agente de Videocan''' (lleva <code style="background:none; border:none; padding:0;">get</code>, agente, api-key, etc.). El agente la pulsa.
# Videocan, a partir de esa URL, '''autentica al agente como moderador''' en Meet mediante '''JWT''' y lo introduce en la sala (la misma del usuario).
# Se establece la videollamada. El usuario, que estaba esperando, ve entrar al agente y comienza la comunicación (audio + vídeo vía Meet).

Detalle de seguridad relevante: '''el agente no conoce el nombre de la sala'''. En la URL que recibe va "encholado" (codificado) tanto el JWT como el nombre de sala, de modo que esa URL solo sirve para '''entrarn en esa sala concreta'''.

=== Llamada saliente / "nueva sala" (agente → usuario) ===

La llamada saliente asume que ya existe un canal de comunicación con el destinatario. El mecanismo es deliberadamente simple:

# El agente dispone de un '''plugin / botón ("compartir enlace")''' que genera una nueva sala.
# Videocan '''crea el nombre de la sala al vuelo''' (aleatorio) — la sala la crea Videocan, no Meet directamente.
# Videocan genera un '''JWT''' firmado para esa sala y construye una página web que mete al agente '''ya autenticado''' como moderador.
# El agente '''copia el enlace''' de la reunión y lo envía al destinatario por el canal que corresponda (p. ej. WhatsApp, el propio canal por el que se estuviera hablando).
# Cualquiera que abra ese enlace entra en la sala. Si lo abren varios, entran varios.

<blockquote>El '''API de agente está filtrado por IP''': solo se puede invocar desde dentro (IP privada) o desde una IP fija conocida (p. ej. la salida del entorno del cliente), según el despliegue.</blockquote>

=== Cierre de la llamada ===

La interacción de OpenChannel debería cerrarse al colgar la videollamada (se cuelga "como se cuelga una llamada"). En la demo se observó que en ocasiones el agente tuvo que cerrarla a mano en OpenChannel; queda como punto a confirmar con el equipo experto en OmniSuite si el cierre debe ser automático o manual. Como red de seguridad existen ''timeouts'' (ver §6) para liberar el canal aunque algo quede colgado.

----

== Arquitectura y componentes ==

Todo el módulo se despliega en una '''máquina virtual independiente''' (separada de la de OpenChannel/OmniSuite), sobre '''Debian 13''', y '''requiere una IP pública dedicada''' (puede estar NATeada 1:1). El puerto de RTP de Meet usa esa IP pública.

Conceptualmente es '''una instalación de Vybite Meet (Jitsi) personalizada''' más el demonio propio Videocan. Componentes:

{| class="wikitable"
! Componente !! Función
|-
| '''Nginx''' || Proxy inverso y servidor de contenido. Punto de entrada HTTPS (443/TCP). Publica los tres APIs de Videocan.
|-
| '''Certbot''' || Generación y renovación automática de certificados TLS (Let's Encrypt). Solo en instalaciones '''públicas'''; en instalaciones internas no se instala.
|-
| '''Prosody''' || Servidor XMPP (programado en Lua) sobre el que se apoya Meet. Equivalente moderno al antiguo OpenFire.
|-
| '''Módulo Prosody propio ("mod")''' || Módulo desarrollado a medida que engancha con Videocan; informa de entradas y salidas de la sala para mantener sincronizado OpenChannel con el estado real de Meet.
|-
| '''Jitsi Meet + Jicofo + JVB''' || Pila de videoconferencia. '''JVB = Jitsi Video Bridge''' (puente de medios). Se instala mediante una lista de paquetes homologados.
|-
| '''Videocan (demonio)''' || Demonio propio. Es el "cerebro": expone los APIs, controla canales/llamadas, construye plantillas, gestiona la autenticación del agente y aplica la firma de licencia.
|-
| '''Fail2ban''' || Seguridad (bloqueo por intentos).
|-
| '''nftables''' || Cortafuegos (sustituto de iptables).
|-
| '''Zabbix''' || Monitorización. No reside en esta máquina, pero puede consultarse vía interfaz <code style="background:none; border:none; padding:0;">nc</code> (especialmente para vigilar congestiones).
|}

No hay '''MySQL ni base de datos''' en esta máquina. Tampoco hay LDAP en este entorno. Toda la configuración del módulo vive en un único fichero (ver §6).

=== Los tres APIs del demonio Videocan ===

A través de Nginx, Videocan expone '''tres APIs''':

# '''API de cliente (usuario):''' lo invoca la aplicación del usuario para iniciar la videollamada.
# '''API de agente:''' devuelve al agente la URL que lo autentica como moderador. Filtrable por IP.
# '''API hacia Prosody:''' la usa el módulo de Prosody para notificar eventos de sala (conexión/desconexión, destrucción de sala). Es la "flecha vertical" del diagrama.

Ejemplo de evento observado en el log al destruirse una sala:

<pre>
POST Prosody v_room_destroy
</pre>

Con estos eventos Videocan mantiene '''sincronizados los canales''' con lo que existe realmente en Meet. No debería crearse ninguna sala sin que intervenga Videocan.

=== Protocolos (leyenda del diagrama) ===

{| class="wikitable"
! Color de flecha !! Protocolo
|-
| Azul || HTTP / HTTPS (incluye el API REST)
|-
| Naranja || XMPP y '''BOSH''' (BOSH = encapsulación de XMPP sobre HTTP)
|-
| Verde || '''RTP''' (audio y vídeo), por '''10000/UDP''' en el lado de Meet
|}

<blockquote>El '''10000/UDP''' coincide con el rango que usa Asterisk (10000–20000/UDP), pero no hay conflicto porque '''nunca conviven un Asterisk y un Meet en la misma máquina'''. Ese puerto debe abrirse en el firewall sobre la IP pública del módulo.</blockquote>

----

== Modelo de autenticación y seguridad ==

El modelo es deliberadamente "sin usuarios":
* '''No hay usuarios, ni contraseñas, ni LDAP, ni inventario de usuarios''' en ningún punto.
* Igual que en Meet estándar, '''la seguridad se basa en conocer (o no) las URLs / el nombre de sala'''. Quien conoce el nombre de una sala abierta, entra.
* '''Moderador (agente):''' entra autenticado mediante '''JWT'''. El mero hecho de conocer la URL de agente (un "churro" largo que en teoría solo conoce el agente que coge la llamada) implica ser agente. Esa URL lleva el JWT y el nombre de sala codificados, y solo sirve para esa sala.
* '''Invitados:''' cualquiera que conozca el nombre de la sala puede entrar '''sin autenticar'''.
* Si un agente reenvía su URL a otra persona, esa persona también entraría como moderador. Si dos agentes pinchan la URL que circula por OpenChannel, ambos entran en la misma sala.

=== Diferencias frente a un Vybite Meet estándar ===

Son básicamente '''dos''':

# '''Autenticación del moderador.''' En Vybite Meet estándar el moderador se valida contra LDAP o contra la base de datos de usuarios de Vybite. En Videocan, el moderador (agente) se autentica vía '''JWT generado al vuelo por Videocan''', sin LDAP ni base de datos.
# '''Carteles (textos/idiomas de la interfaz).''' Se sustituyen para que no aparezca la palabra "Jitsi" sino "Vybite", y para corregir las traducciones al castellano.

<blockquote>'''Conclusión operativa:''' un Vybite Meet existente de un cliente '''no sirve''' para dar este servicio. Serían máquinas e instalaciones distintas (por los carteles, las personalizaciones y la IP pública). Solo en un caso muy forzado podría plantearse compartir máquina usando '''dos dominios distintos''' sobre una misma IP pública. Como norma general: '''no'''.</blockquote>

----

== Control de canales ==

* Un '''canal = una llamada'''. El servicio se factura por '''canales simultáneos'''.
* Videocan lleva un control del número de canales en uso y aplica una '''limitación de canales concurrentes''' (<code style="background:none; border:none; padding:0;">videocan_canales_maximo</code>). Si se alcanza el máximo, las nuevas llamadas entran con '''congestión'''.
* Los "hilos" del demonio (p. ej. 2) son para atender peticiones web y no guardan relación con el número de canales; con pocos hilos basta porque no hay tanto tráfico web.
* Diagnóstico en caliente mediante el socket de control:

<pre>
nc localhost 1132
</pre>

Muestra, entre otras cosas, los canales activos (<code style="background:none; border:none; padding:0;">canales_...</code>) y el contador de alarmas (las alarmas suelen deberse a temas de logs).

----

== Configuración: videocan.conf ==

La configuración del módulo está centralizada en un único fichero en formato '''libconfig''', ubicado dentro del árbol <code style="background:none; border:none; padding:0;">/etc/mdtel/</code> (en la máquina de desarrollo mostrada aparecía también como <code style="background:none; border:none; padding:0;">/etc/mdtel-videocan.conf</code>; la convención estándar es <code style="background:none; border:none; padding:0;">/etc/mdtel/videocan.conf</code>).

Para facilitar el despliegue existe un '''configurador''' (cuestionario) que el centro de servicios debe rellenar antes de arrancar una instalación y entregar cumplimentado.

=== Parámetros globales ===

{| class="wikitable"
! Parámetro !! Descripción
|-
| '''host''' (nombre DNS) || El más crítico. Es el nombre de dominio completo (FQDN), p. ej. <code style="background:none; border:none; padding:0;">labmeetvideo.mednova.local</code>. Aparece en '''multitud de sitios, incluso en nombres de fichero'''. Es la razón por la que se instala de cero en cada despliegue (ver §8).
|-
| '''openchannel_apikey''' || API key de OpenChannel/OmniSuite. Por su tamaño no cabe como cadena en libconfig, así que '''se guarda en un fichero aparte''' y el programa lo carga. Ruta: <code style="background:none; border:none; padding:0;">/etc/mdtel/apikey_openchannel.txt</code>. La proporciona el equipo de OmniSuite.
|-
| '''videocan_canales_maximo''' || Número de canales (llamadas) concurrentes soportados.
|-
| '''Filtro IP del API de agente''' || Restringe desde qué IP/máscara se puede invocar el API de agente (p. ej. <code style="background:none; border:none; padding:0;">172.25.x.x</code>). A <code style="background:none; border:none; padding:0;">0</code> queda abierto.
|-
| '''Dominios y certificados''' || Indica si se trabaja con certificados; debe resolverse '''antes''' de instalar.
|-
| '''firma''' || Firma electrónica de la licencia (ver §9). En un fichero base va vacía.
|}

=== 6.2. Parámetros por servicio ===

Los '''servicios''' son, en la práctica, los '''OpenChannels''' (conceptualmente equivalentes a VDNs): los distintos "puntos de entrada" temáticos. Por cada servicio se configura:

{| class="wikitable"
! Parámetro !! Descripción
|-
| '''Nombre interno''' || Identificador intrascendente (1, 2, 3…).
|-
| '''Nombre a mostrar''' || Nombre descriptivo que ve el cliente por defecto como interlocutor (p. ej. "Antonio"). Hay APIs para que cada agente salga con el suyo.
|-
| '''token de servicio''' || Token que el '''usuario''' (no el agente) debe conocer para invocar el servicio; viaja en la URL de usuario. En algún despliegue concreto (FAPS) se decidió que no viaje nada y baste la URL.
|-
| '''url_openchannel''' || URL de OpenChannel que crea el proveedor de la plataforma (Skally) para ese servicio.
|-
| '''Proxy / verificación TLS de OpenChannel''' || Si se sale por proxy y si hay que verificar el certificado de OpenChannel (si es HTTPS).
|-
| '''Timeout de conexión de agente (s)''' || Tiempo máximo que el cliente espera sin que entre el agente; al vencer se '''cuelga la interacción de OpenChannel''' (en Meet no se puede informar al cliente, así que solo se corta OpenChannel). Se baraja fijarlo en torno a '''3600 s''' como red de seguridad y sacarlo del configurador.
|-
| '''Expiración del JWT de agente (s)''' || Tiempo que tiene el agente para '''entrar''' con el JWT (no limita la duración de la conversación). Valor mostrado: '''1800 s''' (30 min).
|-
| '''Antirrebotes''' || Si llegan varias peticiones al mismo servicio desde la misma IP en una ventana (p. ej. '''20 s'''), se etiquetan como rebote (doble clic) y no entran.
|-
| '''Timeout de liberación de sala (s)''' || Si una sala no se libera sola, se libera el canal a los '''30 s''' de detectar que no hay sala. Red de seguridad heredada de antes de existir el API de Prosody; el canal liberado cuenta para los concurrentes.
|-
| '''Nombre por defecto''' || Nombre a mostrar cuando los datos entrantes no incluyen nombre.
|-
| '''Variables''' || Pares nombre/valor (ver §7). Las fijas (<code style="background:none; border:none; padding:0;">$0</code>–<code style="background:none; border:none; padding:0;">$2</code>) más las específicas por servicio (de <code style="background:none; border:none; padding:0;">$3</code> en adelante).
|}

=== Datos de entrada del usuario ===

La aplicación de front-end recopila los datos que quiera y los envía al invocar el inicio de videollamada. '''No hay un conjunto de datos fijo'''; pueden llegar como argumentos de un GET o como JSON, pero el API siempre trabaja con '''pares nombre/valor'''. Ejemplos:
* '''Servicio "videollamada" (FAPS):''' <code style="background:none; border:none; padding:0;">name</code>, <code style="background:none; border:none; padding:0;">lastname</code>, <code style="background:none; border:none; padding:0;">id</code> (que aquí es el móvil), correo, <code style="background:none; border:none; padding:0;">dni</code>.
* '''Servicio "emergencia 112":''' solo llegan '''latitud y longitud'''; al no llegar nombre, el campo nombre queda vacío.

----

== Plantillas ==

Ubicación: <code style="background:none; border:none; padding:0;">/etc/mdtel-videocan/templates</code>.

Una '''plantilla''' es la '''página web''' que Videocan devuelve cuando se invoca una URL del API (por ejemplo <code style="background:none; border:none; padding:0;">get_agente_nuevasala</code>). Es una página con lógica, específica de cada llamada (no solo de cada servicio), porque el nombre de sala se genera al vuelo para cada llamada.

* Las '''variables''' se marcan con $:
** <code style="background:none; border:none; padding:0;">$0</code> → host
** <code style="background:none; border:none; padding:0;">$1</code> → sala de la videollamada (creada al vuelo)
** <code style="background:none; border:none; padding:0;">$2</code> → nombre a mostrar (<code style="background:none; border:none; padding:0;">displayName</code>)
** <code style="background:none; border:none; padding:0;">$3</code> → token JWT (cadena)
** de <code style="background:none; border:none; padding:0;">$3</code>/siguientes en adelante → variables específicas del servicio
* Videocan sustituye las variables en la plantilla y entrega la página resultante. Quien la recibe queda viendo una '''sala de Meet ya con el JWT aplicado''', entrando autenticado.
* Las plantillas usan el '''API de integración de Jitsi Meet''' (referencia pública: <code style="background:none; border:none; padding:0;">jitsi-meet-api-integration</code>). '''No se usa un IFrame''': la sala se integra directamente en la página (un IFrame "siempre es puñetero"). El JavaScript de la integración vive en las plantillas.
* Permiten '''personalizar el aspecto''': por ejemplo <code style="background:none; border:none; padding:0;">toolbarButtons</code> (qué botones se muestran; hay muchos comentados/quitados), <code style="background:none; border:none; padding:0;">startWithAudioMuted</code>, el botón de '''Full Screen''' (se muestra el botón, no se entra en pantalla completa automáticamente), etc.
* Puede haber '''una plantilla por servicio''', pero lo habitual es que sean '''compartidas''' porque todos los servicios ven prácticamente lo mismo. Las diferencias razonables serían pequeñas (p. ej. permitir o no grabar, activar el botón de chat) y se tocarían vía <code style="background:none; border:none; padding:0;">toolbarButtons</code>.

<blockquote>'''Limitación conocida (móvil):''' al entrar compartiendo la URL, el usuario entra en vista de '''interlocutor en grande''' (no en cuadrícula), por lo que en el móvil '''no se ve a sí mismo'''. Es un problema relevante para lengua de signos, donde la persona necesita verse para comprobar el encuadre. Pulsando el botón de cuadrícula se soluciona, pero la intención es que la app sea transparente. El ajuste no se puede hacer por parámetros de URL; '''habría que resolverlo con JavaScript''' en la plantilla. Queda como punto abierto.</blockquote>

----

== Instalación ==

<blockquote>El planteamiento actual es '''instalar siempre de cero''' (no entregar una imagen de máquina virtual), porque el '''nombre del host está en multitud de sitios''' (incluidos nombres de fichero) y reescribirlo en una imagen sería más complejo. Si en el futuro hubiera muchas instalaciones, podría replantearse.</blockquote>

=== Prerrequisitos y orden ===

# Obtener la '''IP pública''' y darla de alta en '''DNS''' (lo hace el cliente o nosotros, según de quién sea el dominio). Sin nombre DNS no se puede instalar (se necesita para el certificado).
# Instalar '''Nginx''' y '''Certbot''', obtener el '''certificado''' y crear el '''firewall''' (nftables).
# Instalar '''Meet''' mediante la lista de paquetes homologados (<code style="background:none; border:none; padding:0;">apt install <paquete></code>, uno a uno). '''No se instala el repositorio de Jitsi''', sino paquetes concretos y homologados.
# La instalación de Meet '''modifica la configuración de Nginx y de Prosody''', así que tras instalarlo hay que '''reajustar''' ambos. (La configuración que deja Meet por defecto no sirve.) El proceso requiere iterar y reconfigurar varias veces.
# Sustituir el '''contenido estático''' (ver §8.2).
# Rellenar <code style="background:none; border:none; padding:0;">videocan.conf</code>, instalar el demonio, configurar el JWT en Prosody y '''firmar''' (ver §9).

<blockquote>Detalle de <code style="background:none; border:none; padding:0;">apt</code>: para instalar un <code style="background:none; border:none; padding:0;">.deb</code> local hay que indicar una ruta de directorio; por eso se usa <code style="background:none; border:none; padding:0;">apt install ./paquete.deb</code> (con <code style="background:none; border:none; padding:0;">./</code>). Se usa <code style="background:none; border:none; padding:0;">apt install</code> en lugar de <code style="background:none; border:none; padding:0;">dpkg -i</code> porque '''resuelve dependencias'''.</blockquote>

Existe un '''punto intermedio de validación''' muy útil: cuando todo funciona '''sin autenticación''', cualquiera que conozca el nombre de sala entra directamente. Si <code style="background:none; border:none; padding:0;">host/pepito</code> permite que varios se conecten a la sala "pepito" sin autenticar, la instalación base está correcta. A partir de ahí se valida el resto tirando de logs y de la herramienta <code style="background:none; border:none; padding:0;">jitsi-debug</code> (sección ''Health'').

=== Contenido estático (carteles y personalización) ===

* Jitsi instala un directorio de contenido estático en <code style="background:none; border:none; padding:0;">/usr/share/jitsi-meet/…</code>. Videocan '''lo reemplaza entero''' por uno propio (logos, fondos, textos "Vybite Meet"). Ese directorio propio es '''igual para todas las instalaciones''' (no se configura nada en él).
* Los '''carteles''' (textos de interfaz) están en <code style="background:none; border:none; padding:0;">/usr/share/jitsi-meet/lang/</code>:
** <code style="background:none; border:none; padding:0;">main.json</code> → inglés (suele estar bien, retocado para sustituir "Jitsi" por "Vybite").
** <code style="background:none; border:none; padding:0;">main-es.json</code> → castellano (~1700 carteles; las traducciones por defecto son deficientes y se corrigen).
* '''No se recomienda modificar los DEB''' para empaquetar el contenido propio: como los paquetes modifican configuraciones y Meet cambia con frecuencia, no compensa.
* '''Actualizaciones (update/upgrade):''' son arriesgadas porque pueden '''reescribir los carteles''' (decenas de cambios por actualización). El procedimiento de mantenimiento de carteles consiste en comparar a tres (inglés viejo, inglés nuevo, español nuevo) con una herramienta tipo '''Meld''' o el comparador de '''Notepad++''', y trasladar los cambios manteniendo coherencia terminológica. Por eso Meet '''no se actualiza en cada release''', sino periódicamente, y solo cuando interesa (la mayoría de novedades —integración con Drive, transcripción, traducción simultánea— no se usan). La transcripción se apoya en '''Vosk''', que de momento da resultados pobres. Las actualizaciones por '''seguridad''' sí deberán contemplarse.

=== Instalación del demonio Videocan ===

Sigue el estándar de los demonios "mdtel":
* Binario y módulo en '''<code style="background:none; border:none; padding:0;">/opt/videocan/bin/</code>''' (<code style="background:none; border:none; padding:0;">/opt/videocan/</code> como raíz; el módulo de Prosody también reside ahí).
* Arranque en '''<code style="background:none; border:none; padding:0;">/etc/init.d/</code>'''.
* Configuración en '''<code style="background:none; border:none; padding:0;">/etc/mdtel/videocan.conf</code>''' (más <code style="background:none; border:none; padding:0;">apikey_openchannel.txt</code> en el mismo árbol).
* Rotación de logs en '''<code style="background:none; border:none; padding:0;">/etc/logrotate.d/videocan</code>'''.
* Logs en '''<code style="background:none; border:none; padding:0;">/var/log/videocan/videocan.log</code>''' (el demonio corre como usuario <code style="background:none; border:none; padding:0;">videocan</code>, '''no como root''', por estar publicado en web).

=== Instalaciones existentes (referencia) ===

* '''<code style="background:none; border:none; padding:0;">labmeetvideo.mednova.local</code>''' — instalación interna (sin Certbot, no publicada).
* '''<code style="background:none; border:none; padding:0;">mdtel.videocan01.vybite.es</code>''' — instalación con IP pública (en Soax), para el centro de servicios de pruebas/demos.

----

== Firma de licencia y tokens ==

El <code style="background:none; border:none; padding:0;">videocan.conf</code> debe estar protegido para que '''no se pueda manipular''' (por ejemplo, cambiar el número de canales a 2000). Esa protección es la '''firma electrónica''', que usa el '''mismo procedimiento y los mismos certificados que Vybite'''.

=== Qué se protege ===

La firma cubre '''tres''' valores:
# '''Número de servicios''' (no su contenido: se pueden modificar libremente, pero no crear más de los firmados).
# '''Número de canales.'''
# '''host''' (dominio) — para que no se pueda instalar en muchos sitios con la misma licencia.

=== Tokens ===

* Los '''tokens''' y el '''<code style="background:none; border:none; padding:0;">JWT_SECRET</code>''' hacen que cada instalación sea '''distinta'''. La herramienta de firma puede regenerarlos (claves particulares aleatorias por instalación).
* El '''token de servicio''' debe '''coincidir''' con lo que conoce la '''aplicación de usuario''' del otro lado. Por eso, cuando se regeneran tokens, hay que revisar las URLs de acceso y, en su caso, tocar la página web que se entrega al cliente (p. ej. en FAPS, el token lo tenemos nosotros, así que se ajusta en la página web alojada en esta máquina).
* El '''<code style="background:none; border:none; padding:0;">JWT_SECRET</code>''' debe configurarse en '''Prosody''' como '''<code style="background:none; border:none; padding:0;">APP_SECRET</code>''' (ver §9.4).

=== Herramienta videocan-firmar ===

Primer parámetro = operación a realizar:

{| class="wikitable"
! Operación !! Efecto
|-
| '''Generar tokens''' || Regenera los tokens (not firma). No requiere la clave; podría delegarse al cliente.
|-
| '''Firmar''' || Generar solo la firma.
|-
| '''Generar tokens y firmar''' || Operación recomendada para todas las instalaciones.
|-
| '''Verificar''' || Indica si la firma del fichero es válida. No requiere clave (va embebida en la herramienta).
|}

Reglas:
* Siempre se indica '''el fichero de configuración''' (no se modifica el original: la herramienta entrega '''otro fichero''' ya procesado).
* Para '''firmar''' se necesita el '''fichero de clave privada (.key)'''; para '''verificar''' no se necesita nada.

Ejemplos:

<pre>
# Verificar
videocan-firmar verificar /etc/mdtel/videocan.conf
# → "La sección Videocan tiene un campo firma que no es correcto.
# Error al verificar firma de videocan.conf." (si no es válido)

# Generar tokens + firmar (recomendado)
videocan-firmar tokens-firmar mdtel.key videocan.conf
# → "Operación correcta. Se actualiza el fichero."
# Avisos: token de servicio modificado (revisar URLs de acceso),
# JWT_SECRET modificado (configurar APP_SECRET y reiniciar Prosody),
# firma del archivo modificada.
</pre>

Una verificación correcta enumera qué se está firmando (host, número de servicios, número de canales) y termina con un <code style="background:none; border:none; padding:0;">OK</code> en la '''última línea''':

<pre>
Host labmeetvideo... ok
</pre>

=== Tras firmar ===

# Configurar '''<code style="background:none; border:none; padding:0;">APP_SECRET</code>''' en Prosody con el nuevo <code style="background:none; border:none; padding:0;">JWT_SECRET</code>. Configuración de Prosody en '''<code style="background:none; border:none; padding:0;">/etc/prosody/conf.avail/</code>''' (estructura similar a la de Nginx; el fichero incluye el nombre de dominio).
# '''Reiniciar Prosody.'''
# Revisar las '''URLs de acceso''' afectadas por el cambio de tokens de servicio.

=== 9.5. Comportamiento sin firma válida ("la bomba") ===

Si la firma '''no es válida''', el sistema '''sigue funcionando pero limitado a 1 canal''' (<code style="background:none; border:none; padding:0;">canales_max = 1</code>). El paso a 1 canal '''no ocurre en el arranque''', sino tras un tiempo indeterminado (diseñado así para dificultar su localización en el código). Esto permite, en la práctica, '''hacer demos''': con el fichero sin firmar y configurado a 1 canal, todo funciona. El procedimiento habitual del cliente puede ser instalar primero (con tokens, para que arranque y se pueda probar) y '''entregarnos después el fichero para que lo firmemos''' con las licencias.

----

== Diagnóstico y logs ==

{| class="wikitable"
! Recurso !! Uso
|-
| <code style="background:none; border:none; padding:0;">nc localhost 1132</code> || Socket de control de Videocan: canales activos, alarmas, congestión.
|-
| <code style="background:none; border:none; padding:0;">/var/log/videocan/videocan.log</code> || Log del demonio Videocan.
|-
| <code style="background:none; border:none; padding:0;">/var/log/prosody/</code> || Log de Prosody.
|-
| <code style="background:none; border:none; padding:0;">/var/log/nginx/</code> || Log de Nginx.
|-
| <code style="background:none; border:none; padding:0;">/var/log/jitsi/</code> || Log de la pila Jitsi.
|-
| <code style="background:none; border:none; padding:0;">jitsi-debug</code> (script) || Comprobación de salud de la instalación (sección ''Health'').
|-
| '''Zabbix''' (vía <code style="background:none; border:none; padding:0;">nc</code>) || Monitorización externa, especialmente de congestiones, explotando el socket <code style="background:none; border:none; padding:0;">nc</code>.
|}

----

== Resumen de rutas y puertos ==

'''Rutas (convención estándar <code style="background:none; border:none; padding:0;">/etc/mdtel/</code>):'''

<pre>
/opt/videocan/bin/ # demonio Videocan + módulo
/etc/init.d/videocan # arranque
/etc/mdtel/videocan.conf # configuración principal (libconfig)
/etc/mdtel/apikey_openchannel.txt # API key de OpenChannel
/etc/mdtel-videocan/templates/ # plantillas (páginas web con JS de integración Meet)
/etc/logrotate.d/videocan # rotación de logs
/etc/prosody/conf.avail/ # configuración de Prosody (APP_SECRET)
/var/log/videocan/videocan.log # log del demonio (usuario videocan)
/usr/share/jitsi-meet/ # contenido estático (reemplazado por el propio)
/usr/share/jitsi-meet/lang/main.json # carteles inglés
/usr/share/jitsi-meet/lang/main-es.json # carteles castellano (~1700)
</pre>

'''Puertos:'''

<pre>
443/TCP Nginx (HTTPS, proxy inverso, APIs de Videocan)
10000/UDP RTP de Meet (audio/vídeo) sobre la IP pública
1132 Socket de control local de Videocan (nc localhost 1132)
</pre>

----

== Limitaciones y puntos abiertos ==

* '''Solo audio y vídeo'''; sin compartición de pantalla ni chat (el chat, si se activase, debería ir por OpenChannel).
* '''Cierre de la interacción OpenChannel:''' confirmar con el equipo de OmniSuite si debe ser automático o manual.
* '''Requiere IP pública dedicada''' por máquina (a día de hoy).

Omnisuite videoCan

2026-07-13T08:23:59Z

Alfredo.rodriguez: /* Doc de transcripción */

== Qué es Videocan ==

Videocan es una plataforma de vídeo que dota de '''videocanal''' a un contact center basado en OmniSuite. Permite que una interacción que entra como '''chat''' a través de '''OpenChannel''' se convierta, en la práctica, en una '''videollamada de audio y vídeo''' entre un usuario externo y un agente.

La idea central es sencilla: la llamada '''no es una llamada de audio tradicional''' (no interviene Asterisk en ningún punto). El usuario y el agente acaban entrando en la '''misma sala de videoconferencia''' (hoy basada en Jitsi Meet, comercialmente "Vybite Meet"), y todo el control de cola, enrutado y atención del agente se apoya en la infraestructura existente de OmniSuite vía OpenChannel.

Puntos clave del alcance funcional actual:
* Solo hay '''audio y vídeo'''. No hay compartición de pantalla.
* El '''chat está desactivado''': si se quisiera, debería salir por OpenChannel, no por Meet, así que de momento no se usa.
* Sustituye a la solución anterior basada en '''Vydao''', que se ha reemplazado por '''Meet'''.

=== Contexto: qué es un OpenChannel ===

OpenChannel es el mecanismo de OmniSuite para meter un '''canal de chat''' dentro del contact center. Lo que se inicia es, técnicamente, una '''interacción de chat''' que se encola, hereda todos los procesos típicos de OmniSuite (colas, prioridades, asignación) y acaba siendo atendida por un agente. Videocan se apoya en ese canal de chat para transportar al agente el enlace de la videollamada.

----

== Flujo funcional ==

=== Llamada entrante (usuario → agente) ===

# Un usuario, desde una aplicación web, un navegador o una '''app móvil''' (que internamente abre una página web), introduce una serie de datos y pulsa '''"Iniciar videollamada"'''.
# Ese evento desencadena '''dos cosas en paralelo''':
#* '''Lado usuario:''' se le crea una '''sala de Meet''' y queda en la pantalla de espera de la sala ("esperando conexión").
#* '''Lado OmniSuite:''' se genera una '''interacción de chat por OpenChannel''' que se encola y llega a un agente.
# El agente (logueado en OmniSuite con sus canales) recibe el aviso de interacción en cola. Al aceptarla se le abre una pestaña tipo chat con un mensaje del estilo ''"Nueva llamada de [Nombre], pulsa aquí para unirte"'' y una '''URL'''.
# Esa URL '''no es una URL de Meet''': es una URL del '''API de agente de Videocan''' (lleva <code style="background:none; border:none; padding:0;">get</code>, agente, api-key, etc.). El agente la pulsa.
# Videocan, a partir de esa URL, '''autentica al agente como moderador''' en Meet mediante '''JWT''' y lo introduce en la sala (la misma del usuario).
# Se establece la videollamada. El usuario, que estaba esperando, ve entrar al agente y comienza la comunicación (audio + vídeo vía Meet).

Detalle de seguridad relevante: '''el agente no conoce el nombre de la sala'''. En la URL que recibe va "encholado" (codificado) tanto el JWT como el nombre de sala, de modo que esa URL solo sirve para '''entrarn en esa sala concreta'''.

=== Llamada saliente / "nueva sala" (agente → usuario) ===

La llamada saliente asume que ya existe un canal de comunicación con el destinatario. El mecanismo es deliberadamente simple:

# El agente dispone de un '''plugin / botón ("compartir enlace")''' que genera una nueva sala.
# Videocan '''crea el nombre de la sala al vuelo''' (aleatorio) — la sala la crea Videocan, no Meet directamente.
# Videocan genera un '''JWT''' firmado para esa sala y construye una página web que mete al agente '''ya autenticado''' como moderador.
# El agente '''copia el enlace''' de la reunión y lo envía al destinatario por el canal que corresponda (p. ej. WhatsApp, el propio canal por el que se estuviera hablando).
# Cualquiera que abra ese enlace entra en la sala. Si lo abren varios, entran varios.

<blockquote>El '''API de agente está filtrado por IP''': solo se puede invocar desde dentro (IP privada) o desde una IP fija conocida (p. ej. la salida del entorno del cliente), según el despliegue.</blockquote>

=== Cierre de la llamada ===

La interacción de OpenChannel debería cerrarse al colgar la videollamada (se cuelga "como se cuelga una llamada"). En la demo se observó que en ocasiones el agente tuvo que cerrarla a mano en OpenChannel; queda como punto a confirmar con el equipo experto en OmniSuite si el cierre debe ser automático o manual. Como red de seguridad existen ''timeouts'' (ver §6) para liberar el canal aunque algo quede colgado.

----

== 3. Arquitectura y componentes ==

Todo el módulo se despliega en una '''máquina virtual independiente''' (separada de la de OpenChannel/OmniSuite), sobre '''Debian 13''', y '''requiere una IP pública dedicada''' (puede estar NATeada 1:1). El puerto de RTP de Meet usa esa IP pública.

Conceptualmente es '''una instalación de Vybite Meet (Jitsi) personalizada''' más el demonio propio Videocan. Componentes:

{| class="wikitable"
! Componente !! Función
|-
| '''Nginx''' || Proxy inverso y servidor de contenido. Punto de entrada HTTPS (443/TCP). Publica los tres APIs de Videocan.
|-
| '''Certbot''' || Generación y renovación automática de certificados TLS (Let's Encrypt). Solo en instalaciones '''públicas'''; en instalaciones internas no se instala.
|-
| '''Prosody''' || Servidor XMPP (programado en Lua) sobre el que se apoya Meet. Equivalente moderno al antiguo OpenFire.
|-
| '''Módulo Prosody propio ("mod")''' || Módulo desarrollado a medida que engancha con Videocan; informa de entradas y salidas de la sala para mantener sincronizado OpenChannel con el estado real de Meet.
|-
| '''Jitsi Meet + Jicofo + JVB''' || Pila de videoconferencia. '''JVB = Jitsi Video Bridge''' (puente de medios). Se instala mediante una lista de paquetes homologados.
|-
| '''Videocan (demonio)''' || Demonio propio. Es el "cerebro": expone los APIs, controla canales/llamadas, construye plantillas, gestiona la autenticación del agente y aplica la firma de licencia.
|-
| '''Fail2ban''' || Seguridad (bloqueo por intentos).
|-
| '''nftables''' || Cortafuegos (sustituto de iptables).
|-
| '''Zabbix''' || Monitorización. No reside en esta máquina, pero puede consultarse vía interfaz <code style="background:none; border:none; padding:0;">nc</code> (especialmente para vigilar congestiones).
|}

No hay '''MySQL ni base de datos''' en esta máquina. Tampoco hay LDAP en este entorno. Toda la configuración del módulo vive en un único fichero (ver §6).

=== 3.1. Los tres APIs del demonio Videocan ===

A través de Nginx, Videocan expone '''tres APIs''':

# '''API de cliente (usuario):''' lo invoca la aplicación del usuario para iniciar la videollamada.
# '''API de agente:''' devuelve al agente la URL que lo autentica como moderador. Filtrable por IP.
# '''API hacia Prosody:''' la usa el módulo de Prosody para notificar eventos de sala (conexión/desconexión, destrucción de sala). Es la "flecha vertical" del diagrama.

Ejemplo de evento observado en el log al destruirse una sala:

<pre>
POST Prosody v_room_destroy
</pre>

Con estos eventos Videocan mantiene '''sincronizados los canales''' con lo que existe realmente en Meet. No debería crearse ninguna sala sin que intervenga Videocan.

=== 3.2. Protocolos (leyenda del diagrama) ===

{| class="wikitable"
! Color de flecha !! Protocolo
|-
| Azul || HTTP / HTTPS (incluye el API REST)
|-
| Naranja || XMPP y '''BOSH''' (BOSH = encapsulación de XMPP sobre HTTP)
|-
| Verde || '''RTP''' (audio y vídeo), por '''10000/UDP''' en el lado de Meet
|}

<blockquote>El '''10000/UDP''' coincide con el rango que usa Asterisk (10000–20000/UDP), pero no hay conflicto porque '''nunca conviven un Asterisk y un Meet en la misma máquina'''. Ese puerto debe abrirse en el firewall sobre la IP pública del módulo.</blockquote>

----

== 4. Modelo de autenticación y seguridad ==

El modelo es deliberadamente "sin usuarios":
* '''No hay usuarios, ni contraseñas, ni LDAP, ni inventario de usuarios''' en ningún punto.
* Igual que en Meet estándar, '''la seguridad se basa en conocer (o no) las URLs / el nombre de sala'''. Quien conoce el nombre de una sala abierta, entra.
* '''Moderador (agente):''' entra autenticado mediante '''JWT'''. El mero hecho de conocer la URL de agente (un "churro" largo que en teoría solo conoce el agente que coge la llamada) implica ser agente. Esa URL lleva el JWT y el nombre de sala codificados, y solo sirve para esa sala.
* '''Invitados:''' cualquiera que conozca el nombre de la sala puede entrar '''sin autenticar'''.
* Si un agente reenvía su URL a otra persona, esa persona también entraría como moderador. Si dos agentes pinchan la URL que circula por OpenChannel, ambos entran en la misma sala.

=== Diferencias frente a un Vybite Meet estándar ===

Son básicamente '''dos''':

# '''Autenticación del moderador.''' En Vybite Meet estándar el moderador se valida contra LDAP o contra la base de datos de usuarios de Vybite. En Videocan, el moderador (agente) se autentica vía '''JWT generado al vuelo por Videocan''', sin LDAP ni base de datos.
# '''Carteles (textos/idiomas de la interfaz).''' Se sustituyen para que no aparezca la palabra "Jitsi" sino "Vybite", y para corregir las traducciones al castellano.

<blockquote>'''Conclusión operativa:''' un Vybite Meet existente de un cliente '''no sirve''' para dar este servicio. Serían máquinas e instalaciones distintas (por los carteles, las personalizaciones y la IP pública). Solo en un caso muy forzado podría plantearse compartir máquina usando '''dos dominios distintos''' sobre una misma IP pública. Como norma general: '''no'''.</blockquote>

----

== 5. Control de canales ==

* Un '''canal = una llamada'''. El servicio se factura por '''canales simultáneos'''.
* Videocan lleva un control del número de canales en uso y aplica una '''limitación de canales concurrentes''' (<code style="background:none; border:none; padding:0;">videocan_canales_maximo</code>). Si se alcanza el máximo, las nuevas llamadas entran con '''congestión'''.
* Los "hilos" del demonio (p. ej. 2) son para atender peticiones web y no guardan relación con el número de canales; con pocos hilos basta porque no hay tanto tráfico web.
* Diagnóstico en caliente mediante el socket de control:

<pre>
nc localhost 1132
</pre>

Muestra, entre otras cosas, los canales activos (<code style="background:none; border:none; padding:0;">canales_...</code>) y el contador de alarmas (las alarmas suelen deberse a temas de logs).

----

== 6. Configuración: videocan.conf ==

La configuración del módulo está centralizada en un único fichero en formato '''libconfig''', ubicado dentro del árbol <code style="background:none; border:none; padding:0;">/etc/mdtel/</code> (en la máquina de desarrollo mostrada aparecía también como <code style="background:none; border:none; padding:0;">/etc/mdtel-videocan.conf</code>; la convención estándar es <code style="background:none; border:none; padding:0;">/etc/mdtel/videocan.conf</code>).

Para facilitar el despliegue existe un '''configurador''' (cuestionario) que el centro de servicios debe rellenar antes de arrancar una instalación y entregar cumplimentado.

=== 6.1. Parámetros globales ===

{| class="wikitable"
! Parámetro !! Descripción
|-
| '''host''' (nombre DNS) || El más crítico. Es el nombre de dominio completo (FQDN), p. ej. <code style="background:none; border:none; padding:0;">labmeetvideo.mednova.local</code>. Aparece en '''multitud de sitios, incluso en nombres de fichero'''. Es la razón por la que se instala de cero en cada despliegue (ver §8).
|-
| '''openchannel_apikey''' || API key de OpenChannel/OmniSuite. Por su tamaño no cabe como cadena en libconfig, así que '''se guarda en un fichero aparte''' y el programa lo carga. Ruta: <code style="background:none; border:none; padding:0;">/etc/mdtel/apikey_openchannel.txt</code>. La proporciona el equipo de OmniSuite.
|-
| '''videocan_canales_maximo''' || Número de canales (llamadas) concurrentes soportados.
|-
| '''Filtro IP del API de agente''' || Restringe desde qué IP/máscara se puede invocar el API de agente (p. ej. <code style="background:none; border:none; padding:0;">172.25.x.x</code>). A <code style="background:none; border:none; padding:0;">0</code> queda abierto.
|-
| '''Dominios y certificados''' || Indica si se trabaja con certificados; debe resolverse '''antes''' de instalar.
|-
| '''firma''' || Firma electrónica de la licencia (ver §9). En un fichero base va vacía.
|}

=== 6.2. Parámetros por servicio ===

Los '''servicios''' son, en la práctica, los '''OpenChannels''' (conceptualmente equivalentes a VDNs): los distintos "puntos de entrada" temáticos. Por cada servicio se configura:

{| class="wikitable"
! Parámetro !! Descripción
|-
| '''Nombre interno''' || Identificador intrascendente (1, 2, 3…).
|-
| '''Nombre a mostrar''' || Nombre descriptivo que ve el cliente por defecto como interlocutor (p. ej. "Antonio"). Hay APIs para que cada agente salga con el suyo.
|-
| '''token de servicio''' || Token que el '''usuario''' (no el agente) debe conocer para invocar el servicio; viaja en la URL de usuario. En algún despliegue concreto (FAPS) se decidió que no viaje nada y baste la URL.
|-
| '''url_openchannel''' || URL de OpenChannel que crea el proveedor de la plataforma (Skally) para ese servicio.
|-
| '''Proxy / verificación TLS de OpenChannel''' || Si se sale por proxy y si hay que verificar el certificado de OpenChannel (si es HTTPS).
|-
| '''Timeout de conexión de agente (s)''' || Tiempo máximo que el cliente espera sin que entre el agente; al vencer se '''cuelga la interacción de OpenChannel''' (en Meet no se puede informar al cliente, así que solo se corta OpenChannel). Se baraja fijarlo en torno a '''3600 s''' como red de seguridad y sacarlo del configurador.
|-
| '''Expiración del JWT de agente (s)''' || Tiempo que tiene el agente para '''entrar''' con el JWT (no limita la duración de la conversación). Valor mostrado: '''1800 s''' (30 min).
|-
| '''Antirrebotes''' || Si llegan varias peticiones al mismo servicio desde la misma IP en una ventana (p. ej. '''20 s'''), se etiquetan como rebote (doble clic) y no entran.
|-
| '''Timeout de liberación de sala (s)''' || Si una sala no se libera sola, se libera el canal a los '''30 s''' de detectar que no hay sala. Red de seguridad heredada de antes de existir el API de Prosody; el canal liberado cuenta para los concurrentes.
|-
| '''Nombre por defecto''' || Nombre a mostrar cuando los datos entrantes no incluyen nombre.
|-
| '''Variables''' || Pares nombre/valor (ver §7). Las fijas (<code style="background:none; border:none; padding:0;">$0</code>–<code style="background:none; border:none; padding:0;">$2</code>) más las específicas por servicio (de <code style="background:none; border:none; padding:0;">$3</code> en adelante).
|}

=== 6.3. Datos de entrada del usuario ===

La aplicación de front-end recopila los datos que quiera y los envía al invocar el inicio de videollamada. '''No hay un conjunto de datos fijo'''; pueden llegar como argumentos de un GET o como JSON, pero el API siempre trabaja con '''pares nombre/valor'''. Ejemplos:
* '''Servicio "videollamada" (FAPS):''' <code style="background:none; border:none; padding:0;">name</code>, <code style="background:none; border:none; padding:0;">lastname</code>, <code style="background:none; border:none; padding:0;">id</code> (que aquí es el móvil), correo, <code style="background:none; border:none; padding:0;">dni</code>.
* '''Servicio "emergencia 112":''' solo llegan '''latitud y longitud'''; al no llegar nombre, el campo nombre queda vacío.

----

== 7. Plantillas ==

Ubicación: <code style="background:none; border:none; padding:0;">/etc/mdtel-videocan/templates</code>.

Una '''plantilla''' es la '''página web''' que Videocan devuelve cuando se invoca una URL del API (por ejemplo <code style="background:none; border:none; padding:0;">get_agente_nuevasala</code>). Es una página con lógica, específica de cada llamada (no solo de cada servicio), porque el nombre de sala se genera al vuelo para cada llamada.

* Las '''variables''' se marcan con $:
** <code style="background:none; border:none; padding:0;">$0</code> → host
** <code style="background:none; border:none; padding:0;">$1</code> → sala de la videollamada (creada al vuelo)
** <code style="background:none; border:none; padding:0;">$2</code> → nombre a mostrar (<code style="background:none; border:none; padding:0;">displayName</code>)
** <code style="background:none; border:none; padding:0;">$3</code> → token JWT (cadena)
** de <code style="background:none; border:none; padding:0;">$3</code>/siguientes en adelante → variables específicas del servicio
* Videocan sustituye las variables en la plantilla y entrega la página resultante. Quien la recibe queda viendo una '''sala de Meet ya con el JWT aplicado''', entrando autenticado.
* Las plantillas usan el '''API de integración de Jitsi Meet''' (referencia pública: <code style="background:none; border:none; padding:0;">jitsi-meet-api-integration</code>). '''No se usa un IFrame''': la sala se integra directamente en la página (un IFrame "siempre es puñetero"). El JavaScript de la integración vive en las plantillas.
* Permiten '''personalizar el aspecto''': por ejemplo <code style="background:none; border:none; padding:0;">toolbarButtons</code> (qué botones se muestran; hay muchos comentados/quitados), <code style="background:none; border:none; padding:0;">startWithAudioMuted</code>, el botón de '''Full Screen''' (se muestra el botón, no se entra en pantalla completa automáticamente), etc.
* Puede haber '''una plantilla por servicio''', pero lo habitual es que sean '''compartidas''' porque todos los servicios ven prácticamente lo mismo. Las diferencias razonables serían pequeñas (p. ej. permitir o no grabar, activar el botón de chat) y se tocarían vía <code style="background:none; border:none; padding:0;">toolbarButtons</code>.

<blockquote>'''Limitación conocida (móvil):''' al entrar compartiendo la URL, el usuario entra en vista de '''interlocutor en grande''' (no en cuadrícula), por lo que en el móvil '''no se ve a sí mismo'''. Es un problema relevante para lengua de signos, donde la persona necesita verse para comprobar el encuadre. Pulsando el botón de cuadrícula se soluciona, pero la intención es que la app sea transparente. El ajuste no se puede hacer por parámetros de URL; '''habría que resolverlo con JavaScript''' en la plantilla. Queda como punto abierto.</blockquote>

----

== 8. Instalación ==

<blockquote>El planteamiento actual es '''instalar siempre de cero''' (no entregar una imagen de máquina virtual), porque el '''nombre del host está en multitud de sitios''' (incluidos nombres de fichero) y reescribirlo en una imagen sería más complejo. Si en el futuro hubiera muchas instalaciones, podría replantearse.</blockquote>

=== 8.1. Prerrequisitos y orden ===

# Obtener la '''IP pública''' y darla de alta en '''DNS''' (lo hace el cliente o nosotros, según de quién sea el dominio). Sin nombre DNS no se puede instalar (se necesita para el certificado).
# Instalar '''Nginx''' y '''Certbot''', obtener el '''certificado''' y crear el '''firewall''' (nftables).
# Instalar '''Meet''' mediante la lista de paquetes homologados (<code style="background:none; border:none; padding:0;">apt install <paquete></code>, uno a uno). '''No se instala el repositorio de Jitsi''', sino paquetes concretos y homologados.
# La instalación de Meet '''modifica la configuración de Nginx y de Prosody''', así que tras instalarlo hay que '''reajustar''' ambos. (La configuración que deja Meet por defecto no sirve.) El proceso requiere iterar y reconfigurar varias veces.
# Sustituir el '''contenido estático''' (ver §8.2).
# Rellenar <code style="background:none; border:none; padding:0;">videocan.conf</code>, instalar el demonio, configurar el JWT en Prosody y '''firmar''' (ver §9).

<blockquote>Detalle de <code style="background:none; border:none; padding:0;">apt</code>: para instalar un <code style="background:none; border:none; padding:0;">.deb</code> local hay que indicar una ruta de directorio; por eso se usa <code style="background:none; border:none; padding:0;">apt install ./paquete.deb</code> (con <code style="background:none; border:none; padding:0;">./</code>). Se usa <code style="background:none; border:none; padding:0;">apt install</code> en lugar de <code style="background:none; border:none; padding:0;">dpkg -i</code> porque '''resuelve dependencias'''.</blockquote>

Existe un '''punto intermedio de validación''' muy útil: cuando todo funciona '''sin autenticación''', cualquiera que conozca el nombre de sala entra directamente. Si <code style="background:none; border:none; padding:0;">host/pepito</code> permite que varios se conecten a la sala "pepito" sin autenticar, la instalación base está correcta. A partir de ahí se valida el resto tirando de logs y de la herramienta <code style="background:none; border:none; padding:0;">jitsi-debug</code> (sección ''Health'').

=== 8.2. Contenido estático (carteles y personalización) ===

* Jitsi instala un directorio de contenido estático en <code style="background:none; border:none; padding:0;">/usr/share/jitsi-meet/…</code>. Videocan '''lo reemplaza entero''' por uno propio (logos, fondos, textos "Vybite Meet"). Ese directorio propio es '''igual para todas las instalaciones''' (no se configura nada en él).
* Los '''carteles''' (textos de interfaz) están en <code style="background:none; border:none; padding:0;">/usr/share/jitsi-meet/lang/</code>:
** <code style="background:none; border:none; padding:0;">main.json</code> → inglés (suele estar bien, retocado para sustituir "Jitsi" por "Vybite").
** <code style="background:none; border:none; padding:0;">main-es.json</code> → castellano (~1700 carteles; las traducciones por defecto son deficientes y se corrigen).
* '''No se recomienda modificar los DEB''' para empaquetar el contenido propio: como los paquetes modifican configuraciones y Meet cambia con frecuencia, no compensa.
* '''Actualizaciones (update/upgrade):''' son arriesgadas porque pueden '''reescribir los carteles''' (decenas de cambios por actualización). El procedimiento de mantenimiento de carteles consiste en comparar a tres (inglés viejo, inglés nuevo, español nuevo) con una herramienta tipo '''Meld''' o el comparador de '''Notepad++''', y trasladar los cambios manteniendo coherencia terminológica. Por eso Meet '''no se actualiza en cada release''', sino periódicamente, y solo cuando interesa (la mayoría de novedades —integración con Drive, transcripción, traducción simultánea— no se usan). La transcripción se apoya en '''Vosk''', que de momento da resultados pobres. Las actualizaciones por '''seguridad''' sí deberán contemplarse.

=== 8.3. Instalación del demonio Videocan ===

Sigue el estándar de los demonios "mdtel":
* Binario y módulo en '''<code style="background:none; border:none; padding:0;">/opt/videocan/bin/</code>''' (<code style="background:none; border:none; padding:0;">/opt/videocan/</code> como raíz; el módulo de Prosody también reside ahí).
* Arranque en '''<code style="background:none; border:none; padding:0;">/etc/init.d/</code>'''.
* Configuración en '''<code style="background:none; border:none; padding:0;">/etc/mdtel/videocan.conf</code>''' (más <code style="background:none; border:none; padding:0;">apikey_openchannel.txt</code> en el mismo árbol).
* Rotación de logs en '''<code style="background:none; border:none; padding:0;">/etc/logrotate.d/videocan</code>'''.
* Logs en '''<code style="background:none; border:none; padding:0;">/var/log/videocan/videocan.log</code>''' (el demonio corre como usuario <code style="background:none; border:none; padding:0;">videocan</code>, '''no como root''', por estar publicado en web).

=== 8.4. Instalaciones existentes (referencia) ===

* '''<code style="background:none; border:none; padding:0;">labmeetvideo.mednova.local</code>''' — instalación interna (sin Certbot, no publicada).
* '''<code style="background:none; border:none; padding:0;">mdtel.videocan01.vybite.es</code>''' — instalación con IP pública (en Soax), para el centro de servicios de pruebas/demos.

----

== 9. Firma de licencia y tokens ==

El <code style="background:none; border:none; padding:0;">videocan.conf</code> debe estar protegido para que '''no se pueda manipular''' (por ejemplo, cambiar el número de canales a 2000). Esa protección es la '''firma electrónica''', que usa el '''mismo procedimiento y los mismos certificados que Vybite'''.

=== 9.1. Qué se protege ===

La firma cubre '''tres''' valores:
# '''Número de servicios''' (no su contenido: se pueden modificar libremente, pero no crear más de los firmados).
# '''Número de canales.'''
# '''host''' (dominio) — para que no se pueda instalar en muchos sitios con la misma licencia.

=== 9.2. Tokens ===

* Los '''tokens''' y el '''<code style="background:none; border:none; padding:0;">JWT_SECRET</code>''' hacen que cada instalación sea '''distinta'''. La herramienta de firma puede regenerarlos (claves particulares aleatorias por instalación).
* El '''token de servicio''' debe '''coincidir''' con lo que conoce la '''aplicación de usuario''' del otro lado. Por eso, cuando se regeneran tokens, hay que revisar las URLs de acceso y, en su caso, tocar la página web que se entrega al cliente (p. ej. en FAPS, el token lo tenemos nosotros, así que se ajusta en la página web alojada en esta máquina).
* El '''<code style="background:none; border:none; padding:0;">JWT_SECRET</code>''' debe configurarse en '''Prosody''' como '''<code style="background:none; border:none; padding:0;">APP_SECRET</code>''' (ver §9.4).

=== 9.3. Herramienta videocan-firmar ===

Primer parámetro = operación a realizar:

{| class="wikitable"
! Operación !! Efecto
|-
| '''Generar tokens''' || Regenera los tokens (not firma). No requiere la clave; podría delegarse al cliente.
|-
| '''Firmar''' || Generar solo la firma.
|-
| '''Generar tokens y firmar''' || Operación recomendada para todas las instalaciones.
|-
| '''Verificar''' || Indica si la firma del fichero es válida. No requiere clave (va embebida en la herramienta).
|}

Reglas:
* Siempre se indica '''el fichero de configuración''' (no se modifica el original: la herramienta entrega '''otro fichero''' ya procesado).
* Para '''firmar''' se necesita el '''fichero de clave privada (.key)'''; para '''verificar''' no se necesita nada.

Ejemplos:

<pre>
# Verificar
videocan-firmar verificar /etc/mdtel/videocan.conf
# → "La sección Videocan tiene un campo firma que no es correcto.
# Error al verificar firma de videocan.conf." (si no es válido)

# Generar tokens + firmar (recomendado)
videocan-firmar tokens-firmar mdtel.key videocan.conf
# → "Operación correcta. Se actualiza el fichero."
# Avisos: token de servicio modificado (revisar URLs de acceso),
# JWT_SECRET modificado (configurar APP_SECRET y reiniciar Prosody),
# firma del archivo modificada.
</pre>

Una verificación correcta enumera qué se está firmando (host, número de servicios, número de canales) y termina con un <code style="background:none; border:none; padding:0;">OK</code> en la '''última línea''':

<pre>
Host labmeetvideo... ok
</pre>

=== 9.4. Tras firmar ===

# Configurar '''<code style="background:none; border:none; padding:0;">APP_SECRET</code>''' en Prosody con el nuevo <code style="background:none; border:none; padding:0;">JWT_SECRET</code>. Configuración de Prosody en '''<code style="background:none; border:none; padding:0;">/etc/prosody/conf.avail/</code>''' (estructura similar a la de Nginx; el fichero incluye el nombre de dominio).
# '''Reiniciar Prosody.'''
# Revisar las '''URLs de acceso''' afectadas por el cambio de tokens de servicio.

=== 9.5. Comportamiento sin firma válida ("la bomba") ===

Si la firma '''no es válida''', el sistema '''sigue funcionando pero limitado a 1 canal''' (<code style="background:none; border:none; padding:0;">canales_max = 1</code>). El paso a 1 canal '''no ocurre en el arranque''', sino tras un tiempo indeterminado (diseñado así para dificultar su localización en el código). Esto permite, en la práctica, '''hacer demos''': con el fichero sin firmar y configurado a 1 canal, todo funciona. El procedimiento habitual del cliente puede ser instalar primero (con tokens, para que arranque y se pueda probar) y '''entregarnos después el fichero para que lo firmemos''' con las licencias.

----

== 10. Diagnóstico y logs ==

{| class="wikitable"
! Recurso !! Uso
|-
| <code style="background:none; border:none; padding:0;">nc localhost 1132</code> || Socket de control de Videocan: canales activos, alarmas, congestión.
|-
| <code style="background:none; border:none; padding:0;">/var/log/videocan/videocan.log</code> || Log del demonio Videocan.
|-
| <code style="background:none; border:none; padding:0;">/var/log/prosody/</code> || Log de Prosody.
|-
| <code style="background:none; border:none; padding:0;">/var/log/nginx/</code> || Log de Nginx.
|-
| <code style="background:none; border:none; padding:0;">/var/log/jitsi/</code> || Log de la pila Jitsi.
|-
| <code style="background:none; border:none; padding:0;">jitsi-debug</code> (script) || Comprobación de salud de la instalación (sección ''Health'').
|-
| '''Zabbix''' (vía <code style="background:none; border:none; padding:0;">nc</code>) || Monitorización externa, especialmente de congestiones, explotando el socket <code style="background:none; border:none; padding:0;">nc</code>.
|}

----

== 11. Resumen de rutas y puertos ==

'''Rutas (convención estándar <code style="background:none; border:none; padding:0;">/etc/mdtel/</code>):'''

<pre>
/opt/videocan/bin/ # demonio Videocan + módulo
/etc/init.d/videocan # arranque
/etc/mdtel/videocan.conf # configuración principal (libconfig)
/etc/mdtel/apikey_openchannel.txt # API key de OpenChannel
/etc/mdtel-videocan/templates/ # plantillas (páginas web con JS de integración Meet)
/etc/logrotate.d/videocan # rotación de logs
/etc/prosody/conf.avail/ # configuración de Prosody (APP_SECRET)
/var/log/videocan/videocan.log # log del demonio (usuario videocan)
/usr/share/jitsi-meet/ # contenido estático (reemplazado por el propio)
/usr/share/jitsi-meet/lang/main.json # carteles inglés
/usr/share/jitsi-meet/lang/main-es.json # carteles castellano (~1700)
</pre>

'''Puertos:'''

<pre>
443/TCP Nginx (HTTPS, proxy inverso, APIs de Videocan)
10000/UDP RTP de Meet (audio/vídeo) sobre la IP pública
1132 Socket de control local de Videocan (nc localhost 1132)
</pre>

----

== 12. Limitaciones y puntos abiertos ==

* '''Solo audio y vídeo'''; sin compartición de pantalla ni chat (el chat, si se activase, debería ir por OpenChannel).
* '''Vista en móvil:''' el usuario no se ve a sí mismo al entrar (entra en vista de interlocutor, no en cuadrícula). Relevante para lengua de signos. Pendiente de resolver vía JavaScript en plantilla.
* '''Cierre de la interacción OpenChannel:''' confirmar con el equipo de OmniSuite si debe ser automático o manual.
* '''Transcripción (Vosk):''' calidad pobre; no apta de momento.
* '''Actualizaciones de Meet:''' arriesgadas por los carteles; solo cuando interese o por seguridad.
* '''Requiere IP pública dedicada''' por máquina (a día de hoy).
* '''Validación de la instalación completa''' sobre máquina estándar de producción: pendiente de cerrar.
* Un '''Vybite Meet''' de cliente '''no''' sirve para este servicio (instalaciones distintas).

= Notas tomadas =

== Maquina genérica ==
* '''Debian 13'''
* '''nginx'''
* '''certbot'''
* '''prosody'''
* No hay Mariadb/Mysql
* Para montar el meet habrá un procedimiento que nos dará Antonio

== Diferencias con un VIVAit Meet "standard" ==
* '''Autenticación:''' VIVAit Meet autentica con credenciales con LDAP o BBDD VIVAit; aquí no hay LDAP ni usuarios. En la URL que llega del chat de la URL de videocan llega un Token. Con esa URL, cuando se conecta el agente, se autentica usando JWT y ya entra autenticado como moderador.
* '''Carteles'''

== Consideraciones de arquitectura ==
* '''No se entrega máquina virtual, siempre se instalará:''' Por ejemplo, el nombre de host está en una cantidad de sitios tan grande que es inmanejable de otra forma.
* '''Nodo dedicado:''' Siempre instalado en un nodo entero; no es compatible con Asterisk (ambos usan el puerto 10000).
* '''Red:''' Requiere una IP Pública entera (puede ser Nateada).
* '''Exclusividad:''' No es compatible con "otro meet" que pudiera haber en el cliente.

== Desarrollos ==
* '''Módulo mod en prosody'''
* '''Videocan (Demonio):''' Proporciona APIs:
** API de conexión de cliente
** API de conexión de Agente
** API contra prosody (control de canales)
* '''Aplicación para firmar (videoCanFirmar):''' Usa la clave privada habitual.
** Se le pasa un fichero <code>videoCan.conf</code> y devuelve otro modificado (no lo machaca).
** Puede generar firma, <code>jwt_secret</code> (para prosody) y tokens (para la conexión desde el lado cliente a URL de videoCan para el servicio).
* '''Plantilla:''' Cuando se invoca a una URL de videocan, la página que se le devuelve es una plantilla. Personalizan aspectos "del meet", reciben parámetros, etc.
* Cuando invocamos a <code>openchannel</code> desde videocan también existe una plantilla para "lo que le entra al agente".
* '''Plantillas:''' Tienen Javascript.

== Proceso de instalación ==
* Pendiente del detalle.
* Configurar prosody (seguramente solo cambiar nombre de host).
* Modificar el JWT.
* Reconfigurar varias veces NGINX y meet.
* Puntos intermedios de prueba en los que se puede probar vídeo (sin autenticación).
* '''Importante:''' Ir viendo logs en todo el proceso.

== Seguridad ==
=== Medidas de protección ===
* '''Nftables'''
* '''Fail2ban:''' Manejamos el nginx y el mcan.
* '''Firmas de control:''' Firmamos una cadena que contiene los valores que nos interesa proteger para poder tener distribución y que, por ejemplo, no nos amplíen el número de canales. Protegemos:
** Número de servicios
** Número de canales
** Host
* '''Actualizaciones (por seguridad):''' <code>update</code>/<code>upgrade</code>, y cuando saquemos actualizaciones de meet o videocan.

== Configuraciones ==
* Hay un fichero guía de instalación / cuestionario a cliente.
* <code>videoCan.conf</code>

== Diagnósticos ==
=== Videocan ===
* Comando de diagnóstico:
: <code>nc localhost 1132</code>
* Rutas de logs principales:
: <code>/var/log/videoCan/videoCan.log</code>
: <code>/var/log/nginx</code> (Típicos de nginx)
: <code>/var/log/prosody</code>
: <code>/var/log/jitsi</code>
* Monitoreo: '''Zabbix''' (explotando el comando "nc").

MediaWiki:Sidebar

2026-07-13T08:23:04Z

Alfredo.rodriguez:

**mainpage|mainpage-description

* Usuario
** Documentación de usuario VIVAit Call|VIVAit Call
** Documentacion de usuario VIVAit Suite|VIVAit Suite
** Documentacion de usuario VIVAit Alert|VIVAit Alert


* Administrador
** Arquitectura VIVAit|Arquitectura
** Release Notes|Release Notes
** Funcionalidades | Funcionalidades
** Portales de administración VIVAit |Portales de administración
** Preguntas frecuentes administración | Preguntas frecuentes

* Servicio técnico
** Manuales de instalación|Instalación
** Actualización|Actualización
** Manuales de operación plataforma VIVAit |Manuales de operación
** Terminales homologados en VIVAit | Terminales
** Hylafax + IAXmodem en VIVAit Call| Solución de fax para VIVAit Call
** Howtos| Howtos
** Formación| Formación
** Incidencias| Incidencias
** Base de datos| Base de datos

* Desarrollo
** APIs integracion|API's de integración
** Kit argumentarios|Desarrollo de argumentarios

* vFlow
** Manual de operación de vFlow|Operación
** Portal de administración de vFlow|Administración

* Omnisuite
** RecordOmni|Mejora grabaciones
** Manual de operación de vFlow | Integración vflow (punto 6)
** Omnisuite STT y TTS | STT y TTS
** Omnisuite_videoCan | Módulo de vídeo en Omnisuite (VideoCan)

* VIVAit Fax
** Documentación de usuario VIVAit Fax|Usuario
** Arquitectura VIVAit Fax|Arquitectura
** Instalación VIVAit Fax|Instalación
** Documentacion técnica|Servicio Técnico

* Cartelia
** Instalacion_cartelia | Instalacion de cartelia
** Operacion_cartelia | Operacion de cartelia

* Roadmap
** Proyectos en desarrollo|Proyectos en desarrollo

Instalacion cartelia

2026-07-13T08:21:03Z

Alfredo.rodriguez: Página creada con «== Manual de instalación de cartelia 1.0 ==»

== Manual de instalación de cartelia 1.0 ==

MediaWiki:Sidebar

2026-07-13T08:19:12Z

Alfredo.rodriguez:

**mainpage|mainpage-description

* Usuario
** Documentación de usuario VIVAit Call|VIVAit Call
** Documentacion de usuario VIVAit Suite|VIVAit Suite
** Documentacion de usuario VIVAit Alert|VIVAit Alert


* Administrador
** Arquitectura VIVAit|Arquitectura
** Release Notes|Release Notes
** Funcionalidades | Funcionalidades
** Portales de administración VIVAit |Portales de administración
** Preguntas frecuentes administración | Preguntas frecuentes

* Servicio técnico
** Manuales de instalación|Instalación
** Actualización|Actualización
** Manuales de operación plataforma VIVAit |Manuales de operación
** Terminales homologados en VIVAit | Terminales
** Hylafax + IAXmodem en VIVAit Call| Solución de fax para VIVAit Call
** Howtos| Howtos
** Formación| Formación
** Incidencias| Incidencias
** Base de datos| Base de datos

* Desarrollo
** APIs integracion|API's de integración
** Kit argumentarios|Desarrollo de argumentarios

* vFlow
** Manual de operación de vFlow|Operación
** Portal de administración de vFlow|Administración

* Omnisuite
** RecordOmni|Mejora grabaciones
** Manual de operación de vFlow | Integración vflow (punto 6)
** Omnisuite STT y TTS | STT y TTS

* VIVAit Fax
** Documentación de usuario VIVAit Fax|Usuario
** Arquitectura VIVAit Fax|Arquitectura
** Instalación VIVAit Fax|Instalación
** Documentacion técnica|Servicio Técnico

* Cartelia
** Instalacion_cartelia | Instalacion de cartelia
** Operacion_cartelia | Operacion de cartelia

* Roadmap
** Proyectos en desarrollo|Proyectos en desarrollo

Manual de operación de vFlow

2026-07-07T10:09:47Z

Alfredo.rodriguez: /* Gestión en vFlow */

== Descripción general vFlow ==

vFlow es un módulo de conexión a sistemas de inteligencia artifical para sistemas de comunicaciones unificadas, ya sean sistemas corporativos o contact center
Gracias a vFlow, las plataformas de UC dispondrán de una solución para comunicarse con sistemas IA utilizando un mismo mecanismo independientemente de la solución de inteligencia artificial que se utilice

Para proporcionar el servicio de manera completa, vFlow (en concreto el orquestador) se conectará a sistemas de inteligencia artificial (LLM) que permitirán desarrollar los agentes definidos en los orquestadores

'''Conceptos:'''
* Plataforma<span style="margin-left: 3em;"></span>--> Plataforma de comunicaciones unificadas; por ejemplo Omnisuite o VIVAit Call
* Orquestador<span style="margin-left: 3em;"></span>--> Plataforma agéntica de IA (por ejemplo Flowise)
* vFlowProxy<span style="margin-left: 3em;"></span>--> Módulo VIVAit que conecta multiples plataformas con múltiples orquestadores
* LLM<span style="margin-left: 3em;"></span>--> Modelo de lenguaje natural que usará un orquestadores
* Agente<span style="margin-left: 3em;"></span>--> Cada uno de los flujos creados en vFlow; corresponde a un par plataforma/agentflow de orquestador
* Servicio<span style="margin-left: 3em;"></span>--> Cada elemento de negocio en la plataforma de CU (por ejemplo VDN)

[[Archivo:Arquitectura Vflow - v2.jpg|1400px|center|Arquitecura de vFlow]]

Los '''módulos principales''' de vFlow son:
* vFlowProxy: Recibe las conexiones de los sistemas de comunicaciones unificadas, y conecta con los orquestadores de Inteligencia Artificial de manera segura y adaptada al tipo de servicio; el acceso a vFlow Proxy desde las plataformas se realizará mediante:
* Programa cliente: Se utiliza en el sistema de comunicaciones unificadas (actualmente VIVAit Call y Omnsisuite) para invocar a vFlow
* API REST: Alternativa al programa cliente, vFlowProxy proporciona una API REST que facilita que cualquier plataforma pueda comunicarse mediante un procedimiento estándar y documentado
* Portal de administración vFlow: Permite visualizar las interaciones realizadas y configurar el sistema
* Orquestador de IA: Herramienta de Inteligencia Artificial que permitirá la creación de aplicaciones personalizadas (agentes)
<br>
'''Otros elementos''' relevantes serán:
* Base de datos vFlow:
:* Almacena información sobre sesiones y transacciones realizadas
:* Almacena información de configuración sobre vFlow
:* Gestiona el RAG de las inteligencias artificiales a usar

== Puesta en marcha de nodo vFlow ==
<br>

Existe un nodo vFlow en los repositorios habituales proporcionados

<br>

Para '''dar de alta nodo vflow en un cliente''' hay que:
* Configurar IP (por defecto la maquina va configurada por DHCP)
* Adaptar el firewall, para ello REVISAR el fichero <code>/etc/firewall/vars.sh</code>
* Certificados validos en apache
* REVISAR ficheros <code>/etc/apache2/sites-enabled/flowise.conf</code> y <code>/etc/apache2/sites-enabled/vFlow.conf</code> la variable <code>ServerName</code> (nombre valido de la maquina)
<br>

'''Accesos vFlow''' (se debe cambiar tras instalación):
* Usuario ssh y de SO por defecto es sat y clave a proporcionar.
* Para el portal de flowise las credenciales son usuario: vfloadmin@vflow.com clave: A proporcionar
* Para el portal de vflow las credenciales son usaurio sat y clave a proporcionar.
<br>

'''Accesos BBDD vFlow'''
* Para acceder a la base de datos desde el workbenck solo desde localhost (o tunel):
* BBDD Vlfow (admin) vflowadmin // clave a proporcionar
* BBDD Vlfow (no_admin) vflow // clave a proporcionar
<br>

'''Portal orquestador Flowise'''

ubicado en https://host.cliente.xx:4567

<br>
<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
'''⚠️ ATENCION !!'''
'''Los cambios en tablas de configuración de BBDD de vFlow (orquestadores, plataformas, agentes) requieren reinicio del servicio vFlowProxy'''
</div>

<br>

<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
/etc/init.d/vFlowProxy.service status
<br>
/etc/init.d/vFlowProxy.service stop
<br>
/etc/init.d/vFlowProxy.service start
<br>
</div>

<br>

El fichero de configuración del demonio <code>vFlowProxy</code> se encuentra en <code>/etc/MDtel/vFlowProxy.conf</code>, si bien este fichero de configuración no se modificará habitualmente (los parámetros generales de configuración de vFlowProxy se encuentran en la BBDD de vFlow)
<br>
<br>

<br>
== Procedimientos de respaldo y restauración ==

=== Respaldo ===

* Hacer backup de las bases de datosdel orquestador (flowise) y de vFlow
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_config_$(date +%F_%H%M%S).sql
<br>
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_upsert_$(date +%F_%H%M%S).sql
<br>
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vFlow > vFlow_$(date +%F_%H%M%S).sql
</div>
<br>
* Copiar:
** El directorio /opt/vFlow_flowise/.flowise
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
cp -vai /opt/vFlow_flowise/.flowise /opt/vFlow_flowise/.flowise_$(date +%F_%H%M%S)
</div>
** El directorio /opt/vFlow_flowise/archivos
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
cp -vai /opt/vFlow_flowise/archivos /opt/vFlow_flowise/archivos_$(date +%F_%H%M%S)
</div>
<br>
'''Todos los ficheros creados pueden ser movidos al destino deseado para almacenar la copia de respaldo'''

=== Restauración ===
Para restaurar, será necesario
* Importar de nuevo las dos bases de datos de flowise y la base de datos de vFlow:
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mysql -u root -p vflow_flowise_config < vflow_flowise_config_ULTIMAFECHA.sql
<br>
mysql -u root -p vflow_flowise_upsert < vflow_flowise_upsert_ULTIMAFECHA.sql
<br>
mysql -u root -p vFlow < vFlow_ULTIMAFECHA.sql
</div>
<br>
* Volver a poner las carpetas de /opt/vFlow_flowise/
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mv -vi /opt/vFlow_flowise/.flowise_ULTIMAFECHA /opt/vFlow_flowise/.flowise
<br>
mv -vi /opt/vFlow_flowise/archivos_ULTIMAFECHA /opt/vFlow_flowise/archivos
</div>
<br>
'''Las ubicaciones de los archivos a resturar pueden ser diferentes'''

== Gestión en vFlow ==
vFlow prevé la existencia de tres entornos que permita hacer una gestión segura de agentes y RAG:

* Producción
* Preproducción
* Pruebas

Para cada agente o store de RAG se podrá desplegar un entorno, dos o los tres entornos

<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
✅ '''Recomendación'''<br>
::En la mayoría de los casos con disponer de entorno de producción y preproducción tanto para agente como para RAG será suficiente
</div>
<br>
Para realizar una gestión completa en vFlow (suponiendo tres entornos y gestión de agentes y RAG), deberemos tener
<br>
[[Archivo:Gestión RAG.png|1200px|miniaturadeimagen|centro|Gestión en vFlow|link=]]
<br>

=== En orquestador (Flowise) ===
* '''<big>1.- Crear agente</big>''': Se crearán hasta '''tres agentes''' (pro/pre/pru) en función de los entornos deseados; es importante '''anotar los ID's de los agentes''' creados (se ven en la URL)
::[[Archivo:Captura de pantalla 2026-05-20 144432.png|800px|miniaturadeimagen|no|Creación de agente en orquestador flowise (uno por entorno)|link=]]
<br>
<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
✅ '''Puntos 2, 3 y 4 solo en caso de tener RAG'''</div>
<br>

* '''<big>2.- Crear store </big>''': Se crearán hasta '''tres stores''' (pro/pre/pru) en función de los entornos deseados; es importante '''anotar los ID's de los stores''' creados (se ven en la URL)
::[[Archivo:Captura de pantalla 2026-05-20 135417.png|800px|miniaturadeimagen|no|Creación de store (uno por entorno)|link=]]
<br>
* '''<big>3.- Crear loader'''</big> : Para cada loader que se desee manejar, se creará en el orquestador y en el document store, para los entornos deseados
::* Subir fichero (p.ej "ld1.txt" a <code>/var/www.html/storages/production</code> (o a <code>/staging</code> o a <code>test</code> si procede)
::::[[Archivo:Captura de pantalla 2026-05-20 135757.png|700px|miniaturadeimagen|no|Subir fichero inicial (uno por entorno)|link=]]
<br>
::* Crear loader
::::* Tipo: API loader
::::* Method: get
::::* URL : <cde>http://127.0.0.1/storages/production/nombrefich.txt</code> (o /staging /test) (formatos posibles txt, pdf, doc, docx)
::::* Splitter: Recursive character text splitter
::::* Comprobar con "preview chunks"
::::* Pulsar "process"
::::::[[Archivo:Captura de pantalla 2026-05-20 140146.png|700px|miniaturadeimagen|no|Creador loader en orquestador flowise|link=]]
<br>
::::::[[Archivo:Captura de pantalla 2026-05-20 140326.png|700px|miniaturadeimagen|no|Loader creado en orquestador flowise|link=]]
<br>
* '''<big>4.- Sincronizar chunks</big>''' en store ('''para cada entorno''')
::* En Store, more actions / Upsert All Chunks
::::[[Archivo:Captura de pantalla 2026-05-20 141118.png|700px|miniaturadeimagen|no|Upsert chunks store flowise|link=]]
<br>
::::* Embeddings: Por ejemplo OpenAI embeddings (requiere "Credential")
::::* Vector Store: Qdrant
::::::* Credential: cflow_qdrant
::::::* URL: http://localhost:6333
::::::* Qdrant Collection Name: vflow
::::* Record Manager: MySQL
::::::* Connect credential: mysql_upsert
::::::* Host: localhost
::::::* Database: vflow_flowise_upsert
::::::* Cleaun: Full
::::* Aplicar
::::::* Save config
::::::* Upsert
::::::[[Archivo:Captura de pantalla 2026-05-20 141626.png|700px|miniaturadeimagen|no|Sincronizado de store en flowise|link=]]
<br>
La siguiente imagen muestra como quedará en el orquestador (flowise) un document store de vflow con entornos de producción, reproducción y pruebas
::[[Archivo:Captura de pantalla 2026-05-20 142148.png|700px|miniaturadeimagen|no|Document store en flowise con los tres entornos (tres document stores)|link=]]
<br>
<br>

=== En flow ===
* 1.- '''<big> Crear un agente</big>''': Vincularlo a los tres agentes de orquestador (pro/pre/pru) anotados anteriormente
::::[[Archivo:Captura de pantalla 2026-05-20 143843.png|800px|miniaturadeimagen|no|Crear agente en vflow|link=]]
<br>
<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
✅ '''Puntos 2 y 3 solo en caso de tener RAG'''</div>
<br>
* 2.- '''<big>Crear un store</big>''': Vinculado a los stores de orquestador anotados anteriormente (pro/pre/pru)
::::[[Archivo:Captura de pantalla 2026-05-20 142920.png|800px|miniaturadeimagen|no|Creacion de Store en vflow|link=]]
<br>
* 3.- '''<big>Crear un loader</big>'''
::* Loader vinculado a agente de vflow
::* El sistema comprobará que el fichero ya existe en el orquestador
:: Pulsar "crear"
::::[[Archivo:Captura de pantalla 2026-05-20 143126.png|700px|miniaturadeimagen|no|Crear loader en vflow|link=]]
<br>
::::[[Archivo:Captura de pantalla 2026-05-20 143239.png|700px|miniaturadeimagen|no|Store, loader y detalle de loader|link=]]
<br>

== Diagnósticos ==
Fichero de log, en nodo vFlowProxy, para cualquier canal
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/vFlowProxy/vFlowProxy.log
</pre>
<br>
Monitorizar estado del proceso vflowProxy, en nodo vFlowProxy
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
nc localhost 1131
</pre>
<br>
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"proceso": {
"nombre": "vFlowProxy",
"version": "00.00.01",
"inicio_ts": 1771315153,
"inicio_cad": "20260217 085913",
"log_alarmas_val": 8,
"log_alarma_ultimo_ts": 1771970401,
"log_alarma_ultimo_ts_cad": "20260224 230001"
},
"diagnostico": {
"gmp": {
"msj_val": 1022,
"msj_max": 1024,
"buf_val": 1024,
"buf_max": 1024,
"tarea_val": 7,
"tarea_max": 15
},
"tiempo": {
"uptime": 716665,
"uptime_dias": 8,
"uptime_horas": 7,
"uptime_minutos": 4,
"uptime_segundos": 25
},
"wws": {
"conexiones_val": 0,
"conexiones_max_periodo": 0,
"hilos_val": 4,
"hilos_max": 4,
"wsi_cad": "sesiones=0/200"
}
},
"alarmas_nivel_max": 0,
"alarmas": []
}
</pre>
Es relevante la monitorización de sesiones <code>"wsi_cad": "sesiones=0/200"</code> (usadas/máximas)
<br>
<br>
En nodo Omnisuite, para canal voz
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
asterisk -rv | grep <callysquare_name>
</pre>
<br>
en nodo Omnisuite, para canal voz
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/xcally/<agi-combined.yyyy-mm-dd.log>
</pre>
<br>
en nodo Omnisuite, para cualquier canal
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/xcally/<routing-combined.yyyy-mm-dd.log>
</pre>

== Pruebas desde vFlow ==

En /home/sat/vFlowProxy hay scripts de prueba (se configuran en el vars.sh); para usar los scripts de prueba tendremos que tener también ".ini" en vFlow

Es útil comenzar con
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/home/sat/vFlowProxy/vFlowGetInfo.sh
</pre>
que sin parámetros adicionales confirma el correcto estado de vFlowProxy
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"app": "vFlowProxy",
"version": "00.00.01",
"sessions_opened": 0,
"sessions_limit": 200,
"sessions_sleep_timeout_s": 3600,
"alarms": 8
}
</pre>

== Integración de vFlow desde Omnisuite ==
=== Descripción general ===
En Omnisuite, la integración con vFlow, se realiza con el programa vFlowOmnisuite, que podrá ser invocado como ejecutable (más rápido, para debian), o como Python (más universal)
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; max-width: 500px; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite (OPCIÓN PREFERENTE)
/opt/omnisuite/bin/vFlowOmnisuite.py (LEGACY)
</pre>

Asociado al programa existen los siguientes ficheros de configuración (.ini):

Un '''".ini" de plataforma''' Omnisuite en vFlow --> Solo contiene uuid de la plataforma; se entrega un ".ini" a modo de ejemplo en <code>/etc/MDtel/vflow/platform.ini</code>

EJEMPLO ".INI" DE PLATAFORMA
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[uuids]
platform=1d111530-e22d-11f0-b0f2-5254008bef96
</pre>

Un '''".ini" por agente''' en vFlow --> Solo contiene uuid del agente según su identificación en vFlow ('''NO''' en un orquestador, por ejemplo flowise); se entrega un ".ini" asociado a un agente "loop" existente en Flowise <code>/etc/MDtel/vflow/agent_loop_01.ini</code>

EJEMPLO ".INI" DE AGENTE
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[uuids]
agent=1a3a1020-ea1d-11f0-b4a5-5254008bef96
</pre>

Un '''".ini" por servicio''' --> Configuración de cada servicio en Omnisuite; se entrega un ".ini" a modo de ejemplo en <code>/etc/MDtel/vflow/service.ini</code>
En cada fichero de servicio configuraremos
::* Donde está Vflow
::* Agente
::* Plataforma
::* timeout_s --> Importante, es afectado por el LLM
::* channel_text_type --> IMPORTANTE si el servicio es de texto que esté bien (vacio solo si el servicio es de texto, NO COMENTARLO)
::* environment --> production, staging, test
EJEMPLO ".INI" DE SERVICIO
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[arch_uuids]
agent=/etc/MDtel/vflow/agent_loop_01.ini
platform=/etc/MDtel/vflow/platform.ini

[vflow]
host_port=172.25.129.242:7900
timeout_s=20
# channel_type=[voice|chat|email]
channel_type=chat
# environment=[production|staging|test]
environment=production
language=es

[omnisuite]
# channel_text_type=[chat|mail|sms|whatsup]
channel_text_type=chat
service_id=vflow_service_id
service_name=vflow_service_name
</pre>
<br>

La imagen siguiente muestra el esquema de relación entre orquestador/plataforma/agente/servicio en la plataforma y en vFlow

[[Archivo:Relaciones vFlow plat orq ag serv.png|800px|miniaturadeimagen|centro|Relación orquestador-plataforma-agente-servicio|link=]]
<br>

=== Invocación ===
==== Generales ====

===== Ver configuración =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> configPrint
</pre>

Ejemplo de respuesta

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
Configuration:
agent_arch_uuid=/etc/MDtel/vflow/agent_fse_rapido.ini
agent_uuid=3487af28-1d14-11f1-803c-525400ef204c
platform_arch_uuid=/etc/MDtel/vflow/platform_labomsui.ini
platform_uuid=9a54ea74-f050-11f0-bdf1-5254008bef96

vflow_host_port=labvflow.mdnova.local
vflow_timeout_s=50
vflow_environment=production
vflow_channel_type=voice
vflow_language=es

omnisuite_channel_text_type=chat
omnisuite_service_id=287
omnisuite_service_name=desarrollo
{
"errorNum": 0,
"errorCad": "OK"
}
</pre>

===== Ver versión =====

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite version
</pre>

Ejemplo de respuesta
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
00.00.02
</pre>

==== Para canales de texto ====

Para canales de texto en Omnisuite existe un único Comando de invocación "omnisuiteText"
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> omnisuiteText <omnisuite_id> <omnisuite_websiteId> <omnisuite_createdAt> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email> <question>
</pre>

Parámetros ( Los OPCIONALES son "" si no se envía valor):

{| class="wikitable"
! Parámetro !! Obligatoriedad !! Descripción
|-
| `<config_arch>` || OBLIGATORIO || ".ini" del servicio
|-
| `<omnisuite_id>` || OBLIGATORIO || Identificativo de la interacción en Omnisuite
|-
| `<omnisuite_websiteId>` || OBLIGATORIO || Identificativo del servicio en Omnisuite (ej. website id en chat)
|-
| `<omnisuite_createdAt>` || OBLIGATORIO || Creación de la interacción
|-
| `<vflow_client_id>` || OPCIONAL || Id de cliente en Omnisuite
|-
| `<vflow_client_phone_number>` || OPCIONAL || Telf de cliente en Omnisuite
|-
| `<vflow_client_email>` || OPCIONAL || Email de cliente en Omnisuite
|-
| `<question>` || OBLIGATORIO || Texto a enviar al orquestado (p. ej. Flowise)
|}

Ejemplo de respuesta JSON

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; max-width: 400px; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "e926548d-fdcf-11f0-a793-525400ef204c",
"language": "es",
"response": "HOLA"
}
</pre>

==== Para canales de voz ====
Para canales de voz, existen comandos para "abrir sesión", "enviar texto" y "cerrar sesión"

===== Abrir sesión =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionOpen <omnisuite_UniqueId> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email>
</pre>

Parámetros (Los OPCIONALES son "" si no se envía valor):

{| class="wikitable"
! Parámetro !! Requisito !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><omnisuite_UniqueId></code> || OBLIGATORIO || Unique_ID de asterisk de la llamada en Omnisuite
|-
| <code><vflow_client_id></code> || OPCIONAL || Id de cliente en Omnisuite
|-
| <code><vflow_client_phone_number></code> || OPCIONAL || Telf de cliente en Omnisuite
|-
| <code><vflow_client_email></code> || OPCIONAL || Email de cliente en Omnisuite
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "ec73df29-f08a-11f0-a8ec-525400ef204c",
"platform_id": "146"
}
</pre>

'''El value correspondiente al key "session" deberá ser guardado en una variable para siguientes invocaciones'''

===== Enviar texto =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> textRequest <vflow_session_uuid> <question>
</pre>

Parámetros:

{| class="wikitable"
! Parámetro !! Requisito !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><vflow_session_uuid></code> || OBLIGATORIO || Variable "session" almacenada en el "sessionOpen"
|-
| <code><question></code> || OBLIGATORIO || Texto a enviar al orquestado (p. ej. Flowise) (normal, abandoned, other)
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "c6f6fad7-f6c1-11f0-a793-525400ef204c",
"language": "ES",
"response": "Cristóbal Colón."
}
</pre>

===== Cerrar sesión=====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionClose <vflow_session_uuid> <vflow_cause>
</pre>

Parámetros (Los OPCIONALES son "" si no se envía valor):
{| class="wikitable"
! Parámetro !! Estado !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><vflow_session_uuid></code> || OBLIGATORIO || Variable "session" almacenada en el "sessionOpen"
|-
| <code><vflow_cause></code> || OPCIONAL || (normal, abandoned, expired, other)
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 104,
"errorStr": "Wrong session"
}
</pre>

=== Ejemplos para omnisuite ===

==== Ejemplo de chat ====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_chat.ini" "omnisuiteText" "{{interaction.id}}" "{{account.id}}" "{{interaction.createdAt}}" "" "" "" "{{message.body}}" | jq -r '.response'
</pre>

==== Ejemplo de voz ====

[[Archivo:Imagen cally square.jpg|1024px|none|miniatura|Ejemplo de flujo de Cally Square]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_voice.ini" "sessionOpen" "{UNIQUEID}" "" "" "" | jq -r '.session' </pre>
::<small>salida del comando almacenado en variable "vflow_sessionopen_response" para su posterior uso en cally square</small>

[[Archivo:Imagen sessionopen.jpg|550px|center|miniatura|Abrir sesión en vFlow]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "textRequest" "{vflow_sessionopen_response}" "{OPENAI_WHISPER_TRANSCRIPT}" | jq -r '.response'
</pre>
::<small>la voz se ha transcrito con OpenAI, por eso se usa como parámetro {OPENAI_WHISPER_TRANSCRIPT})</small>

[[Archivo:Imagen textrequest.jpg|550px|center|miniatura|Enviar texto en vFlow]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "sessionClose" "{{vflow_sessionopen_response}}" "normal"
</pre>

[[Archivo:Imagen sessionclose.jpg|900px|center|miniatura|Cerrar sesión en vFlow]]

[[Category:tecnico]]
[[Category:VIVAit Call]]
[[Category:Omnisuite]]
[[Category:IA]]

Manual de operación de vFlow

2026-07-07T10:09:38Z

Alfredo.rodriguez: /* Gestión en vFlow */

== Descripción general vFlow ==

vFlow es un módulo de conexión a sistemas de inteligencia artifical para sistemas de comunicaciones unificadas, ya sean sistemas corporativos o contact center
Gracias a vFlow, las plataformas de UC dispondrán de una solución para comunicarse con sistemas IA utilizando un mismo mecanismo independientemente de la solución de inteligencia artificial que se utilice

Para proporcionar el servicio de manera completa, vFlow (en concreto el orquestador) se conectará a sistemas de inteligencia artificial (LLM) que permitirán desarrollar los agentes definidos en los orquestadores

'''Conceptos:'''
* Plataforma<span style="margin-left: 3em;"></span>--> Plataforma de comunicaciones unificadas; por ejemplo Omnisuite o VIVAit Call
* Orquestador<span style="margin-left: 3em;"></span>--> Plataforma agéntica de IA (por ejemplo Flowise)
* vFlowProxy<span style="margin-left: 3em;"></span>--> Módulo VIVAit que conecta multiples plataformas con múltiples orquestadores
* LLM<span style="margin-left: 3em;"></span>--> Modelo de lenguaje natural que usará un orquestadores
* Agente<span style="margin-left: 3em;"></span>--> Cada uno de los flujos creados en vFlow; corresponde a un par plataforma/agentflow de orquestador
* Servicio<span style="margin-left: 3em;"></span>--> Cada elemento de negocio en la plataforma de CU (por ejemplo VDN)

[[Archivo:Arquitectura Vflow - v2.jpg|1400px|center|Arquitecura de vFlow]]

Los '''módulos principales''' de vFlow son:
* vFlowProxy: Recibe las conexiones de los sistemas de comunicaciones unificadas, y conecta con los orquestadores de Inteligencia Artificial de manera segura y adaptada al tipo de servicio; el acceso a vFlow Proxy desde las plataformas se realizará mediante:
* Programa cliente: Se utiliza en el sistema de comunicaciones unificadas (actualmente VIVAit Call y Omnsisuite) para invocar a vFlow
* API REST: Alternativa al programa cliente, vFlowProxy proporciona una API REST que facilita que cualquier plataforma pueda comunicarse mediante un procedimiento estándar y documentado
* Portal de administración vFlow: Permite visualizar las interaciones realizadas y configurar el sistema
* Orquestador de IA: Herramienta de Inteligencia Artificial que permitirá la creación de aplicaciones personalizadas (agentes)
<br>
'''Otros elementos''' relevantes serán:
* Base de datos vFlow:
:* Almacena información sobre sesiones y transacciones realizadas
:* Almacena información de configuración sobre vFlow
:* Gestiona el RAG de las inteligencias artificiales a usar

== Puesta en marcha de nodo vFlow ==
<br>

Existe un nodo vFlow en los repositorios habituales proporcionados

<br>

Para '''dar de alta nodo vflow en un cliente''' hay que:
* Configurar IP (por defecto la maquina va configurada por DHCP)
* Adaptar el firewall, para ello REVISAR el fichero <code>/etc/firewall/vars.sh</code>
* Certificados validos en apache
* REVISAR ficheros <code>/etc/apache2/sites-enabled/flowise.conf</code> y <code>/etc/apache2/sites-enabled/vFlow.conf</code> la variable <code>ServerName</code> (nombre valido de la maquina)
<br>

'''Accesos vFlow''' (se debe cambiar tras instalación):
* Usuario ssh y de SO por defecto es sat y clave a proporcionar.
* Para el portal de flowise las credenciales son usuario: vfloadmin@vflow.com clave: A proporcionar
* Para el portal de vflow las credenciales son usaurio sat y clave a proporcionar.
<br>

'''Accesos BBDD vFlow'''
* Para acceder a la base de datos desde el workbenck solo desde localhost (o tunel):
* BBDD Vlfow (admin) vflowadmin // clave a proporcionar
* BBDD Vlfow (no_admin) vflow // clave a proporcionar
<br>

'''Portal orquestador Flowise'''

ubicado en https://host.cliente.xx:4567

<br>
<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
'''⚠️ ATENCION !!'''
'''Los cambios en tablas de configuración de BBDD de vFlow (orquestadores, plataformas, agentes) requieren reinicio del servicio vFlowProxy'''
</div>

<br>

<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
/etc/init.d/vFlowProxy.service status
<br>
/etc/init.d/vFlowProxy.service stop
<br>
/etc/init.d/vFlowProxy.service start
<br>
</div>

<br>

El fichero de configuración del demonio <code>vFlowProxy</code> se encuentra en <code>/etc/MDtel/vFlowProxy.conf</code>, si bien este fichero de configuración no se modificará habitualmente (los parámetros generales de configuración de vFlowProxy se encuentran en la BBDD de vFlow)
<br>
<br>

<br>
== Procedimientos de respaldo y restauración ==

=== Respaldo ===

* Hacer backup de las bases de datosdel orquestador (flowise) y de vFlow
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_config_$(date +%F_%H%M%S).sql
<br>
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_upsert_$(date +%F_%H%M%S).sql
<br>
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vFlow > vFlow_$(date +%F_%H%M%S).sql
</div>
<br>
* Copiar:
** El directorio /opt/vFlow_flowise/.flowise
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
cp -vai /opt/vFlow_flowise/.flowise /opt/vFlow_flowise/.flowise_$(date +%F_%H%M%S)
</div>
** El directorio /opt/vFlow_flowise/archivos
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
cp -vai /opt/vFlow_flowise/archivos /opt/vFlow_flowise/archivos_$(date +%F_%H%M%S)
</div>
<br>
'''Todos los ficheros creados pueden ser movidos al destino deseado para almacenar la copia de respaldo'''

=== Restauración ===
Para restaurar, será necesario
* Importar de nuevo las dos bases de datos de flowise y la base de datos de vFlow:
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mysql -u root -p vflow_flowise_config < vflow_flowise_config_ULTIMAFECHA.sql
<br>
mysql -u root -p vflow_flowise_upsert < vflow_flowise_upsert_ULTIMAFECHA.sql
<br>
mysql -u root -p vFlow < vFlow_ULTIMAFECHA.sql
</div>
<br>
* Volver a poner las carpetas de /opt/vFlow_flowise/
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mv -vi /opt/vFlow_flowise/.flowise_ULTIMAFECHA /opt/vFlow_flowise/.flowise
<br>
mv -vi /opt/vFlow_flowise/archivos_ULTIMAFECHA /opt/vFlow_flowise/archivos
</div>
<br>
'''Las ubicaciones de los archivos a resturar pueden ser diferentes'''

== Gestión en vFlow ==
vFlow prevé la existencia de tres entornos que permita hacer una gestión segura de agentes y RAG:

* Producción
* Preproducción
* Pruebas

Para cada agente o store de RAG se podrá desplegar un entorno, dos o los tres entornos

<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
✅ '''Recomendación'''<br>
::En la mayoría de los casos con disponer de entorno de producción y preproducción tanto para agente como para RAG será suficiente
</div>
<br>
Para realizar una gestión completa en vFlow (suponiendo tres entornos y gestión de agentes y RAG), deberemos tener
<br>
[[Archivo:Gestión RAG.png|1300px|miniaturadeimagen|centro|Gestión en vFlow|link=]]
<br>

=== En orquestador (Flowise) ===
* '''<big>1.- Crear agente</big>''': Se crearán hasta '''tres agentes''' (pro/pre/pru) en función de los entornos deseados; es importante '''anotar los ID's de los agentes''' creados (se ven en la URL)
::[[Archivo:Captura de pantalla 2026-05-20 144432.png|800px|miniaturadeimagen|no|Creación de agente en orquestador flowise (uno por entorno)|link=]]
<br>
<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
✅ '''Puntos 2, 3 y 4 solo en caso de tener RAG'''</div>
<br>

* '''<big>2.- Crear store </big>''': Se crearán hasta '''tres stores''' (pro/pre/pru) en función de los entornos deseados; es importante '''anotar los ID's de los stores''' creados (se ven en la URL)
::[[Archivo:Captura de pantalla 2026-05-20 135417.png|800px|miniaturadeimagen|no|Creación de store (uno por entorno)|link=]]
<br>
* '''<big>3.- Crear loader'''</big> : Para cada loader que se desee manejar, se creará en el orquestador y en el document store, para los entornos deseados
::* Subir fichero (p.ej "ld1.txt" a <code>/var/www.html/storages/production</code> (o a <code>/staging</code> o a <code>test</code> si procede)
::::[[Archivo:Captura de pantalla 2026-05-20 135757.png|700px|miniaturadeimagen|no|Subir fichero inicial (uno por entorno)|link=]]
<br>
::* Crear loader
::::* Tipo: API loader
::::* Method: get
::::* URL : <cde>http://127.0.0.1/storages/production/nombrefich.txt</code> (o /staging /test) (formatos posibles txt, pdf, doc, docx)
::::* Splitter: Recursive character text splitter
::::* Comprobar con "preview chunks"
::::* Pulsar "process"
::::::[[Archivo:Captura de pantalla 2026-05-20 140146.png|700px|miniaturadeimagen|no|Creador loader en orquestador flowise|link=]]
<br>
::::::[[Archivo:Captura de pantalla 2026-05-20 140326.png|700px|miniaturadeimagen|no|Loader creado en orquestador flowise|link=]]
<br>
* '''<big>4.- Sincronizar chunks</big>''' en store ('''para cada entorno''')
::* En Store, more actions / Upsert All Chunks
::::[[Archivo:Captura de pantalla 2026-05-20 141118.png|700px|miniaturadeimagen|no|Upsert chunks store flowise|link=]]
<br>
::::* Embeddings: Por ejemplo OpenAI embeddings (requiere "Credential")
::::* Vector Store: Qdrant
::::::* Credential: cflow_qdrant
::::::* URL: http://localhost:6333
::::::* Qdrant Collection Name: vflow
::::* Record Manager: MySQL
::::::* Connect credential: mysql_upsert
::::::* Host: localhost
::::::* Database: vflow_flowise_upsert
::::::* Cleaun: Full
::::* Aplicar
::::::* Save config
::::::* Upsert
::::::[[Archivo:Captura de pantalla 2026-05-20 141626.png|700px|miniaturadeimagen|no|Sincronizado de store en flowise|link=]]
<br>
La siguiente imagen muestra como quedará en el orquestador (flowise) un document store de vflow con entornos de producción, reproducción y pruebas
::[[Archivo:Captura de pantalla 2026-05-20 142148.png|700px|miniaturadeimagen|no|Document store en flowise con los tres entornos (tres document stores)|link=]]
<br>
<br>

=== En flow ===
* 1.- '''<big> Crear un agente</big>''': Vincularlo a los tres agentes de orquestador (pro/pre/pru) anotados anteriormente
::::[[Archivo:Captura de pantalla 2026-05-20 143843.png|800px|miniaturadeimagen|no|Crear agente en vflow|link=]]
<br>
<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
✅ '''Puntos 2 y 3 solo en caso de tener RAG'''</div>
<br>
* 2.- '''<big>Crear un store</big>''': Vinculado a los stores de orquestador anotados anteriormente (pro/pre/pru)
::::[[Archivo:Captura de pantalla 2026-05-20 142920.png|800px|miniaturadeimagen|no|Creacion de Store en vflow|link=]]
<br>
* 3.- '''<big>Crear un loader</big>'''
::* Loader vinculado a agente de vflow
::* El sistema comprobará que el fichero ya existe en el orquestador
:: Pulsar "crear"
::::[[Archivo:Captura de pantalla 2026-05-20 143126.png|700px|miniaturadeimagen|no|Crear loader en vflow|link=]]
<br>
::::[[Archivo:Captura de pantalla 2026-05-20 143239.png|700px|miniaturadeimagen|no|Store, loader y detalle de loader|link=]]
<br>

== Diagnósticos ==
Fichero de log, en nodo vFlowProxy, para cualquier canal
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/vFlowProxy/vFlowProxy.log
</pre>
<br>
Monitorizar estado del proceso vflowProxy, en nodo vFlowProxy
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
nc localhost 1131
</pre>
<br>
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"proceso": {
"nombre": "vFlowProxy",
"version": "00.00.01",
"inicio_ts": 1771315153,
"inicio_cad": "20260217 085913",
"log_alarmas_val": 8,
"log_alarma_ultimo_ts": 1771970401,
"log_alarma_ultimo_ts_cad": "20260224 230001"
},
"diagnostico": {
"gmp": {
"msj_val": 1022,
"msj_max": 1024,
"buf_val": 1024,
"buf_max": 1024,
"tarea_val": 7,
"tarea_max": 15
},
"tiempo": {
"uptime": 716665,
"uptime_dias": 8,
"uptime_horas": 7,
"uptime_minutos": 4,
"uptime_segundos": 25
},
"wws": {
"conexiones_val": 0,
"conexiones_max_periodo": 0,
"hilos_val": 4,
"hilos_max": 4,
"wsi_cad": "sesiones=0/200"
}
},
"alarmas_nivel_max": 0,
"alarmas": []
}
</pre>
Es relevante la monitorización de sesiones <code>"wsi_cad": "sesiones=0/200"</code> (usadas/máximas)
<br>
<br>
En nodo Omnisuite, para canal voz
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
asterisk -rv | grep <callysquare_name>
</pre>
<br>
en nodo Omnisuite, para canal voz
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/xcally/<agi-combined.yyyy-mm-dd.log>
</pre>
<br>
en nodo Omnisuite, para cualquier canal
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/xcally/<routing-combined.yyyy-mm-dd.log>
</pre>

== Pruebas desde vFlow ==

En /home/sat/vFlowProxy hay scripts de prueba (se configuran en el vars.sh); para usar los scripts de prueba tendremos que tener también ".ini" en vFlow

Es útil comenzar con
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/home/sat/vFlowProxy/vFlowGetInfo.sh
</pre>
que sin parámetros adicionales confirma el correcto estado de vFlowProxy
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"app": "vFlowProxy",
"version": "00.00.01",
"sessions_opened": 0,
"sessions_limit": 200,
"sessions_sleep_timeout_s": 3600,
"alarms": 8
}
</pre>

== Integración de vFlow desde Omnisuite ==
=== Descripción general ===
En Omnisuite, la integración con vFlow, se realiza con el programa vFlowOmnisuite, que podrá ser invocado como ejecutable (más rápido, para debian), o como Python (más universal)
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; max-width: 500px; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite (OPCIÓN PREFERENTE)
/opt/omnisuite/bin/vFlowOmnisuite.py (LEGACY)
</pre>

Asociado al programa existen los siguientes ficheros de configuración (.ini):

Un '''".ini" de plataforma''' Omnisuite en vFlow --> Solo contiene uuid de la plataforma; se entrega un ".ini" a modo de ejemplo en <code>/etc/MDtel/vflow/platform.ini</code>

EJEMPLO ".INI" DE PLATAFORMA
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[uuids]
platform=1d111530-e22d-11f0-b0f2-5254008bef96
</pre>

Un '''".ini" por agente''' en vFlow --> Solo contiene uuid del agente según su identificación en vFlow ('''NO''' en un orquestador, por ejemplo flowise); se entrega un ".ini" asociado a un agente "loop" existente en Flowise <code>/etc/MDtel/vflow/agent_loop_01.ini</code>

EJEMPLO ".INI" DE AGENTE
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[uuids]
agent=1a3a1020-ea1d-11f0-b4a5-5254008bef96
</pre>

Un '''".ini" por servicio''' --> Configuración de cada servicio en Omnisuite; se entrega un ".ini" a modo de ejemplo en <code>/etc/MDtel/vflow/service.ini</code>
En cada fichero de servicio configuraremos
::* Donde está Vflow
::* Agente
::* Plataforma
::* timeout_s --> Importante, es afectado por el LLM
::* channel_text_type --> IMPORTANTE si el servicio es de texto que esté bien (vacio solo si el servicio es de texto, NO COMENTARLO)
::* environment --> production, staging, test
EJEMPLO ".INI" DE SERVICIO
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[arch_uuids]
agent=/etc/MDtel/vflow/agent_loop_01.ini
platform=/etc/MDtel/vflow/platform.ini

[vflow]
host_port=172.25.129.242:7900
timeout_s=20
# channel_type=[voice|chat|email]
channel_type=chat
# environment=[production|staging|test]
environment=production
language=es

[omnisuite]
# channel_text_type=[chat|mail|sms|whatsup]
channel_text_type=chat
service_id=vflow_service_id
service_name=vflow_service_name
</pre>
<br>

La imagen siguiente muestra el esquema de relación entre orquestador/plataforma/agente/servicio en la plataforma y en vFlow

[[Archivo:Relaciones vFlow plat orq ag serv.png|800px|miniaturadeimagen|centro|Relación orquestador-plataforma-agente-servicio|link=]]
<br>

=== Invocación ===
==== Generales ====

===== Ver configuración =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> configPrint
</pre>

Ejemplo de respuesta

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
Configuration:
agent_arch_uuid=/etc/MDtel/vflow/agent_fse_rapido.ini
agent_uuid=3487af28-1d14-11f1-803c-525400ef204c
platform_arch_uuid=/etc/MDtel/vflow/platform_labomsui.ini
platform_uuid=9a54ea74-f050-11f0-bdf1-5254008bef96

vflow_host_port=labvflow.mdnova.local
vflow_timeout_s=50
vflow_environment=production
vflow_channel_type=voice
vflow_language=es

omnisuite_channel_text_type=chat
omnisuite_service_id=287
omnisuite_service_name=desarrollo
{
"errorNum": 0,
"errorCad": "OK"
}
</pre>

===== Ver versión =====

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite version
</pre>

Ejemplo de respuesta
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
00.00.02
</pre>

==== Para canales de texto ====

Para canales de texto en Omnisuite existe un único Comando de invocación "omnisuiteText"
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> omnisuiteText <omnisuite_id> <omnisuite_websiteId> <omnisuite_createdAt> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email> <question>
</pre>

Parámetros ( Los OPCIONALES son "" si no se envía valor):

{| class="wikitable"
! Parámetro !! Obligatoriedad !! Descripción
|-
| `<config_arch>` || OBLIGATORIO || ".ini" del servicio
|-
| `<omnisuite_id>` || OBLIGATORIO || Identificativo de la interacción en Omnisuite
|-
| `<omnisuite_websiteId>` || OBLIGATORIO || Identificativo del servicio en Omnisuite (ej. website id en chat)
|-
| `<omnisuite_createdAt>` || OBLIGATORIO || Creación de la interacción
|-
| `<vflow_client_id>` || OPCIONAL || Id de cliente en Omnisuite
|-
| `<vflow_client_phone_number>` || OPCIONAL || Telf de cliente en Omnisuite
|-
| `<vflow_client_email>` || OPCIONAL || Email de cliente en Omnisuite
|-
| `<question>` || OBLIGATORIO || Texto a enviar al orquestado (p. ej. Flowise)
|}

Ejemplo de respuesta JSON

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; max-width: 400px; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "e926548d-fdcf-11f0-a793-525400ef204c",
"language": "es",
"response": "HOLA"
}
</pre>

==== Para canales de voz ====
Para canales de voz, existen comandos para "abrir sesión", "enviar texto" y "cerrar sesión"

===== Abrir sesión =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionOpen <omnisuite_UniqueId> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email>
</pre>

Parámetros (Los OPCIONALES son "" si no se envía valor):

{| class="wikitable"
! Parámetro !! Requisito !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><omnisuite_UniqueId></code> || OBLIGATORIO || Unique_ID de asterisk de la llamada en Omnisuite
|-
| <code><vflow_client_id></code> || OPCIONAL || Id de cliente en Omnisuite
|-
| <code><vflow_client_phone_number></code> || OPCIONAL || Telf de cliente en Omnisuite
|-
| <code><vflow_client_email></code> || OPCIONAL || Email de cliente en Omnisuite
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "ec73df29-f08a-11f0-a8ec-525400ef204c",
"platform_id": "146"
}
</pre>

'''El value correspondiente al key "session" deberá ser guardado en una variable para siguientes invocaciones'''

===== Enviar texto =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> textRequest <vflow_session_uuid> <question>
</pre>

Parámetros:

{| class="wikitable"
! Parámetro !! Requisito !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><vflow_session_uuid></code> || OBLIGATORIO || Variable "session" almacenada en el "sessionOpen"
|-
| <code><question></code> || OBLIGATORIO || Texto a enviar al orquestado (p. ej. Flowise) (normal, abandoned, other)
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "c6f6fad7-f6c1-11f0-a793-525400ef204c",
"language": "ES",
"response": "Cristóbal Colón."
}
</pre>

===== Cerrar sesión=====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionClose <vflow_session_uuid> <vflow_cause>
</pre>

Parámetros (Los OPCIONALES son "" si no se envía valor):
{| class="wikitable"
! Parámetro !! Estado !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><vflow_session_uuid></code> || OBLIGATORIO || Variable "session" almacenada en el "sessionOpen"
|-
| <code><vflow_cause></code> || OPCIONAL || (normal, abandoned, expired, other)
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 104,
"errorStr": "Wrong session"
}
</pre>

=== Ejemplos para omnisuite ===

==== Ejemplo de chat ====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_chat.ini" "omnisuiteText" "{{interaction.id}}" "{{account.id}}" "{{interaction.createdAt}}" "" "" "" "{{message.body}}" | jq -r '.response'
</pre>

==== Ejemplo de voz ====

[[Archivo:Imagen cally square.jpg|1024px|none|miniatura|Ejemplo de flujo de Cally Square]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_voice.ini" "sessionOpen" "{UNIQUEID}" "" "" "" | jq -r '.session' </pre>
::<small>salida del comando almacenado en variable "vflow_sessionopen_response" para su posterior uso en cally square</small>

[[Archivo:Imagen sessionopen.jpg|550px|center|miniatura|Abrir sesión en vFlow]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "textRequest" "{vflow_sessionopen_response}" "{OPENAI_WHISPER_TRANSCRIPT}" | jq -r '.response'
</pre>
::<small>la voz se ha transcrito con OpenAI, por eso se usa como parámetro {OPENAI_WHISPER_TRANSCRIPT})</small>

[[Archivo:Imagen textrequest.jpg|550px|center|miniatura|Enviar texto en vFlow]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "sessionClose" "{{vflow_sessionopen_response}}" "normal"
</pre>

[[Archivo:Imagen sessionclose.jpg|900px|center|miniatura|Cerrar sesión en vFlow]]

[[Category:tecnico]]
[[Category:VIVAit Call]]
[[Category:Omnisuite]]
[[Category:IA]]

Archivo:Gestión RAG.png

2026-07-07T10:08:53Z

Alfredo.rodriguez: Alfredo.rodriguez subió una nueva versión de Archivo:Gestión RAG.png

Gestión RAG

Manual de operación de vFlow

2026-07-07T09:59:34Z

Alfredo.rodriguez: /* Descripción general vFlow */

== Descripción general vFlow ==

vFlow es un módulo de conexión a sistemas de inteligencia artifical para sistemas de comunicaciones unificadas, ya sean sistemas corporativos o contact center
Gracias a vFlow, las plataformas de UC dispondrán de una solución para comunicarse con sistemas IA utilizando un mismo mecanismo independientemente de la solución de inteligencia artificial que se utilice

Para proporcionar el servicio de manera completa, vFlow (en concreto el orquestador) se conectará a sistemas de inteligencia artificial (LLM) que permitirán desarrollar los agentes definidos en los orquestadores

'''Conceptos:'''
* Plataforma<span style="margin-left: 3em;"></span>--> Plataforma de comunicaciones unificadas; por ejemplo Omnisuite o VIVAit Call
* Orquestador<span style="margin-left: 3em;"></span>--> Plataforma agéntica de IA (por ejemplo Flowise)
* vFlowProxy<span style="margin-left: 3em;"></span>--> Módulo VIVAit que conecta multiples plataformas con múltiples orquestadores
* LLM<span style="margin-left: 3em;"></span>--> Modelo de lenguaje natural que usará un orquestadores
* Agente<span style="margin-left: 3em;"></span>--> Cada uno de los flujos creados en vFlow; corresponde a un par plataforma/agentflow de orquestador
* Servicio<span style="margin-left: 3em;"></span>--> Cada elemento de negocio en la plataforma de CU (por ejemplo VDN)

[[Archivo:Arquitectura Vflow - v2.jpg|1400px|center|Arquitecura de vFlow]]

Los '''módulos principales''' de vFlow son:
* vFlowProxy: Recibe las conexiones de los sistemas de comunicaciones unificadas, y conecta con los orquestadores de Inteligencia Artificial de manera segura y adaptada al tipo de servicio; el acceso a vFlow Proxy desde las plataformas se realizará mediante:
* Programa cliente: Se utiliza en el sistema de comunicaciones unificadas (actualmente VIVAit Call y Omnsisuite) para invocar a vFlow
* API REST: Alternativa al programa cliente, vFlowProxy proporciona una API REST que facilita que cualquier plataforma pueda comunicarse mediante un procedimiento estándar y documentado
* Portal de administración vFlow: Permite visualizar las interaciones realizadas y configurar el sistema
* Orquestador de IA: Herramienta de Inteligencia Artificial que permitirá la creación de aplicaciones personalizadas (agentes)
<br>
'''Otros elementos''' relevantes serán:
* Base de datos vFlow:
:* Almacena información sobre sesiones y transacciones realizadas
:* Almacena información de configuración sobre vFlow
:* Gestiona el RAG de las inteligencias artificiales a usar

== Puesta en marcha de nodo vFlow ==
<br>

Existe un nodo vFlow en los repositorios habituales proporcionados

<br>

Para '''dar de alta nodo vflow en un cliente''' hay que:
* Configurar IP (por defecto la maquina va configurada por DHCP)
* Adaptar el firewall, para ello REVISAR el fichero <code>/etc/firewall/vars.sh</code>
* Certificados validos en apache
* REVISAR ficheros <code>/etc/apache2/sites-enabled/flowise.conf</code> y <code>/etc/apache2/sites-enabled/vFlow.conf</code> la variable <code>ServerName</code> (nombre valido de la maquina)
<br>

'''Accesos vFlow''' (se debe cambiar tras instalación):
* Usuario ssh y de SO por defecto es sat y clave a proporcionar.
* Para el portal de flowise las credenciales son usuario: vfloadmin@vflow.com clave: A proporcionar
* Para el portal de vflow las credenciales son usaurio sat y clave a proporcionar.
<br>

'''Accesos BBDD vFlow'''
* Para acceder a la base de datos desde el workbenck solo desde localhost (o tunel):
* BBDD Vlfow (admin) vflowadmin // clave a proporcionar
* BBDD Vlfow (no_admin) vflow // clave a proporcionar
<br>

'''Portal orquestador Flowise'''

ubicado en https://host.cliente.xx:4567

<br>
<div style="background-color: #fef6e7; border: 1px solid #fbd68a; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
'''⚠️ ATENCION !!'''
'''Los cambios en tablas de configuración de BBDD de vFlow (orquestadores, plataformas, agentes) requieren reinicio del servicio vFlowProxy'''
</div>

<br>

<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
/etc/init.d/vFlowProxy.service status
<br>
/etc/init.d/vFlowProxy.service stop
<br>
/etc/init.d/vFlowProxy.service start
<br>
</div>

<br>

El fichero de configuración del demonio <code>vFlowProxy</code> se encuentra en <code>/etc/MDtel/vFlowProxy.conf</code>, si bien este fichero de configuración no se modificará habitualmente (los parámetros generales de configuración de vFlowProxy se encuentran en la BBDD de vFlow)
<br>
<br>

<br>
== Procedimientos de respaldo y restauración ==

=== Respaldo ===

* Hacer backup de las bases de datosdel orquestador (flowise) y de vFlow
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_config_$(date +%F_%H%M%S).sql
<br>
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vflow_flowise_config > vflow_flowise_upsert_$(date +%F_%H%M%S).sql
<br>
mariadb-dump -u root -p --single-transaction --routines --events --triggers --default-character-set=utf8mb4 vFlow > vFlow_$(date +%F_%H%M%S).sql
</div>
<br>
* Copiar:
** El directorio /opt/vFlow_flowise/.flowise
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
cp -vai /opt/vFlow_flowise/.flowise /opt/vFlow_flowise/.flowise_$(date +%F_%H%M%S)
</div>
** El directorio /opt/vFlow_flowise/archivos
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
cp -vai /opt/vFlow_flowise/archivos /opt/vFlow_flowise/archivos_$(date +%F_%H%M%S)
</div>
<br>
'''Todos los ficheros creados pueden ser movidos al destino deseado para almacenar la copia de respaldo'''

=== Restauración ===
Para restaurar, será necesario
* Importar de nuevo las dos bases de datos de flowise y la base de datos de vFlow:
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mysql -u root -p vflow_flowise_config < vflow_flowise_config_ULTIMAFECHA.sql
<br>
mysql -u root -p vflow_flowise_upsert < vflow_flowise_upsert_ULTIMAFECHA.sql
<br>
mysql -u root -p vFlow < vFlow_ULTIMAFECHA.sql
</div>
<br>
* Volver a poner las carpetas de /opt/vFlow_flowise/
<div style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', 'Monaco', 'Courier New', monospace;">
mv -vi /opt/vFlow_flowise/.flowise_ULTIMAFECHA /opt/vFlow_flowise/.flowise
<br>
mv -vi /opt/vFlow_flowise/archivos_ULTIMAFECHA /opt/vFlow_flowise/archivos
</div>
<br>
'''Las ubicaciones de los archivos a resturar pueden ser diferentes'''

== Gestión en vFlow ==
vFlow prevé la existencia de tres entornos que permita hacer una gestión segura de agentes y RAG:

* Producción
* Preproducción
* Pruebas

Para cada agente o store de RAG se podrá desplegar un entorno, dos o los tres entornos

<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 0px">
✅ '''Recomendación'''<br>
::En la mayoría de los casos con disponer de entorno de producción y preproducción tanto para agente como para RAG será suficiente
</div>
<br>
Para realizar una gestión completa en vFlow (suponiendo tres entornos y gestión de agentes y RAG), deberemos tener
<br>
[[Archivo:Gestión RAG.png|1000px|miniaturadeimagen|centro|Gestión en vFlow|link=]]
<br>

=== En orquestador (Flowise) ===
* '''<big>1.- Crear agente</big>''': Se crearán hasta '''tres agentes''' (pro/pre/pru) en función de los entornos deseados; es importante '''anotar los ID's de los agentes''' creados (se ven en la URL)
::[[Archivo:Captura de pantalla 2026-05-20 144432.png|800px|miniaturadeimagen|no|Creación de agente en orquestador flowise (uno por entorno)|link=]]
<br>
<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
✅ '''Puntos 2, 3 y 4 solo en caso de tener RAG'''</div>
<br>

* '''<big>2.- Crear store </big>''': Se crearán hasta '''tres stores''' (pro/pre/pru) en función de los entornos deseados; es importante '''anotar los ID's de los stores''' creados (se ven en la URL)
::[[Archivo:Captura de pantalla 2026-05-20 135417.png|800px|miniaturadeimagen|no|Creación de store (uno por entorno)|link=]]
<br>
* '''<big>3.- Crear loader'''</big> : Para cada loader que se desee manejar, se creará en el orquestador y en el document store, para los entornos deseados
::* Subir fichero (p.ej "ld1.txt" a <code>/var/www.html/storages/production</code> (o a <code>/staging</code> o a <code>test</code> si procede)
::::[[Archivo:Captura de pantalla 2026-05-20 135757.png|700px|miniaturadeimagen|no|Subir fichero inicial (uno por entorno)|link=]]
<br>
::* Crear loader
::::* Tipo: API loader
::::* Method: get
::::* URL : <cde>http://127.0.0.1/storages/production/nombrefich.txt</code> (o /staging /test) (formatos posibles txt, pdf, doc, docx)
::::* Splitter: Recursive character text splitter
::::* Comprobar con "preview chunks"
::::* Pulsar "process"
::::::[[Archivo:Captura de pantalla 2026-05-20 140146.png|700px|miniaturadeimagen|no|Creador loader en orquestador flowise|link=]]
<br>
::::::[[Archivo:Captura de pantalla 2026-05-20 140326.png|700px|miniaturadeimagen|no|Loader creado en orquestador flowise|link=]]
<br>
* '''<big>4.- Sincronizar chunks</big>''' en store ('''para cada entorno''')
::* En Store, more actions / Upsert All Chunks
::::[[Archivo:Captura de pantalla 2026-05-20 141118.png|700px|miniaturadeimagen|no|Upsert chunks store flowise|link=]]
<br>
::::* Embeddings: Por ejemplo OpenAI embeddings (requiere "Credential")
::::* Vector Store: Qdrant
::::::* Credential: cflow_qdrant
::::::* URL: http://localhost:6333
::::::* Qdrant Collection Name: vflow
::::* Record Manager: MySQL
::::::* Connect credential: mysql_upsert
::::::* Host: localhost
::::::* Database: vflow_flowise_upsert
::::::* Cleaun: Full
::::* Aplicar
::::::* Save config
::::::* Upsert
::::::[[Archivo:Captura de pantalla 2026-05-20 141626.png|700px|miniaturadeimagen|no|Sincronizado de store en flowise|link=]]
<br>
La siguiente imagen muestra como quedará en el orquestador (flowise) un document store de vflow con entornos de producción, reproducción y pruebas
::[[Archivo:Captura de pantalla 2026-05-20 142148.png|700px|miniaturadeimagen|no|Document store en flowise con los tres entornos (tres document stores)|link=]]
<br>
<br>

=== En flow ===
* 1.- '''<big> Crear un agente</big>''': Vincularlo a los tres agentes de orquestador (pro/pre/pru) anotados anteriormente
::::[[Archivo:Captura de pantalla 2026-05-20 143843.png|800px|miniaturadeimagen|no|Crear agente en vflow|link=]]
<br>
<div style="background-color: #f0fff4; border: 3px solid #c6f6d5; padding: 1em; border-radius: 4px;width: fit-content; margin-left: 50px">
✅ '''Puntos 2 y 3 solo en caso de tener RAG'''</div>
<br>
* 2.- '''<big>Crear un store</big>''': Vinculado a los stores de orquestador anotados anteriormente (pro/pre/pru)
::::[[Archivo:Captura de pantalla 2026-05-20 142920.png|800px|miniaturadeimagen|no|Creacion de Store en vflow|link=]]
<br>
* 3.- '''<big>Crear un loader</big>'''
::* Loader vinculado a agente de vflow
::* El sistema comprobará que el fichero ya existe en el orquestador
:: Pulsar "crear"
::::[[Archivo:Captura de pantalla 2026-05-20 143126.png|700px|miniaturadeimagen|no|Crear loader en vflow|link=]]
<br>
::::[[Archivo:Captura de pantalla 2026-05-20 143239.png|700px|miniaturadeimagen|no|Store, loader y detalle de loader|link=]]
<br>

== Diagnósticos ==
Fichero de log, en nodo vFlowProxy, para cualquier canal
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/vFlowProxy/vFlowProxy.log
</pre>
<br>
Monitorizar estado del proceso vflowProxy, en nodo vFlowProxy
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
nc localhost 1131
</pre>
<br>
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"proceso": {
"nombre": "vFlowProxy",
"version": "00.00.01",
"inicio_ts": 1771315153,
"inicio_cad": "20260217 085913",
"log_alarmas_val": 8,
"log_alarma_ultimo_ts": 1771970401,
"log_alarma_ultimo_ts_cad": "20260224 230001"
},
"diagnostico": {
"gmp": {
"msj_val": 1022,
"msj_max": 1024,
"buf_val": 1024,
"buf_max": 1024,
"tarea_val": 7,
"tarea_max": 15
},
"tiempo": {
"uptime": 716665,
"uptime_dias": 8,
"uptime_horas": 7,
"uptime_minutos": 4,
"uptime_segundos": 25
},
"wws": {
"conexiones_val": 0,
"conexiones_max_periodo": 0,
"hilos_val": 4,
"hilos_max": 4,
"wsi_cad": "sesiones=0/200"
}
},
"alarmas_nivel_max": 0,
"alarmas": []
}
</pre>
Es relevante la monitorización de sesiones <code>"wsi_cad": "sesiones=0/200"</code> (usadas/máximas)
<br>
<br>
En nodo Omnisuite, para canal voz
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
asterisk -rv | grep <callysquare_name>
</pre>
<br>
en nodo Omnisuite, para canal voz
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/xcally/<agi-combined.yyyy-mm-dd.log>
</pre>
<br>
en nodo Omnisuite, para cualquier canal
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
tail -f /var/log/xcally/<routing-combined.yyyy-mm-dd.log>
</pre>

== Pruebas desde vFlow ==

En /home/sat/vFlowProxy hay scripts de prueba (se configuran en el vars.sh); para usar los scripts de prueba tendremos que tener también ".ini" en vFlow

Es útil comenzar con
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/home/sat/vFlowProxy/vFlowGetInfo.sh
</pre>
que sin parámetros adicionales confirma el correcto estado de vFlowProxy
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"app": "vFlowProxy",
"version": "00.00.01",
"sessions_opened": 0,
"sessions_limit": 200,
"sessions_sleep_timeout_s": 3600,
"alarms": 8
}
</pre>

== Integración de vFlow desde Omnisuite ==
=== Descripción general ===
En Omnisuite, la integración con vFlow, se realiza con el programa vFlowOmnisuite, que podrá ser invocado como ejecutable (más rápido, para debian), o como Python (más universal)
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; max-width: 500px; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite (OPCIÓN PREFERENTE)
/opt/omnisuite/bin/vFlowOmnisuite.py (LEGACY)
</pre>

Asociado al programa existen los siguientes ficheros de configuración (.ini):

Un '''".ini" de plataforma''' Omnisuite en vFlow --> Solo contiene uuid de la plataforma; se entrega un ".ini" a modo de ejemplo en <code>/etc/MDtel/vflow/platform.ini</code>

EJEMPLO ".INI" DE PLATAFORMA
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[uuids]
platform=1d111530-e22d-11f0-b0f2-5254008bef96
</pre>

Un '''".ini" por agente''' en vFlow --> Solo contiene uuid del agente según su identificación en vFlow ('''NO''' en un orquestador, por ejemplo flowise); se entrega un ".ini" asociado a un agente "loop" existente en Flowise <code>/etc/MDtel/vflow/agent_loop_01.ini</code>

EJEMPLO ".INI" DE AGENTE
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[uuids]
agent=1a3a1020-ea1d-11f0-b4a5-5254008bef96
</pre>

Un '''".ini" por servicio''' --> Configuración de cada servicio en Omnisuite; se entrega un ".ini" a modo de ejemplo en <code>/etc/MDtel/vflow/service.ini</code>
En cada fichero de servicio configuraremos
::* Donde está Vflow
::* Agente
::* Plataforma
::* timeout_s --> Importante, es afectado por el LLM
::* channel_text_type --> IMPORTANTE si el servicio es de texto que esté bien (vacio solo si el servicio es de texto, NO COMENTARLO)
::* environment --> production, staging, test
EJEMPLO ".INI" DE SERVICIO
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
[arch_uuids]
agent=/etc/MDtel/vflow/agent_loop_01.ini
platform=/etc/MDtel/vflow/platform.ini

[vflow]
host_port=172.25.129.242:7900
timeout_s=20
# channel_type=[voice|chat|email]
channel_type=chat
# environment=[production|staging|test]
environment=production
language=es

[omnisuite]
# channel_text_type=[chat|mail|sms|whatsup]
channel_text_type=chat
service_id=vflow_service_id
service_name=vflow_service_name
</pre>
<br>

La imagen siguiente muestra el esquema de relación entre orquestador/plataforma/agente/servicio en la plataforma y en vFlow

[[Archivo:Relaciones vFlow plat orq ag serv.png|800px|miniaturadeimagen|centro|Relación orquestador-plataforma-agente-servicio|link=]]
<br>

=== Invocación ===
==== Generales ====

===== Ver configuración =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> configPrint
</pre>

Ejemplo de respuesta

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
Configuration:
agent_arch_uuid=/etc/MDtel/vflow/agent_fse_rapido.ini
agent_uuid=3487af28-1d14-11f1-803c-525400ef204c
platform_arch_uuid=/etc/MDtel/vflow/platform_labomsui.ini
platform_uuid=9a54ea74-f050-11f0-bdf1-5254008bef96

vflow_host_port=labvflow.mdnova.local
vflow_timeout_s=50
vflow_environment=production
vflow_channel_type=voice
vflow_language=es

omnisuite_channel_text_type=chat
omnisuite_service_id=287
omnisuite_service_name=desarrollo
{
"errorNum": 0,
"errorCad": "OK"
}
</pre>

===== Ver versión =====

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite version
</pre>

Ejemplo de respuesta
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
00.00.02
</pre>

==== Para canales de texto ====

Para canales de texto en Omnisuite existe un único Comando de invocación "omnisuiteText"
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> omnisuiteText <omnisuite_id> <omnisuite_websiteId> <omnisuite_createdAt> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email> <question>
</pre>

Parámetros ( Los OPCIONALES son "" si no se envía valor):

{| class="wikitable"
! Parámetro !! Obligatoriedad !! Descripción
|-
| `<config_arch>` || OBLIGATORIO || ".ini" del servicio
|-
| `<omnisuite_id>` || OBLIGATORIO || Identificativo de la interacción en Omnisuite
|-
| `<omnisuite_websiteId>` || OBLIGATORIO || Identificativo del servicio en Omnisuite (ej. website id en chat)
|-
| `<omnisuite_createdAt>` || OBLIGATORIO || Creación de la interacción
|-
| `<vflow_client_id>` || OPCIONAL || Id de cliente en Omnisuite
|-
| `<vflow_client_phone_number>` || OPCIONAL || Telf de cliente en Omnisuite
|-
| `<vflow_client_email>` || OPCIONAL || Email de cliente en Omnisuite
|-
| `<question>` || OBLIGATORIO || Texto a enviar al orquestado (p. ej. Flowise)
|}

Ejemplo de respuesta JSON

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; max-width: 400px; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "e926548d-fdcf-11f0-a793-525400ef204c",
"language": "es",
"response": "HOLA"
}
</pre>

==== Para canales de voz ====
Para canales de voz, existen comandos para "abrir sesión", "enviar texto" y "cerrar sesión"

===== Abrir sesión =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionOpen <omnisuite_UniqueId> <vflow_client_id> <vflow_client_phone_number> <vflow_client_email>
</pre>

Parámetros (Los OPCIONALES son "" si no se envía valor):

{| class="wikitable"
! Parámetro !! Requisito !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><omnisuite_UniqueId></code> || OBLIGATORIO || Unique_ID de asterisk de la llamada en Omnisuite
|-
| <code><vflow_client_id></code> || OPCIONAL || Id de cliente en Omnisuite
|-
| <code><vflow_client_phone_number></code> || OPCIONAL || Telf de cliente en Omnisuite
|-
| <code><vflow_client_email></code> || OPCIONAL || Email de cliente en Omnisuite
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "ec73df29-f08a-11f0-a8ec-525400ef204c",
"platform_id": "146"
}
</pre>

'''El value correspondiente al key "session" deberá ser guardado en una variable para siguientes invocaciones'''

===== Enviar texto =====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> textRequest <vflow_session_uuid> <question>
</pre>

Parámetros:

{| class="wikitable"
! Parámetro !! Requisito !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><vflow_session_uuid></code> || OBLIGATORIO || Variable "session" almacenada en el "sessionOpen"
|-
| <code><question></code> || OBLIGATORIO || Texto a enviar al orquestado (p. ej. Flowise) (normal, abandoned, other)
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 0,
"errorStr": "OK",
"session": "c6f6fad7-f6c1-11f0-a793-525400ef204c",
"language": "ES",
"response": "Cristóbal Colón."
}
</pre>

===== Cerrar sesión=====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite <config_arch> sessionClose <vflow_session_uuid> <vflow_cause>
</pre>

Parámetros (Los OPCIONALES son "" si no se envía valor):
{| class="wikitable"
! Parámetro !! Estado !! Descripción
|-
| <code><config_arch></code> || OBLIGATORIO || ".ini" del servicio
|-
| <code><vflow_session_uuid></code> || OBLIGATORIO || Variable "session" almacenada en el "sessionOpen"
|-
| <code><vflow_cause></code> || OPCIONAL || (normal, abandoned, expired, other)
|}

Ejemplo de respuesta JSON
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 50px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
{
"errorNum": 104,
"errorStr": "Wrong session"
}
</pre>

=== Ejemplos para omnisuite ===

==== Ejemplo de chat ====
<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_chat.ini" "omnisuiteText" "{{interaction.id}}" "{{account.id}}" "{{interaction.createdAt}}" "" "" "" "{{message.body}}" | jq -r '.response'
</pre>

==== Ejemplo de voz ====

[[Archivo:Imagen cally square.jpg|1024px|none|miniatura|Ejemplo de flujo de Cally Square]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_voice.ini" "sessionOpen" "{UNIQUEID}" "" "" "" | jq -r '.session' </pre>
::<small>salida del comando almacenado en variable "vflow_sessionopen_response" para su posterior uso en cally square</small>

[[Archivo:Imagen sessionopen.jpg|550px|center|miniatura|Abrir sesión en vFlow]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "textRequest" "{vflow_sessionopen_response}" "{OPENAI_WHISPER_TRANSCRIPT}" | jq -r '.response'
</pre>
::<small>la voz se ha transcrito con OpenAI, por eso se usa como parámetro {OPENAI_WHISPER_TRANSCRIPT})</small>

[[Archivo:Imagen textrequest.jpg|550px|center|miniatura|Enviar texto en vFlow]]
<br>
<br>
<br>

<pre style="background-color: #f6f8fa; border: 1px solid #d1d5da; padding: 1em; border-radius: 4px; width: fit-content; margin-left: 0px; font-family: 'Ubuntu Mono', 'Consolas', monospace; white-space: pre-wrap;">
/opt/omnisuite/bin/vFlowOmnisuite "/etc/MDtel/vflow/service_desa_voz.ini" "sessionClose" "{{vflow_sessionopen_response}}" "normal"
</pre>

[[Archivo:Imagen sessionclose.jpg|900px|center|miniatura|Cerrar sesión en vFlow]]

[[Category:tecnico]]
[[Category:VIVAit Call]]
[[Category:Omnisuite]]
[[Category:IA]]

Archivo:Arquitectura Vflow - v2.jpg

2026-07-07T09:58:18Z

Alfredo.rodriguez: Alfredo.rodriguez subió una nueva versión de Archivo:Arquitectura Vflow - v2.jpg

Arquitectura de vFlow

Howto's 5.0

2026-07-07T09:39:42Z

Alfredo.rodriguez: /* Signgle Sign On Oauth2/SAML */

== <big>Guías Prácticas versión 5.x</big> ==
<br><br>
<big>Utilizar los siguientes enlaces para descargar las guías practicas, sobre las funcionalidades indicadas en cada apartado, de la versión 5.0 de '''''VIVA'''it CALL''.</big>
<br><br>
=== Conexión con Teams ===
:<big>[[:media:Conexión Teams modelo Smart.pdf| Guía práctica para la configuración de la ''Conexión con Teams'', modelo Smart]]</big>
<br>
=== Puesta en marcha direc ===
:<big>[[:media:Puesta en marcha direc.pdf| Guía práctica para la ''Puesta en marcha de direc'']]</big>
<br>
=== Puesta en marcha SIPREC ===
:<big>[[:media:Puesta en marcha SIPREC.pdf| Guía práctica para la ''Puesta en marcha de SIPREC'']]</big>
<br>
=== Puesta en marcha TBC ===
:<big>[[:media:Puesta en marcha TBC.pdf| Guía práctica para la ''Puesta en marcha de TBC'']]</big>
<br>
=== Importación masiva de usuarios ===
:<big>[[:media:importación+masiva_V5+(2).pdf| Guía práctica para la ''Importación masiva'' de usuarios]]</big>
<br>
=== Puesta en marcha Grabación bajo demanda ===
:<big>[[:media:Grabación_bajo_demanda_V5111.pdf| Guía práctica para la ''Puesta en marcha de Grabación bajo demanda'']]</big>
<br>
=== Single Sign On Oauth2/SAML ===
:<big>[[:media:Admin_VIVAit-sso-documentacion-tecnica.pdf| Implementación ''SSO para administrador de VIVAit Call'']]</big>
:<big>[[:media:Admin MS-Integracion VIVAit con MS Teams y SSO v4.pdf| Implementación ''SSO para administrador de MICROSOFT'']]</big>
:<big>[[:media:Admin Google-Integración VIVAit con Google OAuth para SSO.pdf| Implementación ''SSO para administrador de GOOGLE'']]</big>

[[Página_principal | Volver a la Página Principal]]
<br><br>
[[Category:tecnico]]
[[Category:usuario]]
[[Category:administrador]]
[[Category:VIVAit Call]]
[[Category:IA]]

Archivo:Admin Google-Integración VIVAit con Google OAuth para SSO.pdf

2026-07-07T09:38:13Z

Alfredo.rodriguez:

Archivo:Admin MS-Integracion VIVAit con MS Teams y SSO v4.pdf

2026-07-07T09:38:00Z

Alfredo.rodriguez:

Archivo:Admin VIVAit-sso-documentacion-tecnica.pdf

2026-07-07T09:37:37Z

Alfredo.rodriguez:

Howto's 5.0

2026-07-07T09:37:11Z

Alfredo.rodriguez: /* Guías Prácticas versión 5.x */

== <big>Guías Prácticas versión 5.x</big> ==
<br><br>
<big>Utilizar los siguientes enlaces para descargar las guías practicas, sobre las funcionalidades indicadas en cada apartado, de la versión 5.0 de '''''VIVA'''it CALL''.</big>
<br><br>
=== Conexión con Teams ===
:<big>[[:media:Conexión Teams modelo Smart.pdf| Guía práctica para la configuración de la ''Conexión con Teams'', modelo Smart]]</big>
<br>
=== Puesta en marcha direc ===
:<big>[[:media:Puesta en marcha direc.pdf| Guía práctica para la ''Puesta en marcha de direc'']]</big>
<br>
=== Puesta en marcha SIPREC ===
:<big>[[:media:Puesta en marcha SIPREC.pdf| Guía práctica para la ''Puesta en marcha de SIPREC'']]</big>
<br>
=== Puesta en marcha TBC ===
:<big>[[:media:Puesta en marcha TBC.pdf| Guía práctica para la ''Puesta en marcha de TBC'']]</big>
<br>
=== Importación masiva de usuarios ===
:<big>[[:media:importación+masiva_V5+(2).pdf| Guía práctica para la ''Importación masiva'' de usuarios]]</big>
<br>
=== Puesta en marcha Grabación bajo demanda ===
:<big>[[:media:Grabación_bajo_demanda_V5111.pdf| Guía práctica para la ''Puesta en marcha de Grabación bajo demanda'']]</big>
<br>
=== Signgle Sign On Oauth2/SAML ===
:<big>[[:media:Admin_VIVAit-sso-documentacion-tecnica.pdf| Implementación ''SSO para administrador de VIVAit Call'']]</big>
:<big>[[:media:Admin MS-Integracion VIVAit con MS Teams y SSO v4.pdf| Implementación ''SSO para administrador de MICROSOFT'']]</big>
:<big>[[:media:Admin Google-Integración VIVAit con Google OAuth para SSO.pdf| Implementación ''SSO para administrador de GOOGLE'']]</big>

[[Página_principal | Volver a la Página Principal]]
<br><br>
[[Category:tecnico]]
[[Category:usuario]]
[[Category:administrador]]
[[Category:VIVAit Call]]
[[Category:IA]]

Howtos

2026-07-07T09:32:00Z

Alfredo.rodriguez:

{| class="wikitable"
|-
! '''Producto: '''!! VIVAit Call
VIVAit Suite
|-
|}
<br><br>
Utilizar los enlaces siguientes para acceder a la información sobre guías práctica en las distintas versiones de '''''VIVA'''it''.
<br><br>
::[[Howto's | <big>Guías Prácticas VIVAit</big>]]
:::Guías paso a paso de funcionalidades del sistema '''''VIVA'''''it Call / '''''VIVA'''''it Suite de '''''<span style="color:#144F9B">MD</span>'''''Tel.
<br>
::[[Howto's 5.0 | <big>Guías Prácticas especificas de VIVAit 5.x</big>]]
:::Guía paso a paso de funcionalidades espécificas para la versión 5.0 del sistema '''''VIVA'''''it Call / '''''VIVA'''''it Suite de '''''<span style="color:#144F9B">MD</span>'''''Tel.
<br><br>
[[Página_principal | Volver a la Página Principal]]
<br><br>
[[Category:tecnico]]
[[Category:usuario]]
[[Category:administrador]]
[[Category:VIVAit Call]]

Portal administracion de vFlow v01.04

2026-07-06T12:14:40Z

Alfredo.rodriguez:

== Manual de usuario — VFlow (Portal de IA) ==

<blockquote>'''Versión de la aplicación:''' v01.04.09 · © 2026 MDtel</blockquote>
----

__TOC__

=== 1. Introducción ===

'''VFlow''' es el portal de administración y analítica de los agentes de IA de MDtel. Desde una única interfaz web permite:

* Consultar '''métricas de uso''' (tokens, peticiones, sesiones y tiempos de respuesta) por modelo y periodo.
* Revisar el '''historial de peticiones''' y el '''detalle de las conversaciones''' de cada sesión.
* Gestionar la '''base de conocimiento RAG''' (almacenes de documentos y loaders).
* Administrar los componentes del sistema: '''plataformas, agentes, orquestadores, usuarios''' y '''parámetros globales'''.
* Mantener '''objetos de datos estructurados''' (Metabase de datos).

El manual recorre todas las pantallas en el orden en el que aparecen en el menú lateral.

----

=== 2. Acceso a la aplicación (Login) ===

Al abrir <code>https://labvflow/vflow</code> la aplicación redirige a la pantalla de inicio de sesión.

[[File:00-login.png|1000px|center|Pantalla de login de VFlow]]

'''Pasos para iniciar sesión:'''

# Introduce tu '''Usuario''' en el primer campo.
# Introduce tu '''Contraseña'''.
# Pulsa el botón '''Entrar'''.

<blockquote>El acceso está restringido a usuarios expresamente autorizados. Si las credenciales son incorrectas, la aplicación no permitirá el acceso y permanecerá en esta pantalla.</blockquote>

Una vez autenticado, se accede al '''Panel''' (dashboard) principal.

----

=== 3. Estructura general y menú de navegación ===

Tras iniciar sesión, la interfaz se organiza en dos zonas:

* '''Barra lateral izquierda:''' menú de navegación por iconos. Al pasar el ratón se muestra el nombre de cada sección.
* '''Área de contenido:''' muestra la pantalla de la sección seleccionada.

El menú lateral contiene las siguientes secciones (de arriba a abajo):

{| class="wikitable"
! Icono !! Sección !! Descripción
|-
| 📊 || '''Panel''' || Analítica y métricas de uso (dashboard).
|-
| 📋 || '''Peticiones''' || Historial de todas las peticiones realizadas.
|-
| 💬 || '''Sesiones''' || Historial de sesiones y detalle de conversaciones.
|-
| 🗄️ || '''Gestión RAG''' || Documentos y versiones de los almacenes RAG.
|-
| 🛡️ || '''Administración''' || Panel de administración de todos los componentes.
|-
| ⚙️ || '''Configuración''' || Ajustes de la interfaz (tema, idioma, etiquetas).
|-
| ⤺ || '''Salir''' || Cierra la sesión.
|}

En la esquina inferior izquierda se muestra siempre la '''versión''' de la aplicación (v01.04.09) y el aviso de copyright.

----

=== 4. Panel (Dashboard) ===

'''Ruta:''' <code>/vflow/dashboard</code>

Es la pantalla de inicio. Muestra el análisis y las métricas de uso del sistema.

[[File:01-dashboard.png|1000px|center|Panel de VFlow (dashboard)]]

'''Elementos de la cabecera:'''

* '''Total de tokens''', '''Total de peticiones''' y '''Chats únicos''': contadores globales del periodo seleccionado.
* '''Gráficas''' (desplegable): permite mostrar/ocultar las gráficas disponibles.
* '''Periodo''' (desplegable): filtra todas las métricas por el rango de fechas elegido.
* '''+ Añadir gráfica''': abre el asistente para crear una gráfica personalizada (ver 4.1).

'''Gráficas incluidas por defecto:'''

* '''Tokens por Modelo''' — tabla con el total de tokens consumidos por cada modelo.
* '''Evolución de Peticiones''' — evolución temporal del número de peticiones.
* '''Peticiones por Modelo''' — comparativa de peticiones por modelo.
* '''Evolución de Tokens''' — evolución temporal del consumo de tokens.
* '''Llamadas LLM por Día''', '''Tiempo de respuesta por modelo (ms)''' y '''Peticiones por hora del día''' (más abajo en la página).

Cada gráfica dispone del botón '''⚙ Configuración de Gráficos''' y de una leyenda con los modelos, donde se puede quitar un modelo pulsando la '''✕''' de su etiqueta.

==== 4.1 Añadir una gráfica personalizada ====

Al pulsar '''+ Añadir gráfica''' se abre el asistente '''Crear gráfica personalizada''':

[[File:dlg-anadir-grafica.png|1000px|center|Diálogo de creación de gráfica personalizada]]

Opciones de configuración:

* '''Nombre de la gráfica''': título que se mostrará.
* '''Fuente de datos''': origen de los datos (p. ej. ''Consumos (DAT_CONSUMOS)'').
* '''Agrupar por''': dimensión de agrupación (p. ej. ''Por Modelo'').
* '''Métrica''': valor a representar (p. ej. ''Número de llamadas'').
* '''Tipo de gráfica''': Barras, Horizontal, Línea, Área, Circular, Donut, KPI, Radar, Mapa de calor, Medidor, Histograma, Treemap o Dispersión.
* '''Color''', '''Estilo''' (mostrar leyenda, opacidad), rangos '''Y mínimo / Y máximo''' y '''Umbral de alerta'''.

A la derecha se muestra una '''Vista previa''' en tiempo real. Pulsa '''Guardar gráfica''' para añadirla al panel o '''Cancelar''' para descartar.

<blockquote>Nota: la creación de gráficas personalizadas puede estar limitada por rol (ver [[#8.5 Configuración del sistema|8.5 Configuración del sistema → Overrides por rol]]).</blockquote>

----

=== 5. Peticiones ===

'''Ruta:''' <code>/vflow/requests</code>

Muestra el '''Historial de Peticiones''': la lista completa de todas las peticiones realizadas al sistema.

[[File:02-peticiones.png|1000px|center|Historial de Peticiones]]

'''Filtros (parte superior):'''

* '''Plataformas''', '''Agentes''', '''Orquestadores''': desplegables para filtrar por cada componente.
* '''Periodo''': filtra por rango de fechas.

'''Tabla de Peticiones:'''

* Campo de '''Búsqueda''' y selector de '''Registros por página''' (10 por defecto).
* Columnas: '''Message ID''', '''ID de sesión''', '''Fecha''', '''Pregunta''' y '''Respuesta'''.
* Indicador ''"Mostrando 1 a 10 de N resultados"'' y '''paginación''' en la parte inferior.

Es la vista de referencia para auditar de forma tabular qué se preguntó, cuándo y qué respondió el agente.

----

=== 6. Sesiones ===

'''Ruta:''' <code>/vflow/conversations</code>

Muestra el '''Historial de sesiones'''. Cada sesión agrupa los mensajes de una conversación.

[[File:03-sesiones.png|1000px|center|Listado de Sesiones]]

'''Panel izquierdo (listado):'''

* Buscador '''"Buscar por ID de sesión o texto"'''.
* Botón '''Cargar más''' para paginar resultados.
* Cada tarjeta muestra: plataforma (p. ej. <code>omsui_1</code>), fecha/hora, '''agente''' e '''ID de sesión''', y el número de mensajes (<code>N msg</code>).
* Filtros superiores: '''Plataformas''', '''Agentes''', '''Orquestadores''', '''Sesiones''' y '''Periodo'''.

'''Panel derecho (detalle):''' al seleccionar una sesión se muestra la conversación completa en formato chat.

[[File:sesion-detalle.png|1000px|center|Detalle de una sesión]]

En el detalle se ven, en orden cronológico, los mensajes del '''usuario''' (a la derecha) y las respuestas del '''agente''' (a la izquierda, con el nombre del agente), junto con la cabecera de la sesión (plataforma, agente e ID).

----

=== 7. Gestión RAG ===

'''Ruta:''' <code>/vflow/rag-management</code>

Permite gestionar los documentos del sistema '''RAG''' (Retrieval-Augmented Generation), organizados por almacén (''store'').

[[File:04-gestion-rag.png|1000px|center|Gestión RAG]]

* Cada bloque corresponde a un '''RAG Store''' (p. ej. <code>ARA002</code>, <code>General</code>, <code>DS_ARA</code>) e indica su '''UUID''' y un estado ('''ACTUALIZADO''').
* Al expandir un store (flecha ▾) se muestran sus '''documentos/loaders'''. Para cada documento:
** Nombre del documento (p. ej. <code>ARA002_ld1</code>).
** '''Versión activa''' (etiqueta, p. ej. <code>v3</code>).
** Acciones: '''subir/actualizar''' (icono nube) y '''eliminar''' (icono papelera).

<blockquote>Esta pantalla es la vista operativa del contenido RAG. La definición de los stores y loaders se realiza en Administración (ver [[#8.6 RAG Stores|8.6]] y [[#8.7 RAG Loaders|8.7]]).</blockquote>

----

=== 8. Administración ===

'''Ruta:''' <code>/vflow/admin</code>

Panel central para administrar y configurar todos los componentes del sistema VFlow. Se presenta como una cuadrícula de tarjetas de acceso.

[[File:05-administracion.png|1000px|center|Panel de administración de VFlow]]

Tarjetas disponibles:

{| class="wikitable"
! Tarjeta !! Función
|-
| '''Plataformas''' || Gestión de plataformas.
|-
| '''Agentes''' || Gestión de agentes.
|-
| '''Orquestadores''' || Gestión de orquestadores.
|-
| '''Usuarios''' || Gestión de usuarios.
|-
| '''Configuración del sistema''' || Parámetros y ajustes globales.
|-
| '''RAG Stores''' || Almacenes de documentos RAG.
|-
| '''RAG Loaders''' || Loaders de documentos RAG.
|-
| '''Metabase de datos''' || Objetos, campos y registros estructurados.
|}

<blockquote>Aviso mostrado en la propia pantalla: ''"Desde este panel puedes administrar todas las configuraciones críticas del sistema VFlow. Asegúrate de tener los permisos necesarios antes de realizar cambios."''</blockquote>

En todas las subpantallas de administración el botón '''← Volver''' regresa a este panel.

==== 8.1 Plataformas ====

'''Ruta:''' <code>/vflow/admin/plataformas</code>

Listado de plataformas conectadas (p. ej. VIVAit, OmniSuite).

[[File:adm-plataformas.png|1000px|center|Listado de Plataformas]]

* Columnas: '''Nombre''', '''Identificador (UUID)''', '''Descripción''', '''Tipo''' (<code>vivait</code>, <code>omniSuite</code>…), '''Max Sesiones''' y '''Acciones''' (editar ✏️ / eliminar 🗑️).
* Botón '''+ Crear''' para dar de alta una plataforma.

'''Formulario de creación/edición:'''

[[File:dlg-plataforma.png|1000px|center|Formulario de plataforma]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Tipo''' ''(obligatorio)'': selector de tipo de plataforma.
* '''Descripción'''.
* '''Max Sesiones Abiertas''', '''Max Peticiones Simultáneas''', '''Max Peticiones/Min/Sesión''': límites de capacidad.

Pulsa '''Guardar''' para confirmar o '''Cancelar''' para descartar.

==== 8.2 Agentes ====

'''Ruta:''' <code>/vflow/admin/agentes</code>

Gestión de los agentes de IA.

[[File:adm-agentes.png|1000px|center|Listado de Agentes]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''Orquestadores''', '''IDs entorno''' (PRO / PRE / PRU) y '''Acciones'''.
* Los '''IDs entorno''' muestran el identificador del agente en cada entorno: '''PRO''' (Producción), '''PRE''' (Preproducción) y '''PRU''' (Pruebas).
* Botón '''+ Nuevo Agente'''.

'''Formulario de agente:'''

[[File:dlg-agente.png|1000px|center|Formulario de nuevo agente]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''ID Agente Producción''' ''(obligatorio)'', '''ID Agente Preproducción''', '''ID Agente Pruebas''': identificadores del agente en cada entorno.
* '''Descripción'''.
* '''Plataformas''' ''(obligatorio)'' y '''Orquestadores''' ''(obligatorio)'': selección del componente asociado.
* '''Timeout Respuesta (ms)''': tiempo máximo de espera de respuesta (30000 por defecto).

Los campos marcados con <code>*</code> son obligatorios. Pulsa '''Guardar'''.

==== 8.3 Orquestadores ====

'''Ruta:''' <code>/vflow/admin/orquestadores</code>

Gestión de los orquestadores (motores que enrutan/ejecutan las peticiones, p. ej. ''Flowise'', ''Bucle'').

[[File:adm-orquestadores.png|1000px|center|Listado de Orquestadores]]

* Columnas: '''Nombre''', '''Descripción''', '''Tipo''' (Bucle, Flowise…), '''URL Conexión''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de orquestador:'''

[[File:dlg-orquestador.png|1000px|center|Formulario de orquestador]]

Campos:

* '''Nombre''' ''(obligatorio)'' y '''Tipo''' ''(obligatorio)''.
* '''URL Conexión''' ''(obligatorio)'': endpoint del orquestador.
* '''URL Proxy (opcional)''', '''URL RAG'''.
* '''Cadena de Autenticación''': Bearer token o API Key.
* '''Usuario (opcional)''' y '''Contraseña (opcional)'''.
* '''Descripción'''.

==== 8.4 Usuarios ====

'''Ruta:''' <code>/vflow/admin/usuarios</code>

Gestión de las cuentas de usuario de VFlow.

[[File:adm-usuarios.png|1000px|center|Listado de Usuarios]]

* Columnas: '''Nombre''', '''Cuenta (login)''', '''Rol''' (Invitado, Usuario, Administrador), '''Activo''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de usuario:'''

[[File:dlg-usuario.png|1000px|center|Formulario de usuario]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Primer Apellido''', '''Segundo Apellido'''.
* '''Email''' ''(obligatorio)'', '''Móvil''', '''Cuenta (login)''' ''(obligatorio)''.
* '''Contraseña''' ''(obligatorio)''.
* '''Rol''' ''(obligatorio)'': perfil de permisos.
* '''Modo de Login''': ''Local'' (u otros modos disponibles, p. ej. SSO).

==== 8.5 Configuración del sistema ====

'''Ruta:''' <code>/vflow/admin/configuracion</code>

Parámetros y ajustes globales del sistema. Está organizada en '''pestañas'''. Los cambios se confirman con el botón '''Guardar Configuración''' (abajo a la derecha).

'''Pestaña Monitorización''' — estado general e incidencias recientes del frontend:

[[File:adm-configuracion-sistema.png|1000px|center|Configuración del sistema — Monitorización]]

Muestra tarjetas de estado: '''Estado''' (Backend disponible), '''Nivel de log''', '''Stores pendientes''', '''Histórico de sincronización''', '''Errores recientes''', '''Warnings recientes''' y '''Última comprobación'''. El botón '''Actualizar estado''' refresca los datos. Debajo se listan los ''stores pendientes'' de sincronización y el ''histórico de sincronización''.

<blockquote>Indicación en pantalla: los logs de frontend se ven en <code>F12 > Consola</code>; los del backend en <code>/opt/tomcat11/logs/catalina.out</code>.</blockquote>

'''Pestaña Tarificación:'''

[[File:cfg-tarificacion.png|1000px|center|Configuración del sistema — Tarificación]]

* '''Peticiones por Bloque a Tarificar''' y '''Segundos por Bloque a Tarificar'''.

'''Pestaña Configuración runtime''' — se guarda en <code>vflow-config.json</code> y se aplica al refrescar la aplicación:

[[File:cfg-configuracion.png|1000px|center|Configuración del sistema — Configuración runtime]]

* '''URL de la API backend''' (p. ej. <code>/vflow/api</code>): ruta que usa el frontend para llamar al backend.
* '''Tamaño de página de sesiones''': nº de sesiones por tanda en la pantalla de conversaciones.
* '''Nivel de log''': DEBUG muestra todo, ERROR solo fallos.
* '''Overrides por rol''': permite ajustar 2FA y la '''visibilidad del dashboard''' por perfil (Administrador, Invitado, Usuario), incluyendo qué gráficas ve cada rol y si puede crear gráficas personalizadas.

'''Pestaña Rutas de Archivos''' — configuradas en servidor, '''no editables''' desde la interfaz:

[[File:cfg-rutas.png|1000px|center|Configuración del sistema — Rutas de Archivos]]

* '''Ruta de Documentos''' (p. ej. <code>/etc/MDtel/vFlow/Documentos/</code>).
* '''Ruta API Loader''' (p. ej. <code>/var/www/html/storages/</code>).

'''Pestaña Timeouts de Sesión (segundos):'''

[[File:cfg-timeouts.png|1000px|center|Configuración del sistema — Timeouts de Sesión]]

* '''Dormir Sesión''', '''Sesión Voz''', '''Sesión Chat''' y '''Sesión Email''': tiempos de expiración por tipo de sesión.

==== 8.6 RAG Stores ====

'''Ruta:''' <code>/vflow/admin/rag-stores</code>

Gestión de los almacenes de documentos RAG.

[[File:adm-rag-stores.png|1000px|center|Listado de RAG Stores]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''ID Store Producción''', '''ID Store Preproducción''', '''ID Store Pruebas''' y '''Acciones'''.
* Botón '''+ Nuevo RAG Store'''.

'''Formulario de RAG Store:'''

[[File:dlg-ragstore.png|1000px|center|Formulario de RAG Store]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Plataformas''' ''(obligatorio)'', '''Orquestadores''' ''(obligatorio)''.
* '''Descripción'''.
* '''ID Store Producción''' ''(obligatorio)'', '''ID Store Preproducción''', '''ID Store Pruebas''': identificadores del Document Store en cada entorno.

==== 8.7 RAG Loaders ====

'''Ruta:''' <code>/vflow/admin/rag-loaders</code>

Gestión de los ''loaders'' (cargadores de documentos) asociados a los RAG Stores.

[[File:adm-rag-loaders.png|1000px|center|Listado de RAG Loaders]]

* Columnas: '''Nombre''', '''RAG Stores''', '''Interno (gestionado por VFlow)''', '''Configuración JSON''' y '''Acciones''' (eliminar).
* Botón '''+ Añadir loader'''.

'''Formulario de loader:'''

[[File:dlg-ragloader.png|1000px|center|Formulario de añadir loader]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Descripción'''.
* '''Nombre del archivo''' ''(obligatorio)''.
* '''Seleccione un RAG Store''' ''(obligatorio)'': store al que se asocia.
* '''Contenido detectado del archivo base''': área de texto con el contenido.

Pulsa '''Crear''' para añadirlo.

==== 8.8 Metabase de datos ====

'''Ruta:''' <code>/vflow/metadata</code>

Gestión de '''objetos de datos estructurados''' (tablas de datos que puede usar el sistema: clientes, doctores, etc.).

[[File:adm-metabase.png|1000px|center|Metabase de datos]]

* Cada tarjeta representa un '''objeto''' (p. ej. ''Clientes'', ''Doctores'') e indica su descripción, el '''JSON''' asociado y la '''Ruta'''.
* Acciones por objeto: '''Editar objeto''' (definición/estructura) y '''Editar/Ver datos''' (registros).
* Botones superiores: '''↻''' (refrescar) y '''+ Nuevo objeto'''.

'''Nuevo objeto / Editar objeto''' — define la estructura del objeto:

[[File:dlg-metaobjeto.png|1000px|center|Diálogo de nuevo objeto]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Descripción'''.
* '''Nombre del JSON''' y '''Ruta de upload'''.
* '''Campos''': definición de los campos del objeto (botón '''+ Añadir campo''').
* A la derecha se muestra una vista previa del '''JSON''' resultante.

'''Editar/Ver datos''' — gestiona los registros del objeto:

[[File:meta-ver-datos.png|1000px|center|Vista de datos de un objeto (registros)]]

* Tabla paginada con los registros y sus columnas (Id, Nombre, Fecha, Dirección, Localidad, Teléfono, Email, etc.).
* Acciones por fila: '''editar''' ✏️ y '''eliminar''' 🗑️.
* Botones superiores: '''← Volver''', '''↻''' refrescar, '''⤒ Importar''', '''Generar JSON''', '''Eliminar todo''' y '''+ Nuevo registro'''.

----

=== 9. Configuración de la interfaz ===

Al pulsar el icono '''⚙ Configuración''' de la barra lateral (parte inferior) se despliega un pequeño menú de ajustes de la interfaz:

[[File:menu-configuracion.png|1000px|center|Menú de configuración de la interfaz]]

Opciones:

* '''Tema Claro / Oscuro''': interruptor para cambiar el aspecto visual.
* '''Idioma''': selector de idioma (p. ej. '''ES''').
* '''Etiquetas de navegación''': interruptor para mostrar u ocultar los textos junto a los iconos del menú lateral.

Estos ajustes afectan únicamente a la visualización de la interfaz para el usuario actual.

----

=== 10. Salir de la aplicación ===

Para cerrar la sesión, pulsa el icono '''⤺ Salir''' situado en la parte inferior de la barra lateral. La aplicación cerrará la sesión y volverá a la pantalla de [[#2. Acceso a la aplicación (Login)|Login]].

----

=== Anexo — Rutas de la aplicación ===

{| class="wikitable"
! Sección !! Ruta
|-
| Login || <code>/vflow/login</code>
|-
| Panel || <code>/vflow/dashboard</code>
|-
| Peticiones || <code>/vflow/requests</code>
|-
| Sesiones || <code>/vflow/conversations</code>
|-
| Gestión RAG || <code>/vflow/rag-management</code>
|-
| Administración || <code>/vflow/admin</code>
|-
| Plataformas || <code>/vflow/admin/plataformas</code>
|-
| Agentes || <code>/vflow/admin/agentes</code>
|-
| Orquestadores || <code>/vflow/admin/orquestadores</code>
|-
| Usuarios || <code>/vflow/admin/usuarios</code>
|-
| Configuración del sistema || <code>/vflow/admin/configuracion</code>
|-
| RAG Stores || <code>/vflow/admin/rag-stores</code>
|-
| RAG Loaders || <code>/vflow/admin/rag-loaders</code>
|-
| Metabase de datos || <code>/vflow/metadata</code>
|}

----

''Manual generado para su publicación en MediaWiki. Las imágenes se encuentran en la carpeta <code>img/</code>.''

Portal administracion de vFlow v01.04

2026-07-06T12:12:33Z

Alfredo.rodriguez:

== Manual de usuario — VFlow (Portal de IA) ==

<blockquote>'''Versión de la aplicación:''' v01.04.09 · © 2026 MDtel</blockquote>
----

__TOC__

=== 1. Introducción ===

'''VFlow''' es el portal de administración y analítica de los agentes de IA de MDtel. Desde una única interfaz web permite:

* Consultar '''métricas de uso''' (tokens, peticiones, sesiones y tiempos de respuesta) por modelo y periodo.
* Revisar el '''historial de peticiones''' y el '''detalle de las conversaciones''' de cada sesión.
* Gestionar la '''base de conocimiento RAG''' (almacenes de documentos y loaders).
* Administrar los componentes del sistema: '''plataformas, agentes, orquestadores, usuarios''' y '''parámetros globales'''.
* Mantener '''objetos de datos estructurados''' (Metabase de datos).

El manual recorre todas las pantallas en el orden en el que aparecen en el menú lateral.

----

=== 2. Acceso a la aplicación (Login) ===

Al abrir <code>https://labvflow/vflow</code> la aplicación redirige a la pantalla de inicio de sesión.

[[File:00-login.png|1000px|Pantalla de login de VFlow]]

'''Pasos para iniciar sesión:'''

# Introduce tu '''Usuario''' en el primer campo.
# Introduce tu '''Contraseña'''.
# Pulsa el botón '''Entrar'''.

<blockquote>El acceso está restringido a usuarios expresamente autorizados. Si las credenciales son incorrectas, la aplicación no permitirá el acceso y permanecerá en esta pantalla.</blockquote>

Una vez autenticado, se accede al '''Panel''' (dashboard) principal.

----

=== 3. Estructura general y menú de navegación ===

Tras iniciar sesión, la interfaz se organiza en dos zonas:

* '''Barra lateral izquierda:''' menú de navegación por iconos. Al pasar el ratón se muestra el nombre de cada sección.
* '''Área de contenido:''' muestra la pantalla de la sección seleccionada.

El menú lateral contiene las siguientes secciones (de arriba a abajo):

{| class="wikitable"
! Icono !! Sección !! Descripción
|-
| 📊 || '''Panel''' || Analítica y métricas de uso (dashboard).
|-
| 📋 || '''Peticiones''' || Historial de todas las peticiones realizadas.
|-
| 💬 || '''Sesiones''' || Historial de sesiones y detalle de conversaciones.
|-
| 🗄️ || '''Gestión RAG''' || Documentos y versiones de los almacenes RAG.
|-
| 🛡️ || '''Administración''' || Panel de administración de todos los componentes.
|-
| ⚙️ || '''Configuración''' || Ajustes de la interfaz (tema, idioma, etiquetas).
|-
| ⤺ || '''Salir''' || Cierra la sesión.
|}

En la esquina inferior izquierda se muestra siempre la '''versión''' de la aplicación (v01.04.09) y el aviso de copyright.

----

=== 4. Panel (Dashboard) ===

'''Ruta:''' <code>/vflow/dashboard</code>

Es la pantalla de inicio. Muestra el análisis y las métricas de uso del sistema.

[[File:01-dashboard.png|1000px|Panel de VFlow (dashboard)]]

'''Elementos de la cabecera:'''

* '''Total de tokens''', '''Total de peticiones''' y '''Chats únicos''': contadores globales del periodo seleccionado.
* '''Gráficas''' (desplegable): permite mostrar/ocultar las gráficas disponibles.
* '''Periodo''' (desplegable): filtra todas las métricas por el rango de fechas elegido.
* '''+ Añadir gráfica''': abre el asistente para crear una gráfica personalizada (ver 4.1).

'''Gráficas incluidas por defecto:'''

* '''Tokens por Modelo''' — tabla con el total de tokens consumidos por cada modelo.
* '''Evolución de Peticiones''' — evolución temporal del número de peticiones.
* '''Peticiones por Modelo''' — comparativa de peticiones por modelo.
* '''Evolución de Tokens''' — evolución temporal del consumo de tokens.
* '''Llamadas LLM por Día''', '''Tiempo de respuesta por modelo (ms)''' y '''Peticiones por hora del día''' (más abajo en la página).

Cada gráfica dispone del botón '''⚙ Configuración de Gráficos''' y de una leyenda con los modelos, donde se puede quitar un modelo pulsando la '''✕''' de su etiqueta.

==== 4.1 Añadir una gráfica personalizada ====

Al pulsar '''+ Añadir gráfica''' se abre el asistente '''Crear gráfica personalizada''':

[[File:dlg-anadir-grafica.png|1000px|Diálogo de creación de gráfica personalizada]]

Opciones de configuración:

* '''Nombre de la gráfica''': título que se mostrará.
* '''Fuente de datos''': origen de los datos (p. ej. ''Consumos (DAT_CONSUMOS)'').
* '''Agrupar por''': dimensión de agrupación (p. ej. ''Por Modelo'').
* '''Métrica''': valor a representar (p. ej. ''Número de llamadas'').
* '''Tipo de gráfica''': Barras, Horizontal, Línea, Área, Circular, Donut, KPI, Radar, Mapa de calor, Medidor, Histograma, Treemap o Dispersión.
* '''Color''', '''Estilo''' (mostrar leyenda, opacidad), rangos '''Y mínimo / Y máximo''' y '''Umbral de alerta'''.

A la derecha se muestra una '''Vista previa''' en tiempo real. Pulsa '''Guardar gráfica''' para añadirla al panel o '''Cancelar''' para descartar.

<blockquote>Nota: la creación de gráficas personalizadas puede estar limitada por rol (ver [[#8.5 Configuración del sistema|8.5 Configuración del sistema → Overrides por rol]]).</blockquote>

----

=== 5. Peticiones ===

'''Ruta:''' <code>/vflow/requests</code>

Muestra el '''Historial de Peticiones''': la lista completa de todas las peticiones realizadas al sistema.

[[File:02-peticiones.png|1000px|Historial de Peticiones]]

'''Filtros (parte superior):'''

* '''Plataformas''', '''Agentes''', '''Orquestadores''': desplegables para filtrar por cada componente.
* '''Periodo''': filtra por rango de fechas.

'''Tabla de Peticiones:'''

* Campo de '''Búsqueda''' y selector de '''Registros por página''' (10 por defecto).
* Columnas: '''Message ID''', '''ID de sesión''', '''Fecha''', '''Pregunta''' y '''Respuesta'''.
* Indicador ''"Mostrando 1 a 10 de N resultados"'' y '''paginación''' en la parte inferior.

Es la vista de referencia para auditar de forma tabular qué se preguntó, cuándo y qué respondió el agente.

----

=== 6. Sesiones ===

'''Ruta:''' <code>/vflow/conversations</code>

Muestra el '''Historial de sesiones'''. Cada sesión agrupa los mensajes de una conversación.

[[File:03-sesiones.png|1000px|Listado de Sesiones]]

'''Panel izquierdo (listado):'''

* Buscador '''"Buscar por ID de sesión o texto"'''.
* Botón '''Cargar más''' para paginar resultados.
* Cada tarjeta muestra: plataforma (p. ej. <code>omsui_1</code>), fecha/hora, '''agente''' e '''ID de sesión''', y el número de mensajes (<code>N msg</code>).
* Filtros superiores: '''Plataformas''', '''Agentes''', '''Orquestadores''', '''Sesiones''' y '''Periodo'''.

'''Panel derecho (detalle):''' al seleccionar una sesión se muestra la conversación completa en formato chat.

[[File:sesion-detalle.png|1000px|Detalle de una sesión]]

En el detalle se ven, en orden cronológico, los mensajes del '''usuario''' (a la derecha) y las respuestas del '''agente''' (a la izquierda, con el nombre del agente), junto con la cabecera de la sesión (plataforma, agente e ID).

----

=== 7. Gestión RAG ===

'''Ruta:''' <code>/vflow/rag-management</code>

Permite gestionar los documentos del sistema '''RAG''' (Retrieval-Augmented Generation), organizados por almacén (''store'').

[[File:04-gestion-rag.png|1000px|Gestión RAG]]

* Cada bloque corresponde a un '''RAG Store''' (p. ej. <code>ARA002</code>, <code>General</code>, <code>DS_ARA</code>) e indica su '''UUID''' y un estado ('''ACTUALIZADO''').
* Al expandir un store (flecha ▾) se muestran sus '''documentos/loaders'''. Para cada documento:
** Nombre del documento (p. ej. <code>ARA002_ld1</code>).
** '''Versión activa''' (etiqueta, p. ej. <code>v3</code>).
** Acciones: '''subir/actualizar''' (icono nube) y '''eliminar''' (icono papelera).

<blockquote>Esta pantalla es la vista operativa del contenido RAG. La definición de los stores y loaders se realiza en Administración (ver [[#8.6 RAG Stores|8.6]] y [[#8.7 RAG Loaders|8.7]]).</blockquote>

----

=== 8. Administración ===

'''Ruta:''' <code>/vflow/admin</code>

Panel central para administrar y configurar todos los componentes del sistema VFlow. Se presenta como una cuadrícula de tarjetas de acceso.

[[File:05-administracion.png|1000px|Panel de administración de VFlow]]

Tarjetas disponibles:

{| class="wikitable"
! Tarjeta !! Función
|-
| '''Plataformas''' || Gestión de plataformas.
|-
| '''Agentes''' || Gestión de agentes.
|-
| '''Orquestadores''' || Gestión de orquestadores.
|-
| '''Usuarios''' || Gestión de usuarios.
|-
| '''Configuración del sistema''' || Parámetros y ajustes globales.
|-
| '''RAG Stores''' || Almacenes de documentos RAG.
|-
| '''RAG Loaders''' || Loaders de documentos RAG.
|-
| '''Metabase de datos''' || Objetos, campos y registros estructurados.
|}

<blockquote>Aviso mostrado en la propia pantalla: ''"Desde este panel puedes administrar todas las configuraciones críticas del sistema VFlow. Asegúrate de tener los permisos necesarios antes de realizar cambios."''</blockquote>

En todas las subpantallas de administración el botón '''← Volver''' regresa a este panel.

==== 8.1 Plataformas ====

'''Ruta:''' <code>/vflow/admin/plataformas</code>

Listado de plataformas conectadas (p. ej. VIVAit, OmniSuite).

[[File:adm-plataformas.png|1000px|Listado de Plataformas]]

* Columnas: '''Nombre''', '''Identificador (UUID)''', '''Descripción''', '''Tipo''' (<code>vivait</code>, <code>omniSuite</code>…), '''Max Sesiones''' y '''Acciones''' (editar ✏️ / eliminar 🗑️).
* Botón '''+ Crear''' para dar de alta una plataforma.

'''Formulario de creación/edición:'''

[[File:dlg-plataforma.png|1000px|Formulario de plataforma]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Tipo''' ''(obligatorio)'': selector de tipo de plataforma.
* '''Descripción'''.
* '''Max Sesiones Abiertas''', '''Max Peticiones Simultáneas''', '''Max Peticiones/Min/Sesión''': límites de capacidad.

Pulsa '''Guardar''' para confirmar o '''Cancelar''' para descartar.

==== 8.2 Agentes ====

'''Ruta:''' <code>/vflow/admin/agentes</code>

Gestión de los agentes de IA.

[[File:adm-agentes.png|1000px|Listado de Agentes]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''Orquestadores''', '''IDs entorno''' (PRO / PRE / PRU) y '''Acciones'''.
* Los '''IDs entorno''' muestran el identificador del agente en cada entorno: '''PRO''' (Producción), '''PRE''' (Preproducción) y '''PRU''' (Pruebas).
* Botón '''+ Nuevo Agente'''.

'''Formulario de agente:'''

[[File:dlg-agente.png|1000px|Formulario de nuevo agente]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''ID Agente Producción''' ''(obligatorio)'', '''ID Agente Preproducción''', '''ID Agente Pruebas''': identificadores del agente en cada entorno.
* '''Descripción'''.
* '''Plataformas''' ''(obligatorio)'' y '''Orquestadores''' ''(obligatorio)'': selección del componente asociado.
* '''Timeout Respuesta (ms)''': tiempo máximo de espera de respuesta (30000 por defecto).

Los campos marcados con <code>*</code> son obligatorios. Pulsa '''Guardar'''.

==== 8.3 Orquestadores ====

'''Ruta:''' <code>/vflow/admin/orquestadores</code>

Gestión de los orquestadores (motores que enrutan/ejecutan las peticiones, p. ej. ''Flowise'', ''Bucle'').

[[File:adm-orquestadores.png|1000px|Listado de Orquestadores]]

* Columnas: '''Nombre''', '''Descripción''', '''Tipo''' (Bucle, Flowise…), '''URL Conexión''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de orquestador:'''

[[File:dlg-orquestador.png|1000px|Formulario de orquestador]]

Campos:

* '''Nombre''' ''(obligatorio)'' y '''Tipo''' ''(obligatorio)''.
* '''URL Conexión''' ''(obligatorio)'': endpoint del orquestador.
* '''URL Proxy (opcional)''', '''URL RAG'''.
* '''Cadena de Autenticación''': Bearer token o API Key.
* '''Usuario (opcional)''' y '''Contraseña (opcional)'''.
* '''Descripción'''.

==== 8.4 Usuarios ====

'''Ruta:''' <code>/vflow/admin/usuarios</code>

Gestión de las cuentas de usuario de VFlow.

[[File:adm-usuarios.png|1000px|Listado de Usuarios]]

* Columnas: '''Nombre''', '''Cuenta (login)''', '''Rol''' (Invitado, Usuario, Administrador), '''Activo''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de usuario:'''

[[File:dlg-usuario.png|1000px|Formulario de usuario]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Primer Apellido''', '''Segundo Apellido'''.
* '''Email''' ''(obligatorio)'', '''Móvil''', '''Cuenta (login)''' ''(obligatorio)''.
* '''Contraseña''' ''(obligatorio)''.
* '''Rol''' ''(obligatorio)'': perfil de permisos.
* '''Modo de Login''': ''Local'' (u otros modos disponibles, p. ej. SSO).

==== 8.5 Configuración del sistema ====

'''Ruta:''' <code>/vflow/admin/configuracion</code>

Parámetros y ajustes globales del sistema. Está organizada en '''pestañas'''. Los cambios se confirman con el botón '''Guardar Configuración''' (abajo a la derecha).

'''Pestaña Monitorización''' — estado general e incidencias recientes del frontend:

[[File:adm-configuracion-sistema.png|1000px|Configuración del sistema — Monitorización]]

Muestra tarjetas de estado: '''Estado''' (Backend disponible), '''Nivel de log''', '''Stores pendientes''', '''Histórico de sincronización''', '''Errores recientes''', '''Warnings recientes''' y '''Última comprobación'''. El botón '''Actualizar estado''' refresca los datos. Debajo se listan los ''stores pendientes'' de sincronización y el ''histórico de sincronización''.

<blockquote>Indicación en pantalla: los logs de frontend se ven en <code>F12 > Consola</code>; los del backend en <code>/opt/tomcat11/logs/catalina.out</code>.</blockquote>

'''Pestaña Tarificación:'''

[[File:cfg-tarificacion.png|1000px|Configuración del sistema — Tarificación]]

* '''Peticiones por Bloque a Tarificar''' y '''Segundos por Bloque a Tarificar'''.

'''Pestaña Configuración runtime''' — se guarda en <code>vflow-config.json</code> y se aplica al refrescar la aplicación:

[[File:cfg-configuracion.png|1000px|Configuración del sistema — Configuración runtime]]

* '''URL de la API backend''' (p. ej. <code>/vflow/api</code>): ruta que usa el frontend para llamar al backend.
* '''Tamaño de página de sesiones''': nº de sesiones por tanda en la pantalla de conversaciones.
* '''Nivel de log''': DEBUG muestra todo, ERROR solo fallos.
* '''Overrides por rol''': permite ajustar 2FA y la '''visibilidad del dashboard''' por perfil (Administrador, Invitado, Usuario), incluyendo qué gráficas ve cada rol y si puede crear gráficas personalizadas.

'''Pestaña Rutas de Archivos''' — configuradas en servidor, '''no editables''' desde la interfaz:

[[File:cfg-rutas.png|1000px|Configuración del sistema — Rutas de Archivos]]

* '''Ruta de Documentos''' (p. ej. <code>/etc/MDtel/vFlow/Documentos/</code>).
* '''Ruta API Loader''' (p. ej. <code>/var/www/html/storages/</code>).

'''Pestaña Timeouts de Sesión (segundos):'''

[[File:cfg-timeouts.png|1000px|Configuración del sistema — Timeouts de Sesión]]

* '''Dormir Sesión''', '''Sesión Voz''', '''Sesión Chat''' y '''Sesión Email''': tiempos de expiración por tipo de sesión.

==== 8.6 RAG Stores ====

'''Ruta:''' <code>/vflow/admin/rag-stores</code>

Gestión de los almacenes de documentos RAG.

[[File:adm-rag-stores.png|1000px|Listado de RAG Stores]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''ID Store Producción''', '''ID Store Preproducción''', '''ID Store Pruebas''' y '''Acciones'''.
* Botón '''+ Nuevo RAG Store'''.

'''Formulario de RAG Store:'''

[[File:dlg-ragstore.png|1000px|Formulario de RAG Store]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Plataformas''' ''(obligatorio)'', '''Orquestadores''' ''(obligatorio)''.
* '''Descripción'''.
* '''ID Store Producción''' ''(obligatorio)'', '''ID Store Preproducción''', '''ID Store Pruebas''': identificadores del Document Store en cada entorno.

==== 8.7 RAG Loaders ====

'''Ruta:''' <code>/vflow/admin/rag-loaders</code>

Gestión de los ''loaders'' (cargadores de documentos) asociados a los RAG Stores.

[[File:adm-rag-loaders.png|1000px|Listado de RAG Loaders]]

* Columnas: '''Nombre''', '''RAG Stores''', '''Interno (gestionado por VFlow)''', '''Configuración JSON''' y '''Acciones''' (eliminar).
* Botón '''+ Añadir loader'''.

'''Formulario de loader:'''

[[File:dlg-ragloader.png|1000px|Formulario de añadir loader]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Descripción'''.
* '''Nombre del archivo''' ''(obligatorio)''.
* '''Seleccione un RAG Store''' ''(obligatorio)'': store al que se asocia.
* '''Contenido detectado del archivo base''': área de texto con el contenido.

Pulsa '''Crear''' para añadirlo.

==== 8.8 Metabase de datos ====

'''Ruta:''' <code>/vflow/metadata</code>

Gestión de '''objetos de datos estructurados''' (tablas de datos que puede usar el sistema: clientes, doctores, etc.).

[[File:adm-metabase.png|1000px|Metabase de datos]]

* Cada tarjeta representa un '''objeto''' (p. ej. ''Clientes'', ''Doctores'') e indica su descripción, el '''JSON''' asociado y la '''Ruta'''.
* Acciones por objeto: '''Editar objeto''' (definición/estructura) y '''Editar/Ver datos''' (registros).
* Botones superiores: '''↻''' (refrescar) y '''+ Nuevo objeto'''.

'''Nuevo objeto / Editar objeto''' — define la estructura del objeto:

[[File:dlg-metaobjeto.png|1000px|Diálogo de nuevo objeto]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Descripción'''.
* '''Nombre del JSON''' y '''Ruta de upload'''.
* '''Campos''': definición de los campos del objeto (botón '''+ Añadir campo''').
* A la derecha se muestra una vista previa del '''JSON''' resultante.

'''Editar/Ver datos''' — gestiona los registros del objeto:

[[File:meta-ver-datos.png|1000px|Vista de datos de un objeto (registros)]]

* Tabla paginada con los registros y sus columnas (Id, Nombre, Fecha, Dirección, Localidad, Teléfono, Email, etc.).
* Acciones por fila: '''editar''' ✏️ y '''eliminar''' 🗑️.
* Botones superiores: '''← Volver''', '''↻''' refrescar, '''⤒ Importar''', '''Generar JSON''', '''Eliminar todo''' y '''+ Nuevo registro'''.

----

=== 9. Configuración de la interfaz ===

Al pulsar el icono '''⚙ Configuración''' de la barra lateral (parte inferior) se despliega un pequeño menú de ajustes de la interfaz:

[[File:menu-configuracion.png|1000px|Menú de configuración de la interfaz]]

Opciones:

* '''Tema Claro / Oscuro''': interruptor para cambiar el aspecto visual.
* '''Idioma''': selector de idioma (p. ej. '''ES''').
* '''Etiquetas de navegación''': interruptor para mostrar u ocultar los textos junto a los iconos del menú lateral.

Estos ajustes afectan únicamente a la visualización de la interfaz para el usuario actual.

----

=== 10. Salir de la aplicación ===

Para cerrar la sesión, pulsa el icono '''⤺ Salir''' situado en la parte inferior de la barra lateral. La aplicación cerrará la sesión y volverá a la pantalla de [[#2. Acceso a la aplicación (Login)|Login]].

----

=== Anexo — Rutas de la aplicación ===

{| class="wikitable"
! Sección !! Ruta
|-
| Login || <code>/vflow/login</code>
|-
| Panel || <code>/vflow/dashboard</code>
|-
| Peticiones || <code>/vflow/requests</code>
|-
| Sesiones || <code>/vflow/conversations</code>
|-
| Gestión RAG || <code>/vflow/rag-management</code>
|-
| Administración || <code>/vflow/admin</code>
|-
| Plataformas || <code>/vflow/admin/plataformas</code>
|-
| Agentes || <code>/vflow/admin/agentes</code>
|-
| Orquestadores || <code>/vflow/admin/orquestadores</code>
|-
| Usuarios || <code>/vflow/admin/usuarios</code>
|-
| Configuración del sistema || <code>/vflow/admin/configuracion</code>
|-
| RAG Stores || <code>/vflow/admin/rag-stores</code>
|-
| RAG Loaders || <code>/vflow/admin/rag-loaders</code>
|-
| Metabase de datos || <code>/vflow/metadata</code>
|}

----

''Manual generado para su publicación en MediaWiki. Las imágenes se encuentran en la carpeta <code>img/</code>.''

Portal administracion de vFlow v01.04

2026-07-06T12:00:01Z

Alfredo.rodriguez: /* Manual de usuario — VFlow (Portal de IA) */

== Manual de usuario — VFlow (Portal de IA) ==

<blockquote>'''Versión de la aplicación:''' v01.04.09 · © 2026 MDtel</blockquote>
----

__TOC__

=== 1. Introducción ===

'''VFlow''' es el portal de administración y analítica de los agentes de IA de MDtel. Desde una única interfaz web permite:

* Consultar '''métricas de uso''' (tokens, peticiones, sesiones y tiempos de respuesta) por modelo y periodo.
* Revisar el '''historial de peticiones''' y el '''detalle de las conversaciones''' de cada sesión.
* Gestionar la '''base de conocimiento RAG''' (almacenes de documentos y loaders).
* Administrar los componentes del sistema: '''plataformas, agentes, orquestadores, usuarios''' y '''parámetros globales'''.
* Mantener '''objetos de datos estructurados''' (Metabase de datos).

El manual recorre todas las pantallas en el orden en el que aparecen en el menú lateral.

----

=== 2. Acceso a la aplicación (Login) ===

Al abrir <code>https://labvflow/vflow</code> la aplicación redirige a la pantalla de inicio de sesión.

[[File:00-login.png|800px|Pantalla de login de VFlow]]

'''Pasos para iniciar sesión:'''

# Introduce tu '''Usuario''' en el primer campo.
# Introduce tu '''Contraseña'''.
# Pulsa el botón '''Entrar'''.

<blockquote>El acceso está restringido a usuarios expresamente autorizados. Si las credenciales son incorrectas, la aplicación no permitirá el acceso y permanecerá en esta pantalla.</blockquote>

Una vez autenticado, se accede al '''Panel''' (dashboard) principal.

----

=== 3. Estructura general y menú de navegación ===

Tras iniciar sesión, la interfaz se organiza en dos zonas:

* '''Barra lateral izquierda:''' menú de navegación por iconos. Al pasar el ratón se muestra el nombre de cada sección.
* '''Área de contenido:''' muestra la pantalla de la sección seleccionada.

El menú lateral contiene las siguientes secciones (de arriba a abajo):

{| class="wikitable"
! Icono !! Sección !! Descripción
|-
| 📊 || '''Panel''' || Analítica y métricas de uso (dashboard).
|-
| 📋 || '''Peticiones''' || Historial de todas las peticiones realizadas.
|-
| 💬 || '''Sesiones''' || Historial de sesiones y detalle de conversaciones.
|-
| 🗄️ || '''Gestión RAG''' || Documentos y versiones de los almacenes RAG.
|-
| 🛡️ || '''Administración''' || Panel de administración de todos los componentes.
|-
| ⚙️ || '''Configuración''' || Ajustes de la interfaz (tema, idioma, etiquetas).
|-
| ⤺ || '''Salir''' || Cierra la sesión.
|}

En la esquina inferior izquierda se muestra siempre la '''versión''' de la aplicación (v01.04.09) y el aviso de copyright.

----

=== 4. Panel (Dashboard) ===

'''Ruta:''' <code>/vflow/dashboard</code>

Es la pantalla de inicio. Muestra el análisis y las métricas de uso del sistema.

[[File:01-dashboard.png|800px|Panel de VFlow (dashboard)]]

'''Elementos de la cabecera:'''

* '''Total de tokens''', '''Total de peticiones''' y '''Chats únicos''': contadores globales del periodo seleccionado.
* '''Gráficas''' (desplegable): permite mostrar/ocultar las gráficas disponibles.
* '''Periodo''' (desplegable): filtra todas las métricas por el rango de fechas elegido.
* '''+ Añadir gráfica''': abre el asistente para crear una gráfica personalizada (ver 4.1).

'''Gráficas incluidas por defecto:'''

* '''Tokens por Modelo''' — tabla con el total de tokens consumidos por cada modelo.
* '''Evolución de Peticiones''' — evolución temporal del número de peticiones.
* '''Peticiones por Modelo''' — comparativa de peticiones por modelo.
* '''Evolución de Tokens''' — evolución temporal del consumo de tokens.
* '''Llamadas LLM por Día''', '''Tiempo de respuesta por modelo (ms)''' y '''Peticiones por hora del día''' (más abajo en la página).

Cada gráfica dispone del botón '''⚙ Configuración de Gráficos''' y de una leyenda con los modelos, donde se puede quitar un modelo pulsando la '''✕''' de su etiqueta.

==== 4.1 Añadir una gráfica personalizada ====

Al pulsar '''+ Añadir gráfica''' se abre el asistente '''Crear gráfica personalizada''':

[[File:dlg-anadir-grafica.png|800px|Diálogo de creación de gráfica personalizada]]

Opciones de configuración:

* '''Nombre de la gráfica''': título que se mostrará.
* '''Fuente de datos''': origen de los datos (p. ej. ''Consumos (DAT_CONSUMOS)'').
* '''Agrupar por''': dimensión de agrupación (p. ej. ''Por Modelo'').
* '''Métrica''': valor a representar (p. ej. ''Número de llamadas'').
* '''Tipo de gráfica''': Barras, Horizontal, Línea, Área, Circular, Donut, KPI, Radar, Mapa de calor, Medidor, Histograma, Treemap o Dispersión.
* '''Color''', '''Estilo''' (mostrar leyenda, opacidad), rangos '''Y mínimo / Y máximo''' y '''Umbral de alerta'''.

A la derecha se muestra una '''Vista previa''' en tiempo real. Pulsa '''Guardar gráfica''' para añadirla al panel o '''Cancelar''' para descartar.

<blockquote>Nota: la creación de gráficas personalizadas puede estar limitada por rol (ver [[#8.5 Configuración del sistema|8.5 Configuración del sistema → Overrides por rol]]).</blockquote>

----

=== 5. Peticiones ===

'''Ruta:''' <code>/vflow/requests</code>

Muestra el '''Historial de Peticiones''': la lista completa de todas las peticiones realizadas al sistema.

[[File:02-peticiones.png|800px|Historial de Peticiones]]

'''Filtros (parte superior):'''

* '''Plataformas''', '''Agentes''', '''Orquestadores''': desplegables para filtrar por cada componente.
* '''Periodo''': filtra por rango de fechas.

'''Tabla de Peticiones:'''

* Campo de '''Búsqueda''' y selector de '''Registros por página''' (10 por defecto).
* Columnas: '''Message ID''', '''ID de sesión''', '''Fecha''', '''Pregunta''' y '''Respuesta'''.
* Indicador ''"Mostrando 1 a 10 de N resultados"'' y '''paginación''' en la parte inferior.

Es la vista de referencia para auditar de forma tabular qué se preguntó, cuándo y qué respondió el agente.

----

=== 6. Sesiones ===

'''Ruta:''' <code>/vflow/conversations</code>

Muestra el '''Historial de sesiones'''. Cada sesión agrupa los mensajes de una conversación.

[[File:03-sesiones.png|800px|Listado de Sesiones]]

'''Panel izquierdo (listado):'''

* Buscador '''"Buscar por ID de sesión o texto"'''.
* Botón '''Cargar más''' para paginar resultados.
* Cada tarjeta muestra: plataforma (p. ej. <code>omsui_1</code>), fecha/hora, '''agente''' e '''ID de sesión''', y el número de mensajes (<code>N msg</code>).
* Filtros superiores: '''Plataformas''', '''Agentes''', '''Orquestadores''', '''Sesiones''' y '''Periodo'''.

'''Panel derecho (detalle):''' al seleccionar una sesión se muestra la conversación completa en formato chat.

[[File:sesion-detalle.png|800px|Detalle de una sesión]]

En el detalle se ven, en orden cronológico, los mensajes del '''usuario''' (a la derecha) y las respuestas del '''agente''' (a la izquierda, con el nombre del agente), junto con la cabecera de la sesión (plataforma, agente e ID).

----

=== 7. Gestión RAG ===

'''Ruta:''' <code>/vflow/rag-management</code>

Permite gestionar los documentos del sistema '''RAG''' (Retrieval-Augmented Generation), organizados por almacén (''store'').

[[File:04-gestion-rag.png|800px|Gestión RAG]]

* Cada bloque corresponde a un '''RAG Store''' (p. ej. <code>ARA002</code>, <code>General</code>, <code>DS_ARA</code>) e indica su '''UUID''' y un estado ('''ACTUALIZADO''').
* Al expandir un store (flecha ▾) se muestran sus '''documentos/loaders'''. Para cada documento:
** Nombre del documento (p. ej. <code>ARA002_ld1</code>).
** '''Versión activa''' (etiqueta, p. ej. <code>v3</code>).
** Acciones: '''subir/actualizar''' (icono nube) y '''eliminar''' (icono papelera).

<blockquote>Esta pantalla es la vista operativa del contenido RAG. La definición de los stores y loaders se realiza en Administración (ver [[#8.6 RAG Stores|8.6]] y [[#8.7 RAG Loaders|8.7]]).</blockquote>

----

=== 8. Administración ===

'''Ruta:''' <code>/vflow/admin</code>

Panel central para administrar y configurar todos los componentes del sistema VFlow. Se presenta como una cuadrícula de tarjetas de acceso.

[[File:05-administracion.png|800px|Panel de administración de VFlow]]

Tarjetas disponibles:

{| class="wikitable"
! Tarjeta !! Función
|-
| '''Plataformas''' || Gestión de plataformas.
|-
| '''Agentes''' || Gestión de agentes.
|-
| '''Orquestadores''' || Gestión de orquestadores.
|-
| '''Usuarios''' || Gestión de usuarios.
|-
| '''Configuración del sistema''' || Parámetros y ajustes globales.
|-
| '''RAG Stores''' || Almacenes de documentos RAG.
|-
| '''RAG Loaders''' || Loaders de documentos RAG.
|-
| '''Metabase de datos''' || Objetos, campos y registros estructurados.
|}

<blockquote>Aviso mostrado en la propia pantalla: ''"Desde este panel puedes administrar todas las configuraciones críticas del sistema VFlow. Asegúrate de tener los permisos necesarios antes de realizar cambios."''</blockquote>

En todas las subpantallas de administración el botón '''← Volver''' regresa a este panel.

==== 8.1 Plataformas ====

'''Ruta:''' <code>/vflow/admin/plataformas</code>

Listado de plataformas conectadas (p. ej. VIVAit, OmniSuite).

[[File:adm-plataformas.png|800px|Listado de Plataformas]]

* Columnas: '''Nombre''', '''Identificador (UUID)''', '''Descripción''', '''Tipo''' (<code>vivait</code>, <code>omniSuite</code>…), '''Max Sesiones''' y '''Acciones''' (editar ✏️ / eliminar 🗑️).
* Botón '''+ Crear''' para dar de alta una plataforma.

'''Formulario de creación/edición:'''

[[File:dlg-plataforma.png|800px|Formulario de plataforma]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Tipo''' ''(obligatorio)'': selector de tipo de plataforma.
* '''Descripción'''.
* '''Max Sesiones Abiertas''', '''Max Peticiones Simultáneas''', '''Max Peticiones/Min/Sesión''': límites de capacidad.

Pulsa '''Guardar''' para confirmar o '''Cancelar''' para descartar.

==== 8.2 Agentes ====

'''Ruta:''' <code>/vflow/admin/agentes</code>

Gestión de los agentes de IA.

[[File:adm-agentes.png|800px|Listado de Agentes]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''Orquestadores''', '''IDs entorno''' (PRO / PRE / PRU) y '''Acciones'''.
* Los '''IDs entorno''' muestran el identificador del agente en cada entorno: '''PRO''' (Producción), '''PRE''' (Preproducción) y '''PRU''' (Pruebas).
* Botón '''+ Nuevo Agente'''.

'''Formulario de agente:'''

[[File:dlg-agente.png|800px|Formulario de nuevo agente]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''ID Agente Producción''' ''(obligatorio)'', '''ID Agente Preproducción''', '''ID Agente Pruebas''': identificadores del agente en cada entorno.
* '''Descripción'''.
* '''Plataformas''' ''(obligatorio)'' y '''Orquestadores''' ''(obligatorio)'': selección del componente asociado.
* '''Timeout Respuesta (ms)''': tiempo máximo de espera de respuesta (30000 por defecto).

Los campos marcados con <code>*</code> son obligatorios. Pulsa '''Guardar'''.

==== 8.3 Orquestadores ====

'''Ruta:''' <code>/vflow/admin/orquestadores</code>

Gestión de los orquestadores (motores que enrutan/ejecutan las peticiones, p. ej. ''Flowise'', ''Bucle'').

[[File:adm-orquestadores.png|800px|Listado de Orquestadores]]

* Columnas: '''Nombre''', '''Descripción''', '''Tipo''' (Bucle, Flowise…), '''URL Conexión''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de orquestador:'''

[[File:dlg-orquestador.png|800px|Formulario de orquestador]]

Campos:

* '''Nombre''' ''(obligatorio)'' y '''Tipo''' ''(obligatorio)''.
* '''URL Conexión''' ''(obligatorio)'': endpoint del orquestador.
* '''URL Proxy (opcional)''', '''URL RAG'''.
* '''Cadena de Autenticación''': Bearer token o API Key.
* '''Usuario (opcional)''' y '''Contraseña (opcional)'''.
* '''Descripción'''.

==== 8.4 Usuarios ====

'''Ruta:''' <code>/vflow/admin/usuarios</code>

Gestión de las cuentas de usuario de VFlow.

[[File:adm-usuarios.png|800px|Listado de Usuarios]]

* Columnas: '''Nombre''', '''Cuenta (login)''', '''Rol''' (Invitado, Usuario, Administrador), '''Activo''' y '''Acciones'''.
* Botón '''+ Crear'''.

'''Formulario de usuario:'''

[[File:dlg-usuario.png|800px|Formulario de usuario]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Primer Apellido''', '''Segundo Apellido'''.
* '''Email''' ''(obligatorio)'', '''Móvil''', '''Cuenta (login)''' ''(obligatorio)''.
* '''Contraseña''' ''(obligatorio)''.
* '''Rol''' ''(obligatorio)'': perfil de permisos.
* '''Modo de Login''': ''Local'' (u otros modos disponibles, p. ej. SSO).

==== 8.5 Configuración del sistema ====

'''Ruta:''' <code>/vflow/admin/configuracion</code>

Parámetros y ajustes globales del sistema. Está organizada en '''pestañas'''. Los cambios se confirman con el botón '''Guardar Configuración''' (abajo a la derecha).

'''Pestaña Monitorización''' — estado general e incidencias recientes del frontend:

[[File:adm-configuracion-sistema.png|800px|Configuración del sistema — Monitorización]]

Muestra tarjetas de estado: '''Estado''' (Backend disponible), '''Nivel de log''', '''Stores pendientes''', '''Histórico de sincronización''', '''Errores recientes''', '''Warnings recientes''' y '''Última comprobación'''. El botón '''Actualizar estado''' refresca los datos. Debajo se listan los ''stores pendientes'' de sincronización y el ''histórico de sincronización''.

<blockquote>Indicación en pantalla: los logs de frontend se ven en <code>F12 > Consola</code>; los del backend en <code>/opt/tomcat11/logs/catalina.out</code>.</blockquote>

'''Pestaña Tarificación:'''

[[File:cfg-tarificacion.png|800px|Configuración del sistema — Tarificación]]

* '''Peticiones por Bloque a Tarificar''' y '''Segundos por Bloque a Tarificar'''.

'''Pestaña Configuración runtime''' — se guarda en <code>vflow-config.json</code> y se aplica al refrescar la aplicación:

[[File:cfg-configuracion.png|800px|Configuración del sistema — Configuración runtime]]

* '''URL de la API backend''' (p. ej. <code>/vflow/api</code>): ruta que usa el frontend para llamar al backend.
* '''Tamaño de página de sesiones''': nº de sesiones por tanda en la pantalla de conversaciones.
* '''Nivel de log''': DEBUG muestra todo, ERROR solo fallos.
* '''Overrides por rol''': permite ajustar 2FA y la '''visibilidad del dashboard''' por perfil (Administrador, Invitado, Usuario), incluyendo qué gráficas ve cada rol y si puede crear gráficas personalizadas.

'''Pestaña Rutas de Archivos''' — configuradas en servidor, '''no editables''' desde la interfaz:

[[File:cfg-rutas.png|800px|Configuración del sistema — Rutas de Archivos]]

* '''Ruta de Documentos''' (p. ej. <code>/etc/MDtel/vFlow/Documentos/</code>).
* '''Ruta API Loader''' (p. ej. <code>/var/www/html/storages/</code>).

'''Pestaña Timeouts de Sesión (segundos):'''

[[File:cfg-timeouts.png|800px|Configuración del sistema — Timeouts de Sesión]]

* '''Dormir Sesión''', '''Sesión Voz''', '''Sesión Chat''' y '''Sesión Email''': tiempos de expiración por tipo de sesión.

==== 8.6 RAG Stores ====

'''Ruta:''' <code>/vflow/admin/rag-stores</code>

Gestión de los almacenes de documentos RAG.

[[File:adm-rag-stores.png|800px|Listado de RAG Stores]]

* Columnas: '''Nombre''', '''Descripción''', '''Plataformas''', '''ID Store Producción''', '''ID Store Preproducción''', '''ID Store Pruebas''' y '''Acciones'''.
* Botón '''+ Nuevo RAG Store'''.

'''Formulario de RAG Store:'''

[[File:dlg-ragstore.png|800px|Formulario de RAG Store]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Plataformas''' ''(obligatorio)'', '''Orquestadores''' ''(obligatorio)''.
* '''Descripción'''.
* '''ID Store Producción''' ''(obligatorio)'', '''ID Store Preproducción''', '''ID Store Pruebas''': identificadores del Document Store en cada entorno.

==== 8.7 RAG Loaders ====

'''Ruta:''' <code>/vflow/admin/rag-loaders</code>

Gestión de los ''loaders'' (cargadores de documentos) asociados a los RAG Stores.

[[File:adm-rag-loaders.png|800px|Listado de RAG Loaders]]

* Columnas: '''Nombre''', '''RAG Stores''', '''Interno (gestionado por VFlow)''', '''Configuración JSON''' y '''Acciones''' (eliminar).
* Botón '''+ Añadir loader'''.

'''Formulario de loader:'''

[[File:dlg-ragloader.png|800px|Formulario de añadir loader]]

Campos:

* '''Nombre''' ''(obligatorio)''.
* '''Descripción'''.
* '''Nombre del archivo''' ''(obligatorio)''.
* '''Seleccione un RAG Store''' ''(obligatorio)'': store al que se asocia.
* '''Contenido detectado del archivo base''': área de texto con el contenido.

Pulsa '''Crear''' para añadirlo.

==== 8.8 Metabase de datos ====

'''Ruta:''' <code>/vflow/metadata</code>

Gestión de '''objetos de datos estructurados''' (tablas de datos que puede usar el sistema: clientes, doctores, etc.).

[[File:adm-metabase.png|800px|Metabase de datos]]

* Cada tarjeta representa un '''objeto''' (p. ej. ''Clientes'', ''Doctores'') e indica su descripción, el '''JSON''' asociado y la '''Ruta'''.
* Acciones por objeto: '''Editar objeto''' (definición/estructura) y '''Editar/Ver datos''' (registros).
* Botones superiores: '''↻''' (refrescar) y '''+ Nuevo objeto'''.

'''Nuevo objeto / Editar objeto''' — define la estructura del objeto:

[[File:dlg-metaobjeto.png|800px|Diálogo de nuevo objeto]]

Campos:

* '''Nombre''' ''(obligatorio)'', '''Descripción'''.
* '''Nombre del JSON''' y '''Ruta de upload'''.
* '''Campos''': definición de los campos del objeto (botón '''+ Añadir campo''').
* A la derecha se muestra una vista previa del '''JSON''' resultante.

'''Editar/Ver datos''' — gestiona los registros del objeto:

[[File:meta-ver-datos.png|800px|Vista de datos de un objeto (registros)]]

* Tabla paginada con los registros y sus columnas (Id, Nombre, Fecha, Dirección, Localidad, Teléfono, Email, etc.).
* Acciones por fila: '''editar''' ✏️ y '''eliminar''' 🗑️.
* Botones superiores: '''← Volver''', '''↻''' refrescar, '''⤒ Importar''', '''Generar JSON''', '''Eliminar todo''' y '''+ Nuevo registro'''.

----

=== 9. Configuración de la interfaz ===

Al pulsar el icono '''⚙ Configuración''' de la barra lateral (parte inferior) se despliega un pequeño menú de ajustes de la interfaz:

[[File:menu-configuracion.png|800px|Menú de configuración de la interfaz]]

Opciones:

* '''Tema Claro / Oscuro''': interruptor para cambiar el aspecto visual.
* '''Idioma''': selector de idioma (p. ej. '''ES''').
* '''Etiquetas de navegación''': interruptor para mostrar u ocultar los textos junto a los iconos del menú lateral.

Estos ajustes afectan únicamente a la visualización de la interfaz para el usuario actual.

----

=== 10. Salir de la aplicación ===

Para cerrar la sesión, pulsa el icono '''⤺ Salir''' situado en la parte inferior de la barra lateral. La aplicación cerrará la sesión y volverá a la pantalla de [[#2. Acceso a la aplicación (Login)|Login]].

----

=== Anexo — Rutas de la aplicación ===

{| class="wikitable"
! Sección !! Ruta
|-
| Login || <code>/vflow/login</code>
|-
| Panel || <code>/vflow/dashboard</code>
|-
| Peticiones || <code>/vflow/requests</code>
|-
| Sesiones || <code>/vflow/conversations</code>
|-
| Gestión RAG || <code>/vflow/rag-management</code>
|-
| Administración || <code>/vflow/admin</code>
|-
| Plataformas || <code>/vflow/admin/plataformas</code>
|-
| Agentes || <code>/vflow/admin/agentes</code>
|-
| Orquestadores || <code>/vflow/admin/orquestadores</code>
|-
| Usuarios || <code>/vflow/admin/usuarios</code>
|-
| Configuración del sistema || <code>/vflow/admin/configuracion</code>
|-
| RAG Stores || <code>/vflow/admin/rag-stores</code>
|-
| RAG Loaders || <code>/vflow/admin/rag-loaders</code>
|-
| Metabase de datos || <code>/vflow/metadata</code>
|}

----

''Manual generado para su publicación en MediaWiki. Las imágenes se encuentran en la carpeta <code>img/</code>.''

Archivo:Sesion-detalle.png

2026-07-06T11:59:04Z

Alfredo.rodriguez:

Archivo:Meta-ver-datos.png

2026-07-06T11:58:46Z

Alfredo.rodriguez: