Tienes contenedores repartidos por dos o tres máquinas y ninguna consola que los vea todos sin pagar por nodo. Komodo resuelve ese problema con un servidor central y un agente por máquina, y no cobra por servidor conectado. Esta guía instala Komodo con el compose oficial, añade un segundo host y despliega un stack desde un repositorio de Git.

Puntos clave

  • Komodo tiene dos piezas: Core, que sirve la interfaz y la API en el puerto 9120, y Periphery, un agente pequeño y sin estado en cada máquina gestionada.
  • Desde la versión 2.0 el agente puede iniciar él la conexión hacia Core por websocket, así que el segundo host no necesita ningún puerto abierto hacia dentro.
  • La base de datos es obligatoria: MongoDB es la recomendada, y FerretDB sobre PostgreSQL es la alternativa oficial para sistemas que no toleran MongoDB reciente.
  • La autenticación entre Core y Periphery va con pares de claves generados solos y rotación automática; la clave privada del agente nunca sale del servidor.
  • No hay límite de servidores en la versión libre, ni de compilaciones, ni de usuarios con OIDC y permisos por grupos.

Qué es Komodo y en qué se diferencia del agente de Portainer

Komodo se define en su propia documentación como una aplicación web para gestionar servidores, compilaciones, despliegues y procedimientos automatizados. Está escrita en Rust, se publica bajo licencia GPL-3.0 y el repositorio, abierto en marzo de 2022, acumula 12.120 estrellas y 398 bifurcaciones a finales de agosto de 2026.

La arquitectura tiene dos piezas. Core es el servidor web: guarda la configuración en la base de datos, sirve la interfaz y expone la API. Periphery es un binario pequeño que corre en cada máquina gestionada y ejecuta lo que Core le pide, además de informar del uso de CPU, memoria y disco.

Hasta aquí suena a lo que ya hace el agente de Portainer, pero hay dos diferencias que cambian el despliegue. La primera es la dirección de la conexión: desde la versión 2.0, publicada el 24 de marzo de 2026, Periphery puede iniciar él mismo la conexión hacia Core, de modo que el host remoto no necesita exponer ningún puerto. La segunda es el alcance: Komodo no gestiona solo contenedores, también compila imágenes, clona repositorios, ejecuta procedimientos encadenados y sincroniza toda la configuración desde ficheros TOML versionados.

Qué base de datos elegir

Komodo necesita una base de datos propia, y ahí se acaba la simplicidad de un único contenedor. La documentación es explícita sobre cuál usar: "MongoDB is the recommended database for Komodo. It stores all resource configuration, user accounts, audit logs, and system state". El compose oficial la levanta con --wiredTigerCacheSizeGB 0.25, es decir, con la caché limitada a 256 MB para que no se coma la máquina.

La alternativa oficial es FerretDB, un adaptador que habla el protocolo de MongoDB sobre PostgreSQL. Existe por un motivo concreto: hay sistemas que no pueden ejecutar las versiones recientes de MongoDB, normalmente por falta de instrucciones AVX en el procesador. Si tu servidor arranca MongoDB sin quejarse, quédate con MongoDB; si no, el compose de FerretDB levanta ghcr.io/ferretdb/postgres-documentdb y ghcr.io/ferretdb/ferretdb delante y Core no nota la diferencia.

Opción Cuándo elegirla Contenedores extra
MongoDB Caso normal; es la recomendada por el proyecto 1
FerretDB sobre PostgreSQL Procesadores sin AVX o política de no usar MongoDB 2

Los ficheros de FerretDB llevan un aviso en mayúsculas del propio proyecto: fija una versión concreta de las imágenes, porque las actualizaciones pueden romper la compatibilidad.

Instalar Komodo Core con Docker Compose

