Solución de problemas de instalación

El instalador comprueba cada paso y muestra una línea por verificación:

PASS  NET-01  ims.mi-empresa.ma resuelve a este servidor
WARN  PRE-06  el reloj no está sincronizado por NTP
FAIL  KC-01   el servicio de autenticación anuncia otra dirección

El identificador (NET-01, KC-01…) significa lo mismo en todas partes. Cítelo en cualquier solicitud de soporte. El archivo TROUBLESHOOTING.md del paquete da, para cada uno, la causa detallada y los comandos de corrección; esta página da su significado y la primera acción.

Ejecutar el diagnóstico

El diagnóstico no modifica nada y puede ejecutarse en producción. Ejecuta todas las verificaciones, sin detenerse en el primer error, y termina con el código 0 si todo va bien, 1 si no: por eso puede programarse.

Linux

./install.sh --doctor

Windows

.\install.ps1 -Doctor

Ejecútelo tras un reinicio, una actualización, una renovación de certificado, o cuando algo parezca anormal.

Reglas que evitan la mayoría de los fallos

• No modifique a mano los valores deducidos de la configuración (direcciones de la autenticación, orígenes autorizados). Cambie el nombre de host o el protocolo volviendo a ejecutar el instalador: reescribe todo lo que depende de ellos.
• No cambie nunca las contraseñas de las bases en .env.
• Ejecute siempre los comandos desde el directorio de instalación.

PRE · Requisitos

Identificador	Qué se verifica	Primera acción
PRE-01	Docker responde	Arrancar Docker (en Windows, Docker Desktop solo arranca tras iniciar sesión)
PRE-02	Docker Compose v2 presente	Instalar el complemento Compose v2; el antiguo docker-compose no basta
PRE-03	4 GB de memoria para Docker	Añadir memoria; en Windows, aumentar la memoria asignada a WSL2
PRE-04	20 GB de disco libre	Liberar espacio (imágenes antiguas, copias antiguas)
PRE-05	Puertos 80 y 443 libres	Detener el servicio que los ocupa (otro servidor web, IIS, VPN)
PRE-06	Reloj sincronizado	Activar la sincronización NTP: un reloj desfasado hace fallar los inicios de sesión
PRE-07	Bases de datos de una instalación anterior	Conservar los datos reutilizando las credenciales antiguas, o borrarlos solo tras una copia
PRE-08	Servidor de licencias accesible	Permitir la salida HTTPS, o usar un archivo de licencia
PRE-09	Integridad del paquete	Volver a copiar el paquete: un archivo se alteró en la transferencia
PRE-10	Restos de una instalación anterior	Informativo en las versiones recientes

CFG · Configuración

Identificador	Qué se verifica	Primera acción
CFG-01	Configuración escrita desde la plantilla	Usar el instalador y la plantilla del mismo paquete
CFG-02	Ninguna variable sin resolver	Volver a ejecutar el instalador, que reescribe los valores deducidos
CFG-03	Respuesta que falta (instalación sin preguntas)	Completar el archivo de respuestas
CFG-04	Resumen y respuestas guardados	Ejecutar el instalador con un usuario que pueda escribir en el directorio
CFG-05	Respuesta no válida	Corregir el valor indicado (nombre de host, correo, zona horaria…)
CFG-06	Configuración conforme a la versión	Volver a ejecutar el instalador: añade lo que falta y conserva los secretos
CFG-07	Valores deducidos coherentes con el nombre de host	Volver a ejecutar el instalador; no corregir esos valores uno a uno
CFG-08	El sitio HTTPS usa el nombre de host correcto	Volver a ejecutar el instalador tras un cambio de nombre de host
CFG-09	Ajustes de servidor compartido coherentes	Afecta a servidores con varias instalaciones; contacte con el soporte

IMG · Imágenes

Identificador	Qué se verifica	Primera acción
IMG-01	Imágenes cargadas desde el paquete	Verificar el espacio en disco y la integridad del paquete
IMG-02	Descarga de imágenes	Para un servidor sin acceso al registro, pedir un paquete con imágenes integradas
IMG-03	Imágenes de la versión presentes	Cargar exactamente la versión indicada; no pasar nunca a «latest»

