Runbook — Habilitar cuenta de m-system

Alta de un cliente nuevo en m-system: desde la configuración de los equipos Modbus hasta la infraestructura en AWS que procesa sus mensajes.

Ficha

Tipo	Operativo (rutinario, no es un incidente)
Cuándo usarlo	Al habilitar un cliente nuevo en m-system
Tiempo estimado	1 hora sin pruebas · 3 horas haciéndolo bien, con verificación
Requiere	Acceso al repositorio, a m-system como superadministrador y a la cuenta AWS
Owner	TAD — Departamento de Aplicaciones Tecnológicas · DDS — Departamento de Desarrollo de Software
Última ejecución	AAAA-MM-DD

Procedimiento manual — el error humano es el riesgo principal

Todo este proceso se hace a mano y depende de replicar nombres y configuraciones sin equivocarse. Está registrado como deuda técnica prioritaria en Deuda técnica: la meta es automatizarlo.

Mientras tanto: seguir el runbook paso a paso y verificar cada uno antes de continuar. No hacerlo de memoria.

El UUID es la pieza central

Todo el aprovisionamiento gira alrededor del UUID que m-system genera para el usuario del cliente. Ese identificador es lo que permite reconocer, más adelante, qué infraestructura pertenece a quién.

Se usa en cinco lugares, y no siempre con el mismo formato:

Dónde	Formato	Ejemplo
Bucket de InfluxDB	UUID con guiones	291bd6a4-ee3f-4318-87e1-6152eefb819a
Nombre de la cola SQS	UUID con guiones	291bd6a4-ee3f-4318-87e1-6152eefb819a
Topic de la regla IoT (SELECT ... FROM)	UUID con guiones	291bd6a4-ee3f-4318-87e1-6152eefb819a
Nombre de la regla de IoT Core	UUID con guion bajo	291bd6a4_ee3f_4318_87e1_6152eefb819a
Nombre de la Lambda	UUID con guiones	291bd6a4-ee3f-4318-87e1-6152eefb819a
Variable INFLUX_DATABASE de la Lambda	UUID con guiones	291bd6a4-ee3f-4318-87e1-6152eefb819a

La trampa más fácil de cometer

El nombre de la regla de IoT Core es el único que lleva guiones bajos: AWS no admite guiones en ese campo. El topic dentro de la instrucción SQL de esa misma regla sí va con guiones. Confundirlos hace que la regla exista pero no enrute nada.

1. Disparador

La solicitud nace en Gestión de Proyectos y llega al equipo técnico a través del jefe de área.

Rol	Persona	Para qué
Contacto con el cliente final	Ing. Daniel — digital15@industriascts.com.co	Origen de la solicitud; habla con el cliente y con el jefe de área
Jefe de área	Ing. Juan Carlos Sanguino	Autoriza y traslada la solicitud al equipo técnico
Gestión de proyectos	Ing. Alexander Figueroa	Configuración de los equipos y parámetros del cliente

De la solicitud debe salir, entre otros datos, la retención del bucket de InfluxDB (paso 6.3).

Pendiente — proceso comercial

El proceso y los canales de comunicación previos (cómo llega la necesidad desde el cliente hasta Gestión de Proyectos) no están documentados. Queda fuera del alcance técnico de este runbook; hay que abordarlo con Gestión de Proyectos más adelante.

2. Precondiciones

• Acceso al repositorio Industrias-CTS/devices-recognizer.
• Usuario superadministrador en app.m-system.cloud.
• Acceso a la cuenta de AWS admin@industriascts.com (región us-east-1).
• Hardware disponible: Kunbus RevPi Core S o Raspberry Pi 5.
• Datos del cliente confirmados con el jefe de área y el gestor del proyecto.

Los valores de credenciales y tokens no están en este handbook.

3. Configurar los equipos Modbus

Repositorio: Industrias-CTS/devices-recognizer · rama developer (contiene la versión vigente).

Dentro hay un proyecto interno llamado config-generator: una aplicación en React que abre un configurador donde se declaran los equipos Modbus que van a funcionar en la plataforma.

Quién sabe usar el configurador

Ing. Alexander Figueroa, área de Gestión de Proyectos. Es la referencia para resolver dudas sobre cómo configurar los equipos. Ver Contactos.

El configurador genera 4 archivos:

Archivo	Se usa en
generalConfiguration.json	Repo devices-recognizer (paso 4)
devices.json	Repo devices-recognizer (paso 4)
first-seed.js	Repo devices-recognizer (paso 4)
tablero.txt	m-system, al importar el dispositivo (paso 6.2)

4. Generar la base de datos

En el repo principal devices-recognizer:

1. Reemplazar generalConfiguration.json, devices.json y first-seed.js por los que generó el configurador.
2. Generar la base de datos con Prisma:

npx prisma migrate dev
npx prisma generate
npm run seed

5. Preparar el equipo de campo