El proyecto publica el compose y el fichero de variables por separado, y la instalación consiste en descargarlos, editar las variables y levantar la pila:

  1. Descarga los dos ficheros oficiales en un directorio komodo.
  2. Edita komodo/compose.env y cambia las contraseñas y los dos secretos.
  3. Levanta la pila con el proyecto llamado komodo.
  4. Entra en http://<tu-servidor>:9120 con el usuario administrador inicial.

La descarga usa las rutas del repositorio:

wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/mongo.compose.yaml && \
  wget -P komodo https://raw.githubusercontent.com/moghtech/komodo/main/compose/compose.env

Antes de arrancar nada, abre komodo/compose.env. Trae cuatro valores de ejemplo que hay que cambiar sin excepción, porque el fichero está pensado para que la instalación funcione, no para que sea segura:

## Credenciales de la base de datos
KOMODO_DATABASE_USERNAME=admin
KOMODO_DATABASE_PASSWORD=admin

## Usuario administrador creado en el primer arranque
KOMODO_INIT_ADMIN_USERNAME=admin
KOMODO_INIT_ADMIN_PASSWORD=changeme

## Secretos de firma
KOMODO_WEBHOOK_SECRET=a_random_secret
KOMODO_JWT_SECRET=a_random_jwt_secret

## URL pública, la que verán los navegadores y el proveedor de OIDC
KOMODO_HOST=https://example.komodo.com

Merece la pena insistir en la contraseña del administrador: en la configuración que imprime Core al arrancar aparece min_password_length: 1, así que nadie va a impedirte poner una letra. Después ya sube el resto de opciones a la interfaz.

Con las variables listas, el despliegue es una orden:

docker compose -p komodo -f komodo/mongo.compose.yaml \
  --env-file komodo/compose.env up -d

Ese compose levanta tres contenedores: MongoDB, Core con el puerto 9120 publicado, y un Periphery para gestionar la propia máquina donde vive Komodo.

Qué se ve en el primer arranque

Desplegué esta pila en una máquina arm64 para escribir el artículo, y el registro de Core cuenta la historia mejor que cualquier descripción. Estas son las líneas que importan:

INFO CoreStartup: Komodo Core version: v2.3.2
INFO CoreStartup: Writing private key to "/config/keys/core.key"
INFO CoreStartup: Public Key: MCowBQYDK2VuAyEAUrWvi4QRI5idzuDraZJinZegSXFn+RfI6NeotT+3Z10=
INFO CoreStartup: Creating init admin user...
INFO Server starting on http://[::]:9120

Core genera su par de claves en el primer arranque y crea el usuario administrador que declaraste en las variables. El agente hace lo propio y, acto seguido, marca el detalle que define la versión 2:

INFO PeripheryStartup: Komodo Periphery version: v2.3.2
INFO StartCoreConnection: Initiating outbound connection to ws://core:9120/ws/periphery?server=Local
WARN Failed to connect to websocket | Connection refused (os error 111)
INFO Logged in to Komodo Core core:9120 websocket as Server Local

Ese aviso de conexión rechazada es normal: el agente arranca antes de que Core abra el puerto y reintenta cinco segundos después. La conexión sale del agente hacia el servidor, no al revés.

En reposo, con un solo servidor conectado y sin recursos definidos, el consumo medido fue de 53,2 MiB para Core, 6,8 MiB para Periphery y 132,7 MiB para MongoDB. Por debajo de 200 MiB en total, que para una herramienta de gestión es razonable. Las imágenes arm64 sí ocupan lo suyo: 979 MB la de Core y 649 MB la del agente.

Añadir un segundo host con el agente Periphery

Aquí está el motivo por el que instalas Komodo y no algo más simple. Conectar otra máquina son tres pasos según la documentación: crear una clave de alta desde la interfaz, instalar el agente pasándole esa clave y comprobar que el estado del servidor pasa a OK.

La clave de alta vive en Settings, pestaña Onboarding, y empieza por O-. Con ella en la mano, el proyecto recomienda instalar el agente como servicio de systemd y no dentro de un contenedor, porque el binario necesita ver los procesos del anfitrión y las rutas de los ficheros de compose tal cual están en el disco:

