Guías de instalación · Documentación de Oktavia

Instalación local

La instalación recomendada es con contenedores, incluso en una máquina de trabajo. Esta guía cubre los prerrequisitos comunes y el arranque sin contenedores, que sirve para desarrollar sobre la plataforma. Los comandos exactos y las versiones probadas están en la guía de instalación que se entrega con el software.

Prerrequisitos

Requisito	Para qué
Docker con Compose v2	Los contenedores de los dos componentes y de sus servicios de apoyo
Git	Obtener los dos componentes
Python 3 en la versión indicada en la guía	Entorno del motor y sus herramientas de línea de comandos
PostgreSQL	Base de datos de la interfaz (incluido en sus contenedores)
Node.js (opcional)	Herramientas MCP de escritorio
Ollama (opcional)	Modelo local para Argos; alternativa a la API de Anthropic

Instalar juntos

Los dos componentes deben quedar en el mismo directorio padre, porque sus contenedores comparten almacenamiento:

oktavia/
├── motor/        # Engine
└── interfaz/     # UI

Interfaz sin contenedores (desarrollo)

Crea un entorno virtual e instala las dependencias.
Parte de la configuración de ejemplo y apunta la conexión de base de datos a un PostgreSQL. Es el único motor soportado; no hay alternativa SQLite.
Aplica las migraciones y crea el usuario administrador.
Opcional: crea una organización propia y asígnale usuarios; importa inventario y resultados si ya hay artefactos del motor.
Arranca el servidor de desarrollo.

Motor sin contenedores (desarrollo)

Crea el entorno con la versión de Python indicada e instala las dependencias.
Genera la configuración con la herramienta del motor. Si el componente de interfaz ya está instalado junto a él, la herramienta alinea los tres secretos compartidos y siembra las variables de servicio iniciales.
Carga el inventario desde el CSV de equipos con la herramienta de línea de comandos.
Arranca la API y, por separado, el ejecutor de jobs y el programador. Para correr el pipeline completo desde la línea de comandos hay un script que encadena discovery, respaldo, inventario, generación y compliance.

Producción

Fuera de desarrollo: modo de depuración apagado, secreto de la aplicación persistente, hosts permitidos explícitos, clave de cifrado de la bóveda compartida y respaldada, servidor de aplicación con varios workers y la siembra del laboratorio de demostración desactivada.

Docker Compose

Cada componente trae su propio Compose y se levantan en orden: primero el motor, después la interfaz.

Procesos del motor

Proceso	Función
API	Recibe las peticiones de la UI y de integraciones
Ejecutor de jobs	Toma los jobs de la cola y los corre; recupera los que quedaron en cola si se reinicia
Programador	Tareas programadas con ingesta automática a la UI
Cola	Cola de jobs
Series de tiempo	InfluxDB para las métricas
Recolector	Telegraf para SNMP y syslog, una instancia por organización

Procesos de la interfaz

Proceso	Función
Base de datos	PostgreSQL
Caché	Compartida entre los procesos de la aplicación
Aplicación	La UI
Evaluador de automatización	Evalúa periódicamente las reglas de automatización de eventos
Worker de Argos	Avanza los ciclos de Argos

Hay variantes del Compose para depuración, para incluir un modelo de lenguaje local y para desplegar con imagen preconstruida.

Arranque

Configura los dos componentes a partir de sus configuraciones de ejemplo (ver Variables de entorno).
Levanta el motor y valida que su verificación de salud responde.
Levanta la interfaz y espera a que la base de datos esté sana y la aplicación en marcha. Al arrancar, aplica migraciones, importa artefactos si se le pidió y recoge los estáticos.
Punto de control obligatorio: crea el usuario administrador con el comando de gestión de la UI e inicia sesión.
Sigue con la bóveda de credenciales y con la primera auditoría.

Si la aplicación no arranca por autenticación de base de datos, hay un volumen de PostgreSQL de una instalación anterior con otra contraseña. En una instalación nueva se eliminan los volúmenes y se vuelve a levantar. En una existente, no: eso borra la base.

Variables de entorno

Cada repositorio trae un .env.example con todas sus variables comentadas; esa es la referencia completa y se entrega con el código. Aquí va lo que hay que decidir antes del primer arranque. Por política de publicación, los nombres de las variables que contienen secretos no se documentan en este sitio.

Las tres parejas

Tres secretos deben coincidir entre la UI y el Engine. Si alguno difiere, la instalación arranca pero no funciona, y el síntoma no siempre apunta a la causa.

Pareja	Qué protege	Si no coincide
Clave de API UI→Engine	Las llamadas de la UI al Engine	El Engine rechaza todas las llamadas de la UI
Token Engine→UI	La lectura de la fuente de verdad y la ingesta de resultados	La auditoría no encuentra inventario o la UI no recibe resultados
Clave de cifrado de la bóveda	Las credenciales de los equipos	Las conexiones a los equipos fallan

La herramienta del motor genera los tres y, si el componente de interfaz está instalado junto a él, alinea también su configuración. Si se hace a mano, la clave de cifrado es una clave aleatoria de 32 bytes en base64 segura para URL.

Qué más decidir en la UI

La URL del motor.
La conexión a PostgreSQL.
En producción: modo de depuración apagado, secreto de la aplicación persistente, hosts permitidos y orígenes CSRF explícitos.
El tenant por omisión para los scripts de arranque.
La siembra del laboratorio de demostración, apagada en producción.

Qué más decidir en el Engine