El proyecto se copia a un equipo con Node, Redis y PM2, y se deja corriendo bajo PM2 con arranque automático al encender.

5.1 Preparar el sistema

# Actualizar el sistema
sudo apt update && sudo apt upgrade -y

# Instalar nvm
# Verificar la versión vigente del instalador en https://github.com/nvm-sh/nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# Recargar la sesión para que nvm quede disponible
source ~/.bashrc

# Node 22
nvm install 22
nvm use 22
nvm alias default 22     # que 22 sea la versión por defecto tras reiniciar

# Redis
sudo apt install -y redis-server
sudo systemctl enable --now redis-server

# PM2, global
npm install -g pm2

Verificar antes de continuar:

node -v                  # debe reportar v22.x
redis-cli ping           # debe responder PONG
pm2 -v

5.2 Copiar el proyecto al equipo

Hoy se copia con rsync sobre SSH. Requiere estar en la misma red que el hardware.

rsync -avz --exclude node_modules ./ <usuario>@<ip-del-equipo>:<ruta-destino>/

No hay estándar definido

Usuario, ruta de destino y exclusiones se deciden en el momento, sin una convención escrita. Definir ese estándar es parte de la mejora del proceso — ver Deuda técnica y riesgos.

5.3 Arrancar la aplicación

# Desde el directorio del proyecto en el equipo
pm2 start <entrypoint> --name <nombre-del-proceso>

# Generar el script de arranque automático.
# Este comando IMPRIME otro comando con sudo: hay que copiarlo y ejecutarlo.
pm2 startup

# Guardar la lista de procesos para que se restaure al reiniciar
pm2 save

pm2 save es obligatorio

Sin pm2 startup y pm2 save, la aplicación no vuelve sola después de un corte de energía. En un equipo en campo eso significa un cliente sin datos hasta que alguien viaje al sitio.

Verificar reiniciando el equipo y comprobando que el proceso vuelve solo: sudo reboot, y al volver, pm2 list.

Pendiente

El <entrypoint> y el nombre de proceso de pm2 start no están estandarizados: cada equipo puede haber quedado distinto. Fijar una convención única es parte de la mejora del proceso.

Hardware y sistema operativo

Hardware	Sistema operativo
Kunbus RevPi Core S (actual)	Distro Bookworm desde packages.revolutionpi.com/bookworm — instalación adicional obligatoria
Raspberry Pi 5 (cuando se agote el stock de RevPi)	Versión LTS del sistema operativo, siempre la edición Lite

Siempre Lite

No se necesita interfaz gráfica en ningún caso.

Configuración adicional del hardware

La configuración específica del dispositivo está a cargo del Ing. Alexander Figueroa.

6. Dar de alta el cliente en m-system

Entrar a app.m-system.cloud con el usuario superadministrador.

El orden importa

Primero se crea todo lo del cliente en la plataforma —usuario, compañía y planta— y después se configura su entorno, incluida la importación del dispositivo. El dispositivo necesita un usuario que ya exista para poder asignárselo.

6.1 Crear usuario, compañía y planta

1. Módulo Usuarios → crear el usuario del cliente. De aquí sale el UUID que se usa en todo el resto del procedimiento.
2. Módulo Compañías → crear la compañía.
3. Módulo Plantas → crear la planta.

6.2 Importar el dispositivo

1. Ir al módulo Gestión de equipos.
2. Botón Importar y cargar tablero.txt. Esto crea el dispositivo.
3. Editar el dispositivo recién creado y asignarle el usuario del paso 6.1.

6.3 Crear el bucket de InfluxDB

Módulo InfluxDB → Crear Nuevo Bucket.

Campo	Valor
Nombre del Bucket	El UUID del usuario, siempre
Descripción	Opcional
Retención	La que indique la solicitud (ver paso 1)
Unidad de tiempo	Días
Tipo de esquema	Implícito
Asignar un usuario a este bucket	Activado, enlazado al usuario del paso 6.1

El nombre del bucket es el UUID, sin excepciones

Es lo que permite rastrear después toda la infraestructura y la configuración del cliente. Un bucket mal nombrado rompe esa trazabilidad. La convención vigente es solo el UUID, sin prefijos ni nombres de cliente.

7. Infraestructura en AWS

Todo vive en la cuenta admin@industriascts.com, región us-east-1.

El orden importa

La cola SQS se crea antes que la regla de IoT Core, porque la regla necesita seleccionar una cola que ya exista.

7.1 SQS — cola de mensajes

Servicio SQS → crear cola.

Campo	Valor
Nombre	UUID del cliente, con guiones
Tipo	Estándar
Tiempo de espera de visibilidad	5 minutos
Periodo de retención del mensaje	4 días
Retraso de entrega	0 segundos
Tamaño máximo del mensaje	1024 KiB
Tiempo de espera de recepción	20 segundos
Cifrado del servidor	Habilitada — clave SSE-SQS

