Harbor Docker Compose: Registro Privado con Escaneo 2026

Montar Harbor Docker Compose te da un registro de imágenes privado con escaneo de vulnerabilidades, firma de artefactos, control de acceso por proyectos y replicación hacia otros registros. Es lo que usarías si quieres dejar de depender de Docker Hub y de sus límites de descarga sin perder funcionalidad.

Un aviso de partida: no se instala pegando un docker-compose.yml. Harbor trae su propio instalador que genera ese fichero a partir de tu configuración, y entender esa diferencia te ahorra bastante frustración.

Qué aporta Harbor Docker Compose frente a un registro simple

Levantar el registro oficial de Docker es cosa de cinco líneas, pero te deja sin interfaz, sin usuarios, sin permisos y sin ninguna idea de qué vulnerabilidades arrastran tus imágenes. Ahí es donde entra Harbor Docker Compose: un proyecto graduado de la CNCF que cubre justo ese hueco.

La diferencia se nota sobre todo el día que alguien pregunta «¿qué versión de esta librería tenemos desplegada y tiene el fallo crítico del que habla la prensa?». Con un registro simple, la respuesta es un rato largo de investigación manual; aquí es una búsqueda en la interfaz.

Esa última fila importa: es una plataforma completa, no un contenedor suelto. Si solo quieres guardar imágenes en casa, te sobra con el registro básico. Si quieres controlar qué se despliega y con qué fallos conocidos, entonces sí compensa.

Requisitos previos de Harbor Docker Compose

Harbor Docker Compose necesita además un nombre de dominio y un certificado TLS. Esto no es opcional como en otros servicios: Docker se niega a autenticarse contra registros en claro salvo que lo declares como inseguro en cada cliente, y eso es exactamente lo que no quieres hacer.

Instalar Harbor Docker Compose paso a paso

Paso 1: descargar el instalador

El instalador de Harbor Docker Compose tiene dos variantes: la online, más ligera, que descarga las imágenes al instalar, y la offline, que las trae dentro y sirve para servidores sin salida a Internet.

cd /opt
sudo curl -LO https://github.com/goharbor/harbor/releases/download/v2.15.0/harbor-online-installer-v2.15.0.tgz
sudo tar xzvf harbor-online-installer-v2.15.0.tgz
cd harbor

No borres este directorio después de instalar: aquí viven la configuración y los scripts que necesitarás para actualizar o reconfigurar.

Paso 2: preparar los certificados

Si ya tienes certificados de Let’s Encrypt para tu dominio, cópialos donde el instalador pueda leerlos.

sudo mkdir -p /data/cert
sudo cp /etc/letsencrypt/live/registro.midominio.es/fullchain.pem /data/cert/
sudo cp /etc/letsencrypt/live/registro.midominio.es/privkey.pem /data/cert/
sudo chmod 600 /data/cert/privkey.pem

Si prefieres delegar el TLS en un proxy inverso como Traefik, puedes configurar Harbor en HTTP interno y terminar el cifrado fuera. Funciona, pero exige ajustar bien la URL externa o las subidas de imágenes fallarán a mitad.

Paso 3: configurar harbor.yml

Harbor Docker Compose trae una plantilla de configuración que hay que renombrar antes de tocarla.

sudo cp harbor.yml.tmpl harbor.yml
sudo nano harbor.yml

Estos son los valores que debes revisar sin excepción:

hostname: registro.midominio.es

https:
  port: 443
  certificate: /data/cert/fullchain.pem
  private_key: /data/cert/privkey.pem

harbor_admin_password: una-contrasena-larga-y-unica

database:
  password: otra-contrasena-distinta

data_volume: /data

trivy:
  ignore_unfixed: false
  skip_update: false

Paso 4: instalar con escaneo activado

El escáner de vulnerabilidades de Harbor Docker Compose no viene por defecto: hay que pedirlo con una opción. Actívalo, porque es la mitad del valor de todo esto.

sudo ./install.sh --with-trivy

El script de Harbor Docker Compose valida la configuración, genera el docker-compose.yml definitivo y levanta la pila. Cuando termine, comprueba el estado con los comandos habituales desde ese mismo directorio.

sudo docker compose ps
sudo docker compose logs -f core

Entra en https://registro.midominio.es con el usuario admin y la contraseña que pusiste. Lo primero, crea un proyecto y un usuario robot para tus pipelines; el administrador no debería usarse en automatismos.

Paso 5: subir tu primera imagen

docker login registro.midominio.es
docker tag mi-app:1.0 registro.midominio.es/produccion/mi-app:1.0
docker push registro.midominio.es/produccion/mi-app:1.0

En cuanto termine la subida verás la imagen en la interfaz y, si dejaste el escaneo automático activo en el proyecto, el análisis arrancará solo. La primera vez tarda porque Trivy descarga su base de datos de vulnerabilidades.

Escaneo y políticas en Harbor Docker Compose

Escanear sin actuar no sirve de nada, y Harbor Docker Compose lo tiene resuelto. La función que cambia las cosas se llama prevención de despliegue: dentro de la configuración del proyecto puedes impedir que se descarguen imágenes cuya severidad supere un umbral.

Actívala en «Crítica» para empezar. Si la pones en «Media» el primer día, te encontrarás con que media plantilla no puede desplegar nada y acabarás desactivándola entera, que es el peor resultado posible.