TLS · Certificados

Identificador	Qué se verifica	Primera acción
TLS-01	Certificado Let's Encrypt obtenido	Verificar que el nombre DNS apunta al servidor y que el puerto 80 es accesible desde Internet
TLS-02	Certificado existente en su sitio	Colocar el certificado y la clave en la ubicación esperada
TLS-03	Configuración para HTTPS gestionado por su proxy	Proporcionar la configuración de su proxy
TLS-04	Validez del certificado	Relanzar la renovación; aviso 21 días antes de la caducidad
TLS-05	Renovación automática activa	Reiniciar el servicio de renovación

RUN · Arranque

Identificador	Qué se verifica	Primera acción
RUN-00	Arranque de la aplicación	Leer la causa mostrada: puerto ocupado, valor que falta, imagen ausente
RUN-01	Todos los componentes arrancados	—
RUN-02	Cada componente existe	Ejecutar los comandos desde el directorio de instalación
RUN-03	Cada componente está sano	Esperar durante el primer arranque (3 a 5 minutos) y luego leer los registros

API, DB, KC, WEB · Aplicación

Identificador	Qué se verifica	Primera acción
API-01	Los servicios de aplicación responden	Leer el registro de los servicios: el primer error nombra la causa
API-02	El navegador puede llamar a la API	Volver a ejecutar el instalador (vea CFG-07)
DB-01	Migraciones de la base correctas	Dejar de usar la instalación: restaurar la copia previa a la actualización y contactar con el soporte
DB-02	Base conforme a la versión	No modificar nada a mano; contactar con el soporte
DB-03	Las bases pueden reconstruirse	Restablecer las credenciales originales de las bases
KC-01	Dirección anunciada por la autenticación	Volver a ejecutar el instalador (vea CFG-07): provoca inicios de sesión rechazados sin fin
KC-02	Autenticación preparada en el primer arranque	Leer el registro del primer arranque
KC-03	La consola web es conocida por la autenticación	Seguir la corrección de TROUBLESHOOTING.md
WEB-01	La consola web responde	Verificar que la consola está en marcha

LIC, SEC, NET · Licencia, acceso, red

Identificador	Qué se verifica	Primera acción
LIC-00	Archivo de licencia dado en la instalación	Activar la licencia tras iniciar sesión
LIC-01	Licencia activa	Iniciar sesión como administrador y activar la licencia; sin ella, la aplicación sigue en modo restringido
LIC-02	Almacenamiento de la licencia	Volver a colocar el archivo de licencia; verificar los permisos de escritura
SEC-01	Direcciones autorizadas para las consolas de administración	Informativo: sin direcciones, siguen cerradas
SEC-02	Lista de autorización presente	Restaurarla desde el paquete: sin ella, todo el sitio está caído
NET-01	El nombre de host apunta a este servidor	Corregir el registro DNS; el nombre debe resolverse también desde el propio servidor

UPG · Actualización

Identificador	Qué se verifica	Primera acción
UPG-01	El destino es una instalación	Apuntar la actualización al directorio de instalación, no al paquete
UPG-02	La actualización va a una versión más reciente	Usar el paquete más reciente; se rechazan los retrocesos
UPG-03	La autenticación no se degrada nunca	Nada que hacer
UPG-04	Copia previa a la actualización	Liberar espacio; no se modificó nada
UPG-05	Archivos del paquete sustituidos	Corregir espacio o permisos y volver a ejecutar
UPG-06	Configuración fusionada	Leer el mensaje; ejecutar después el diagnóstico
UPG-07	Configuración HTTPS actualizada	Si la había modificado a mano, trasladar los cambios de la nueva versión

Vea Actualizaciones y copias de seguridad para volver a la versión anterior.

Contactar con el soporte

Adjunte a su solicitud:

• los identificadores en FAIL o WARN del diagnóstico;
• la versión instalada (archivo VERSION);
• el registro de la ejecución correspondiente, en install/logs/.

No envíe nunca .env ni install-summary.txt: contienen secretos.