7.2 IoT Core — regla de enrutamiento

Servicio IoT Core → crear una regla de enrutamiento de mensajes.

Campo	Valor
Nombre de la regla	UUID con guiones bajos — 291bd6a4_ee3f_4318_87e1_6152eefb819a
Descripción	Opcional
Versión de SQL	2016-03-23
Instrucción SQL	SELECT * FROM '<uuid-con-guiones>'
Acción 1	Simple Queue Service (SQS)
Nombre de la cola	La creada en 7.1 — https://sqs.us-east-1.amazonaws.com/711387120162/<uuid-con-guiones>
Base64	Desmarcado — no codificar los datos del mensaje
Rol de IAM	IoTRuleRole-INDUSTRIAS_CTS_1 — siempre el mismo, no se crea uno por cliente
Acción de error	No se configura

7.3 Lambda — procesamiento

Servicio Lambda. El procedimiento es replicar una Lambda ya existente, no crearla desde cero.

1. Duplicar una Lambda existente de otro cliente.
2. Nombrarla con el UUID del cliente (con guiones).
3. Conectarle el SQS del paso 7.1 como disparador (trigger).
4. Ajustar las variables de entorno.

Configuración general:

Parámetro	Valor
Memoria	256 MB
Almacenamiento efímero	512 MB
Tiempo de espera	1 min 0 s
SnapStart	None

Variables de entorno (6):

Clave	Cambia por cliente	De dónde sale
INFLUX_DATABASE	✅ Sí	El UUID del cliente — la única variable que se edita
API_BASE_URL	No	https://api.m-system.cloud
INFLUX_HOST	No	https://us-east-1-1.aws.cloud2.influxdata.com
INFLUXDB_TOKEN	No	🔑 Secreto compartido — se hereda al replicar la Lambda
INTERNAL_API_KEY	No	🔑 Secreto compartido — se hereda al replicar la Lambda
SERVICE_JWT_TOKEN	No	🔑 Secreto compartido — se hereda al replicar la Lambda

Solo se toca una variable

Al replicar la Lambda las 6 variables se heredan. La única que hay que editar es INFLUX_DATABASE, con el UUID del cliente nuevo. Si se edita cualquier otra, algo va mal.

Nunca escribir los valores de los secretos aquí

Las tres variables marcadas con 🔑 contienen credenciales. Sus valores no van en este handbook, ni en capturas de pantalla, ni en el repositorio. Si hay que consultarlos, se leen desde la consola de AWS.

Al ser compartidos entre todos los clientes, rotarlos afecta a todas las Lambdas a la vez: no se rota uno sin planificar el cambio en todas. Esto está registrado como riesgo de seguridad en Deuda técnica y riesgos.

8. Verificación

El flujo debe funcionar de punta a punta:

devices-recognizer → IoT Core (regla) → SQS → Lambda → InfluxDB

8.1 Escuchar los mensajes

Usar el cliente MQTT de prueba que ofrece AWS IoT Core (MQTT test client, en la consola).

1. Suscribirse al topic con el UUID del cliente.
2. Dejarlo abierto y monitorear la recepción de mensajes.

8.2 Publicar desde la aplicación

Probar la app devices-recognizer corriendo en el equipo. En su archivo .env, la variable MQTT_TOPIC debe contener el UUID del cliente.

MQTT_TOPIC=<uuid-del-cliente>

Si el UUID del .env no coincide con el del topic de la regla de IoT Core, los mensajes se publican pero no se enrutan a ninguna parte.

8.3 Si algo no llega

Revisar CloudWatch para localizar en qué eslabón se corta el flujo.

9. Qué sale mal normalmente

Síntoma	Qué revisar
El mensaje no llega / el enrutamiento no funciona	La regla de IoT Core. Descartar primero el formato del nombre (guion bajo) y del topic (guiones). Luego la cola seleccionada y el rol de IAM
No hay datos en InfluxDB	INFLUX_DATABASE de la Lambda: debe ser el UUID del cliente. Revisar CloudWatch

Vigilar los recursos asignados

Monitorear qué recursos tiene habilitado cada servicio. Es lo que permite saber cuál es el estándar real al momento de replicar la configuración para el siguiente cliente — si el estándar se desconoce, cada alta queda distinta.

10. Cierre

• Informar al jefe de área (Ing. Juan Carlos Sanguino) que el cliente quedó habilitado.
• Registrar el alta en la tabla de ejecuciones de abajo.

Registro de ejecuciones

Fecha	Cliente	UUID	Quién lo ejecutó	Resultado

Preguntas abiertas

1. Lista completa de datos que debe traer la solicitud para arrancar sin ir a preguntar (paso 1).
2. Convención de despliegue: usuario, ruta destino, <entrypoint> y nombre de proceso de PM2 (pasos 5.2 y 5.3). Hoy no existe.