• Escaneo automático al subir, para que ninguna imagen entre sin analizar.
• Reglas de retención, conservando por ejemplo las diez últimas etiquetas de cada repositorio.
• Recolección de basura programada, que es lo único que libera espacio de verdad en disco.
• Inmutabilidad de etiquetas en producción, para que nadie reescriba una versión ya desplegada.

Ese mismo Trivy es el que usa el operador de escaneo de vulnerabilidades en Kubernetes, así que si ya lo tienes en el clúster, tendrás criterios coherentes en las dos puntas: al guardar la imagen y al ejecutarla.

Merece la pena entender qué significa realmente el resultado de un escaneo, porque los números asustan más de lo que deberían. Un informe con ciento veinte vulnerabilidades no quiere decir que tu aplicación tenga ciento veinte agujeros: la inmensa mayoría vienen de paquetes del sistema base y muchas ni siquiera tienen corrección disponible todavía.

De ahí la opción ignore_unfixed de la configuración. Si la activas, el informe solo muestra lo que puedes arreglar de verdad actualizando, y el ruido baja muchísimo. Es tentador ponerla desde el principio, aunque yo prefiero dejarla desactivada al menos las primeras semanas: ver el panorama completo ayuda a decidir si tu imagen base es la adecuada. Cambiar de una imagen genérica a una variante alpine o slim suele recortar el recuento a la mitad sin tocar una línea de código.

La otra pieza que conviene activar pronto es la firma de imágenes con Cosign, del proyecto Sigstore. Escanear te dice qué hay dentro; firmar te dice que lo que despliegas es exactamente lo que tu integración continua construyó y que nadie lo ha sustituido por el camino. Son dos protecciones distintas y complementarias.

El flujo típico es firmar en el último paso del pipeline, justo después de publicar la imagen, y exigir firma válida en el proyecto de producción. A partir de ahí, una imagen sin firmar sencillamente no se puede descargar desde ese proyecto, por mucho que exista en el registro. Es una barrera sencilla de montar y sorprendentemente eficaz contra despliegues accidentales de artefactos que nunca pasaron por el proceso.

Integrar Harbor Docker Compose en tu flujo

Harbor Docker Compose cobra sentido cuando lo alimenta tu integración continua. Con un usuario robot y su token, cualquier sistema puede publicar sin credenciales personales de por medio.

  - name: publicar imagen
    image: woodpeckerci/plugin-docker-buildx
    settings:
      repo: registro.midominio.es/produccion/mi-app
      registry: registro.midominio.es
      tags: [ "1.0", latest ]
      username:
        from_secret: harbor_robot
      password:
        from_secret: harbor_token

Ese fragmento encaja directamente en el servidor de integración continua con Woodpecker que vimos hace unos días. Del otro lado, tu clúster necesitará un secreto de tipo docker-registry para poder descargar imágenes privadas.

Proyectos, roles y usuarios robot

La unidad organizativa de Harbor Docker Compose es el proyecto, y conviene diseñarlo antes de empezar a subir cosas. Cada proyecto tiene su visibilidad, sus miembros, sus políticas de escaneo y sus reglas de retención propias.

Una organización sencilla que funciona bien: un proyecto desarrollo con reglas laxas donde cualquiera publica, y un proyecto produccion con etiquetas inmutables, prevención de despliegue activada y donde solo escribe la integración continua. Las imágenes pasan de uno a otro mediante replicación cuando se aprueban.

Para los automatismos, usa siempre cuentas robot en lugar de usuarios personales. Se crean por proyecto, tienen permisos acotados y caducidad, y sobre todo se pueden revocar sin romperle el acceso a nadie. Si un token robot se filtra, lo anulas y generas otro en treinta segundos; si se filtra la contraseña de un administrador, el problema es de otro tamaño.

Mantenimiento de Harbor Docker Compose y fallos típicos

El primero es el fallo más común de Harbor Docker Compose con diferencia. Borrar una etiqueta en la interfaz solo quita la referencia; las capas siguen ocupando disco hasta que se ejecuta la recolección de basura, que además requiere poner el registro en modo de solo lectura mientras dura.

Para las copias de seguridad, respalda el volumen de datos y la base de datos, y guarda también el harbor.yml: sin él, reconstruir la instalación es mucho más engorroso. Puedes automatizarlo con Duplicati y copias cifradas.

Una advertencia sobre el tamaño de esas copias: el volumen de datos crece hasta donde le dejes, y respaldar cientos de gigas de capas de contenedor cada noche no tiene mucho sentido. Casi todas esas imágenes se pueden reconstruir desde el código, así que lo verdaderamente irreemplazable es la base de datos —usuarios, proyectos, permisos, políticas e historial de escaneos— junto con el fichero de configuración. Yo respaldaría eso a diario y el volumen de artefactos con mucha menos frecuencia, o solo el proyecto de producción.

Conclusión sobre Harbor Docker Compose

Harbor Docker Compose no es un servicio para instalar por curiosidad: consume varios gigas y tiene mantenimiento real. Pero si publicas imágenes con cierta frecuencia, saber qué vulnerabilidades llevan dentro antes de que lleguen a producción cambia bastante las cosas, y hacerlo con una política automática cambia más todavía.

Empieza tu Harbor Docker Compose con un proyecto, el escaneo automático activado y la prevención en «Crítica». Cuando lleves unas semanas y sepas cómo está tu catálogo, aprieta el umbral. Tienes la documentación en la guía oficial de instalación, las descargas en las versiones publicadas en GitHub, el escáner en la web de Trivy, el proyecto en la ficha de la CNCF y más ideas en los tutoriales de Docker Compose.

Preguntas frecuentes sobre Harbor Docker Compose