La URL de la UI, para resolver el inventario por tenant.
El token de InfluxDB, que debe existir antes del primer arranque porque InfluxDB se inicializa con él.
La credencial SNMP para Telegraf, o su equivalente en la bóveda.
Las banderas de remediación por carril (FortiGate, FortiSwitch, Junos, Meraki, SD-WAN): todas apagadas por omisión. Se encienden a conciencia, cuando el carril ya se validó en dry-run.
La bandera que activa las plantillas por servicio (v2) en lugar de las legadas por rol.

Qué nunca va al repositorio

Los archivos de configuración con secretos y cualquier archivo con credenciales. El motor acepta credenciales legadas en archivos locales y variables de entorno sólo como ruta de migración hacia la bóveda.

Bóveda de credenciales

Las credenciales con que el Engine entra a los equipos se administran en la UI, en Integraciones → Credenciales, y viajan cifradas al Engine. El modelo está explicado en Seguridad y credenciales; aquí va la operación.

Dar de alta una credencial

Elige el tipo: ssh (Cisco, FortiSwitch), snmp (Telegraf), fortigate (token de API), meraki (clave de Dashboard), bgp (contraseña de vecinos), sdwan (Manager), cml (red de pruebas).
Elige el alcance: global para toda la organización, site con el código de sitio, o device con el nombre del equipo. En la resolución gana la más específica.
Captura usuario y secreto. En los tipos de API agrega los metadatos: URL base, verificación TLS y, si el carril va a aplicar cambios, el permiso de escritura.
Guarda. La UI entrega la bóveda cifrada al motor de inmediato; el motor la detecta sin reiniciar.

Una credencial es única por organización, tipo, alcance y valor de alcance. Se puede desactivar sin borrarla y la UI registra la última rotación.

Migrar desde credenciales en archivos

Si la instalación venía de la etapa en que las credenciales estaban en variables de entorno o en archivos locales del inventario, la UI trae un comando de gestión que las importa a la bóveda: lee la credencial SNMP, la contraseña BGP, el usuario y contraseña SSH y los tokens de FortiGate referenciados en el inventario. Se ejecuta primero en modo de prueba para revisar el resumen y después en firme. Está documentado en la guía que se entrega con el software, junto con los comandos para forzar la exportación y rotar tokens de FortiGate.

Cuando el carril va a escribir

FortiGate: token con permiso de escritura, permiso de escritura en la credencial y la bandera de remediación del carril en el Engine. El apply exige dry-run previo y un respaldo lógico reciente; sólo hace upserts, nunca borra.
Junos: usuario con permiso de configuración y la bandera de NETCONF; el commit confirmed de 10 minutos por omisión revierte si nadie confirma.
Meraki y SD-WAN: clave con escritura, permiso de escritura en la credencial y la bandera de cada carril. Meraki nunca ejecuta DELETE.
Cisco por SSH: el mismo usuario del discovery si tiene privilegio para configurar; el diff se muestra antes de aplicar.

Troubleshooting

Síntomas frecuentes en la instalación y su corrección. Cuando un síntoma apunta a los secretos, revisa primero las tres parejas.

Síntoma	Causa	Corrección
Error de archivo o directorio inexistente al levantar un componente	Los dos componentes no están instalados en el mismo directorio padre	Instalarlos juntos
La UI no puede hablar con el motor (error de autenticación)	La credencial de integración no coincide entre UI y motor	Igualarla y reiniciar
Las conexiones SSH o de API a los equipos fallan sin error claro	La clave de cifrado de la bóveda no coincide	Misma clave en ambos componentes; volver a guardar una credencial para reexportar
La auditoría se rechaza porque no hay reglas de la organización	La organización no tiene intención sincronizada	Guardar una regla desde la UI
El motor está sano, pero la auditoría no encuentra el inventario de la organización	El motor no alcanza la UI por red (frecuente en Linux)	Revisar la resolución de nombres entre contenedores según la guía de instalación
Editar el inventario en archivos del motor no cambia nada	Existe un inventario de la organización con prioridad	Editar el inventario en la UI y sincronizar
Tableros vacíos tras iniciar sesión	La UI aún no ingirió artefactos	Reiniciar la UI o pulsar «Sincronizar resultados»
La aplicación no arranca por autenticación de base de datos	Volumen de PostgreSQL de otra instalación	En instalación nueva, eliminar los volúmenes y volver a levantar
Telegraf no recolecta	SNMP apagado, credencial errónea, ACL o alcance	Probar la recolección en modo prueba; revisar la credencial SNMP, timeouts y que el OID exista en ese fabricante
InfluxDB no recibe datos	Token inválido o definido después del primer arranque	Verificar el token y el bucket; el token va antes del primer arranque
El programador no ejecuta	Proceso caído o configuración inválida	Revisar su estado en la UI y los registros del proceso
Un servicio v2 nunca aparece en la configuración generada	Las plantillas por servicio no están activadas	Activar la bandera correspondiente en el motor
Timeouts de discovery en equipos virtuales lentos	Tiempo de lectura corto	Aumentar el timeout de lectura en las opciones de conexión del inventario
«data missing» tras reemplazar un equipo con la misma IP	Cambió la llave SSH del host	Aceptar la nueva llave desde la UI; el motor guarda las llaves conocidas por organización
Falsos negativos en reglas sobre interfaces	Nombres cortos en la regla, largos en el snapshot	Escribir `GigabitEthernet0/1`, no `gi0/1`