curl -sSL https://raw.githubusercontent.com/moghtech/komodo/main/scripts/setup-periphery.py \
  | python3 - \
  --core-address="https://komodo.ejemplo.com" \
  --connect-as="$(hostname)" \
  --onboarding-key="O-..."

Después conviene dejarlo activado para que sobreviva a un reinicio con sudo systemctl enable periphery. El fichero de configuración queda en /etc/komodo/periphery.config.toml para la instalación como root, o en $HOME/.config/komodo/periphery.config.toml para la instalación de usuario.

Lo que ocurre por debajo es lo interesante. La clave de alta se usa una única vez: en la primera conexión el agente genera su propio par de claves y envía a Core solo la pública. A partir de ahí toda la comunicación se autentica con un handshake criptográfico del marco Noise[1], comprobando que la clave pública transmitida coincide. La clave privada del agente nunca sale de esa máquina, y auto_rotate_keys viene activado por defecto, así que Komodo puede renovar los pares de claves de todos los servidores cuando se lo pidas.

Si prefieres el contenedor, el compose del agente existe y la variable importante es PERIPHERY_CORE_ADDRESS. Y si tu red te obliga al modelo clásico, Core también puede conectarse hacia el agente: en ese caso Periphery escucha en el puerto 8120 y tendrás que abrirlo.

Una restricción que sorprende a mucha gente: todos los ficheros de compose y todos los repositorios tienen que colgar de root_directory, que por defecto es /etc/komodo, y esa ruta debe coincidir dentro y fuera del contenedor si instalas el agente contenerizado. Si no coinciden, Docker se pierde.

Desplegar un stack desde un repositorio de Git

Un Stack en Komodo es un despliegue de docker compose, y admite tres formas de aportar el fichero: escribirlo en la interfaz, apuntar a ficheros que ya están en el servidor, o clonar un repositorio de Git. La tercera es la que justifica la herramienta, y la documentación la resume así: "Komodo clones the repo onto the host to deploy. Changes are tracked in git and you can use webhooks to auto-redeploy on push".

Diagrama del flujo de despliegue de Komodo: un push en Git dispara un webhook a Komodo Core, que ordena al agente Periphery ejecutar docker compose up en el host remoto.

La configuración pide el servidor de destino, la cuenta de Git, el repositorio en formato propietario/repo y la rama. Las cuentas de Git y de los registros de imágenes se declaran en Settings, en la pestaña de proveedores, o en el fichero de configuración de Core:

[[git_provider]]
domain = "github.com"
https = true
accounts = [{ username = "mi-usuario", token = "ghp_xxxxxxxxxxxx" }]

[[image_registry]]
domain = "docker.io"
accounts = [{ username = "mi-usuario", token = "dckr_pat_xxxxxxxxxxxx" }]

Los testigos declarados en el fichero aparecen luego en la interfaz, pero no se pueden leer de vuelta ni por la API ni por la pantalla. Además del webhook, cada stack tiene dos ajustes de actualización que conviene entender antes de activarlos: uno vigila si hay imágenes nuevas y enciende un indicador, y el otro redespliega solo cuando aparece una firma nueva.

Inicio de sesión con OIDC y permisos por grupos

Komodo admite usuario y contraseña, GitHub, Google y cualquier proveedor OIDC genérico. La configuración se reduce a cinco variables, y si tu proveedor implementa PKCE puedes omitir el secreto:

KOMODO_OIDC_ENABLED=true
KOMODO_OIDC_PROVIDER=https://sso.ejemplo.com/application/o/komodo
KOMODO_OIDC_CLIENT_ID=komodo
KOMODO_OIDC_CLIENT_SECRET=...
KOMODO_DISABLE_USER_REGISTRATION=true

Si ya tienes Authentik montado como proveedor de identidad, la integración es la habitual: creas la aplicación, copias identificador y secreto, y desde la versión 2.2 puedes activar la redirección automática al proveedor para que la pantalla de contraseña ni aparezca.

Los permisos se conceden por grupos, y la documentación lo recomienda por encima de asignarlos usuario a usuario: los usuarios se añaden a varios grupos y heredan lo que el grupo tenga. Los niveles son cuatro y forman una escalera:

  • None: el usuario ni ve el recurso en la interfaz ni lo obtiene si consulta la API directamente.
  • Read: lo ve y puede revisar la configuración, sin tocar nada.
  • Execute: dispara acciones como compilar o redesplegar, pero no cambia la configuración.
  • Write: acceso completo, incluida la eliminación del recurso.

Por encima hay permisos específicos que se conceden aparte, como el acceso a registros, a la inspección, a la terminal o a los procesos del servidor. Y si prefieres cerrar del todo la puerta, el agente admite PERIPHERY_DISABLE_TERMINALS=true para que no exista acceso a la consola aunque alguien tenga el permiso.

Qué te cuesta cada opción

La cuenta es la parte fácil de esta comparación. Portainer Business Edition es gratis para siempre hasta tres nodos y a partir de ahí el plan Starter arranca en 105 dólares al mes. Komodo lo pone por escrito en la primera página de su documentación: "There is no limit to the number of servers you can connect, and there never will be".

Komodo v2.3.2 Portainer
Servidores gratis Sin límite 3 en la edición de negocio
Sentido de la conexión El agente llama al servidor, o al revés El servidor llama al agente
Base de datos aparte Sí, MongoDB o FerretDB No
Compilación de imágenes Incluida No
Configuración declarativa Ficheros TOML versionados Parcial
Curva de entrada Alta Baja

Donde Komodo pierde es en todo lo demás. Son dos binarios más una base de datos, hay nueve tipos de recurso que entender antes de sentirte cómodo, y la comunidad es una fracción de la de Portainer, con lo que eso significa cuando buscas un mensaje de error concreto a las once de la noche. Si lo único que quieres es reiniciar contenedores desde el móvil, esto es demasiada máquina.

Preguntas frecuentes

¿Necesito abrir puertos en el segundo servidor?

No, si usas el modo saliente. Desde la versión 2.0 el agente inicia la conexión hacia Core por websocket, así que basta con que la máquina remota alcance tu servidor de Komodo. El puerto 8120 solo hace falta en el modo clásico, cuando es Core quien llama al agente.

¿Puedo usar PostgreSQL en lugar de MongoDB?

Sí, con el compose de FerretDB, que traduce el protocolo de MongoDB sobre PostgreSQL. El proyecto lo ofrece sobre todo para máquinas donde MongoDB reciente no arranca. Si MongoDB funciona en tu servidor, es la opción recomendada.

¿Komodo sirve para un clúster de Swarm?

Sí desde la versión 2.0. Conectas los nodos gestores y desde ahí administras nodos, servicios, stacks, configuraciones y secretos del clúster. Si estás montando la parte de red, viene bien tener Traefik ya resuelto.

Conclusión

Instalar Komodo son dos ficheros y una orden de compose; entenderlo cuesta bastante más. Lo que compras con esa curva es una consola que no cobra por servidor, que despliega desde Git con webhook, que compila imágenes y que guarda toda la configuración en TOML versionado. Si vienes de Portainer y solo tienes dos máquinas, seguramente no lo necesites. Si tienes seis, ya empieza a salir la cuenta. La comparación completa entre las tres opciones está en Komodo frente a Portainer y Dockge, y la versión en inglés de esta guía en How to install Komodo with Docker.

Fuentes

  1. marco Noise
  2. Komodo, qué es Komodo
  3. moghtech/komodo, repositorio del proyecto
  4. Komodo, instalación con MongoDB
  5. Komodo, conectar más servidores
  6. Komodo, permisos y grupos
  7. Portainer, precios y nodos gratuitos