Configuración de un Docker Registry privado (

Qué configuramos y por qué

Configuraremos Harbor, un potente registro de contenedores privado, basado en la nube y de código abierto, que almacena, firma y escanea imágenes. Harbor extiende la funcionalidad del Docker Registry estándar, añadiéndole características empresariales como seguridad, gestión de proyectos, control de acceso basado en roles (RBAC), escaneo de vulnerabilidades, replicación de imágenes e integración con LDAP/AD. Esta solución permite a los equipos de desarrollo gestionar de forma segura sus imágenes de contenedor, garantizando su integridad y el cumplimiento de los estándares corporativos.

Al final, obtendrá un Docker Registry privado completamente funcional, seguro y gestionado, que servirá como repositorio central para todas sus imágenes de contenedor. Esto es especialmente importante para los pipelines de CI/CD, donde las imágenes deben estar disponibles de forma rápida y fiable, así como para entornos donde se requiere un control estricto sobre lo que se despliega. Podrá almacenar imágenes propietarias, protegerlas del acceso no autorizado, escanearlas en busca de vulnerabilidades antes del despliegue y controlar quién puede publicar o extraer imágenes.

¿Qué alternativas existen? Se pueden utilizar servicios gestionados en la nube, como AWS ECR, Google Container Registry (GCR) / Artifact Registry, Azure Container Registry (ACR) o GitLab Container Registry. Estos ofrecen comodidad, escalabilidad y a menudo están integrados con otros servicios en la nube. Sin embargo, una solución autoalojada en un VPS tiene sus ventajas:

• Control total: Usted controla completamente los datos, la seguridad y la infraestructura. Esto es fundamental para empresas con estrictos requisitos regulatorios o para aquellas que no quieren depender de un proveedor de nube específico.
• Eficiencia económica: Para volúmenes medios y grandes de almacenamiento y tráfico, una solución autoalojada puede ser significativamente más barata que las alternativas en la nube, especialmente si ya dispone de recursos libres en un servidor VPS/dedicado.
• Personalización: Posibilidad de ajustar la configuración a las necesidades específicas de su infraestructura, integración con sistemas de autenticación internos o herramientas de seguridad únicas.
• Privacidad: Las imágenes se almacenan en su infraestructura, lo que reduce los riesgos de fuga de datos a través de servicios de terceros.

La elección de Harbor autoalojado en un VPS es ideal para equipos que necesitan un equilibrio entre control, seguridad y coste, así como para aquellos que desean evitar el bloqueo de proveedor.

Qué configuración de VPS se necesita para esta tarea

La elección de la configuración correcta del servidor es fundamental para el funcionamiento estable y productivo de Harbor. Harbor no es solo un almacén, sino un conjunto completo de servicios (PostgreSQL, Redis, Notary, Clair, Trivy, Portal) que consumen recursos.

Requisitos mínimos (para equipos pequeños / entornos de prueba):

• CPU: 2 núcleos. Harbor realiza muchas tareas en segundo plano, como el escaneo de vulnerabilidades, lo que puede consumir muchos recursos.
• RAM: 4 GB. Este es el mínimo absoluto, se recomiendan 6-8 GB para un funcionamiento estable de todos los componentes.
• Disco: 100 GB SSD. El consumo principal de espacio en disco se destina al almacenamiento de imágenes. Un SSD acelera significativamente las operaciones de archivos y bases de datos.
• Red: 100 Mbit/s. Para un uso inicial es suficiente, pero para un trabajo activo de CI/CD o un gran número de usuarios se necesitará un canal más amplio.

Plan de VPS recomendado (para entornos de producción de carga media):

• CPU: 4 núcleos. Proporcionará un rendimiento suficiente para procesar solicitudes, escaneos y tareas en segundo plano.
• RAM: 8-16 GB. Permitirá que todos los componentes de Harbor funcionen sin intercambio de memoria (swapping), lo cual es crítico para el rendimiento.
• Disco: 250-500 GB NVMe/SSD. El volumen depende de la cantidad y el tamaño de las imágenes almacenadas. NVMe ofrece la máxima velocidad de E/S. Es importante elegir un disco con capacidad de expansión o utilizar almacenamiento externo si se planea almacenar muchas imágenes.
• Red: 1 Gbit/s. Un canal de alta velocidad es necesario para la carga y descarga rápida de imágenes, lo que afecta significativamente el tiempo de compilación y despliegue.

Para alquilar un VPS con las características indicadas, por ejemplo, 4 núcleos de CPU, 8-16 GB de RAM, 250-500 GB NVMe/SSD y una red de 1 Gbit/s, puede considerar un VPS con las características indicadas.

Cuándo se necesita un servidor dedicado, no un VPS

Un servidor dedicado se convierte en la opción preferida cuando:

• Carga muy alta: Si planea almacenar miles de imágenes, atender a cientos de desarrolladores, o su pipeline de CI/CD está constantemente subiendo/bajando imágenes.
• Requisitos de rendimiento: Cuando se requiere un rendimiento garantizado de CPU, RAM y subsistema de disco sin el "efecto vecino ruidoso" (noisy neighbor) de otros usuarios en el mismo hipervisor.
• Gran volumen de almacenamiento: Si necesita varios terabytes para imágenes y almacenamiento a largo plazo.
• SLA estrictos y aislamiento: Para sistemas críticos donde se requiere el máximo aislamiento y control sobre el hardware.

En tales casos, un servidor dedicado adecuado proporcionará la potencia y fiabilidad necesarias.

Ubicación: cómo influye

La ubicación de su VPS o servidor dedicado influye en varios factores:

• Latencia (ping): Cuanto más cerca esté el servidor de sus desarrolladores y agentes de CI/CD, menor será la latencia al cargar/descargar imágenes. Esto afecta directamente la velocidad de trabajo.
• Regulaciones regionales: En algunos casos, debido a la legislación (por ejemplo, GDPR), los datos deben almacenarse en una región geográfica específica.
• Costo: Los precios de los VPS pueden variar según la región.

Elija una ubicación que minimice la latencia para la mayoría de sus usuarios y cumpla con todos los requisitos legales.

Preparación del servidor

Se asume que está utilizando un servidor recién instalado con Ubuntu 24.04 LTS. Estos pasos garantizarán la seguridad básica y prepararán el sistema para la instalación de Harbor.

1. Actualización del sistema

Siempre comience actualizando el gestor de paquetes y los paquetes instalados para asegurarse de que el sistema esté actualizado y que las últimas correcciones de seguridad estén disponibles.

sudo apt update             # Actualizar la lista de paquetes
sudo apt upgrade -y         # Actualizar todos los paquetes instalados
sudo apt autoremove -y      # Eliminar paquetes no utilizados

2. Creación de un nuevo usuario y configuración de claves SSH

No se recomienda trabajar con la cuenta de root. Cree un nuevo usuario con privilegios sudo y configure la autenticación por claves SSH para mejorar la seguridad.

sudo adduser harboradmin    # Crear un nuevo usuario "harboradmin"
sudo usermod -aG sudo harboradmin # Añadir el usuario al grupo sudo
sudo mkdir /home/harboradmin/.ssh # Crear el directorio para las claves SSH
sudo chmod 700 /home/harboradmin/.ssh # Establecer los permisos correctos
sudo cp ~/.ssh/authorized_keys /home/harboradmin/.ssh/ # Copiar su clave pública
sudo chown -R harboradmin:harboradmin /home/harboradmin/.ssh # Establecer el propietario del directorio

Importante: Después de realizar estos pasos, cierre la sesión actual de root e inicie sesión con el nuevo usuario harboradmin, utilizando su clave SSH. Luego, desactive el inicio de sesión con contraseña para root y usuarios normales en el archivo /etc/ssh/sshd_config.

sudo nano /etc/ssh/sshd_config

Busque y modifique las siguientes líneas:

PermitRootLogin no
PasswordAuthentication no
ChallengeResponseAuthentication no
UsePAM no

Reinicie el servicio SSH para aplicar los cambios:

sudo systemctl restart sshd

3. Instalación y configuración del Firewall (UFW)

Configure un firewall básico para permitir solo los puertos necesarios. Harbor utilizará los puertos 80 (HTTP, para redirección), 443 (HTTPS) y posiblemente otros para servicios internos.

sudo apt install ufw -y     # Instalar UFW
sudo ufw default deny incoming # Denegar todas las conexiones entrantes por defecto
sudo ufw default allow outgoing # Permitir todas las conexiones salientes por defecto
sudo ufw allow OpenSSH      # Permitir SSH (puerto 22)
sudo ufw allow http         # Permitir HTTP (puerto 80)
sudo ufw allow https        # Permitir HTTPS (puerto 443)
sudo ufw enable             # Habilitar UFW
sudo ufw status verbose     # Verificar el estado de UFW

4. Instalación de Fail2Ban

Fail2Ban ayuda a proteger contra ataques de fuerza bruta en SSH y otros servicios.

sudo apt install fail2ban -y # Instalar Fail2Ban
sudo systemctl enable fail2ban # Habilitar el inicio automático de Fail2Ban
sudo systemctl start fail2ban  # Iniciar Fail2Ban
sudo cp /etc/fail2ban/jail.conf /etc/fail2ban/jail.local # Crear configuración local

Abra /etc/fail2ban/jail.local y asegúrese de que la sección [sshd] esté activa (enabled = true) y configure los parámetros a su gusto (por ejemplo, bantime, findtime, maxretry).

sudo nano /etc/fail2ban/jail.local

Ejemplo de configuración:

[sshd]
enabled = true
port = ssh
logpath = %(sshd_log)s
backend = %(sshd_backend)s
bantime = 1h
findtime = 10m
maxretry = 5

Reinicie Fail2Ban para aplicar los cambios:

sudo systemctl restart fail2ban
sudo fail2ban-client status sshd # Verificar el estado del filtro SSH

5. Instalación de utilidades básicas

Algunas utilidades pueden ser útiles durante el proceso de instalación y depuración.

sudo apt install curl wget git nano htop net-tools -y # Instalar utilidades útiles

Ahora su servidor está listo para la instalación de Docker y Harbor.

Instalación de software — paso a paso

Instalación de software — paso a paso

En este paso, instalaremos Docker Engine, Docker Compose y Harbor. Utilizaremos las versiones actuales disponibles en 2026. Para Ubuntu 24.04 LTS, lo más probable es que sean Docker Engine 25.x/26.x y Docker Compose v2.x, y Harbor versión 2.x o 3.x.

1. Instalación de Docker Engine

Instalaremos Docker desde el repositorio oficial de Docker para tener siempre las versiones más recientes.

# Eliminamos versiones antiguas de Docker, si las hay
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt remove $pkg; done

# Instalamos los paquetes necesarios para usar el repositorio HTTPS
sudo apt install ca-certificates curl gnupg lsb-release -y

# Agregamos la clave GPG oficial de Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Agregamos el repositorio de Docker a las fuentes de APT
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Actualizamos la lista de paquetes e instalamos Docker Engine
sudo apt update
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

Verifiquemos que Docker esté instalado y en ejecución:

sudo systemctl status docker # Verificación del estado de Docker
sudo docker run hello-world  # Ejecución de un contenedor de prueba

Agreguemos su usuario al grupo docker para no usar sudo con cada comando de Docker (es necesario volver a iniciar sesión después de este paso):

sudo usermod -aG docker harboradmin # Adición del usuario al grupo docker

Cierre sesión y vuelva a iniciarla para que los cambios surtan efecto. Luego verifique:

docker run hello-world # Ejecución de un contenedor de prueba sin sudo

2. Instalación de Docker Compose

El plugin de Docker Compose ya está instalado junto con Docker Engine, pero para mayor comodidad, se puede crear un enlace simbólico a docker compose como docker-compose.

sudo ln -s /usr/libexec/docker/cli-plugins/docker-compose /usr/local/bin/docker-compose # Creación de un enlace simbólico
docker-compose version # Verificación de la versión de Docker Compose

3. Descarga y preparación de Harbor

Harbor se distribuye como un archivo con archivos de Docker Compose. Descargaremos la última versión estable (asumiendo Harbor 2.x o 3.x para 2026) de los lanzamientos de GitHub.

# Creamos un directorio para Harbor
mkdir -p ~/harbor && cd ~/harbor

# Descargamos la última versión estable del instalador de Harbor (por ejemplo, v2.10.x o v3.x)
# Verifique la versión actual en GitHub Releases: https://github.com/goharbor/harbor/releases
# Suponemos que en 2026 la versión actual es la 2.10.0
HARBOR_VERSION="2.10.0" # Reemplace con la versión actual
wget https://github.com/goharbor/harbor/releases/download/v${HARBOR_VERSION}/harbor-offline-installer-v${HARBOR_VERSION}.tgz

# Descomprimimos el archivo
tar xvf harbor-offline-installer-v${HARBOR_VERSION}.tgz

# Nos movemos al directorio con Harbor descomprimido
cd harbor

4. Configuración del instalador de Harbor

El archivo de configuración principal de Harbor es harbor.yml.tmpl. Lo copiaremos a harbor.yml y lo editaremos.

cp harbor.yml.tmpl harbor.yml # Creación del archivo de configuración a partir de la plantilla
nano harbor.yml               # Edición del archivo de configuración

En el archivo harbor.yml, es necesario modificar los siguientes parámetros (ejemplos):

• hostname: your.domain.com — especifique el nombre de dominio por el cual estará disponible su Registro Harbor. Asegúrese de que este dominio tenga un registro A que apunte a la dirección IP de su VPS.
• http.port: 80 — puerto para acceso HTTP (será redirigido a HTTPS).
• https.port: 443 — puerto para acceso HTTPS.
• harbor_admin_password: YourSecurePassword123 — establezca una contraseña segura para el administrador de Harbor.
• data_volume: /data/harbor — ruta donde se almacenarán todos los datos de Harbor (imágenes, base de datos, etc.). Se recomienda usar un disco o partición separada para los datos.
• external_url: https://your.domain.com — URL que se utilizará para acceder a Harbor.

Ejemplo de fragmento de harbor.yml:

hostname: your.domain.com

http:
  port: 80

https:
  port: 443
  # Indicaremos que TLS será gestionado por Caddy, y Harbor funcionará sin TLS directo
  # Para ello, configuraremos Caddy como un proxy inverso.
  # Por ahora, dejaremos estos campos comentados o vacíos si Caddy manejará TLS.
  # Si Harbor generara los certificados por sí mismo, aquí estarían las rutas a ellos.
  # certificate: /your/path/to/server.crt
  # private_key: /your/path/to/server.key

harbor_admin_password: YourSecurePassword123

data_volume: /data/harbor

external_url: https://your.domain.com

Importante: Para entornos de producción, se recomienda usar una base de datos PostgreSQL externa y Redis para una mejor escalabilidad y manejabilidad, pero para esta guía utilizaremos los contenedores integrados en Harbor.

5. Instalación de Harbor

Después de guardar harbor.yml, se puede iniciar la instalación. El instalador configurará todos los archivos de Docker Compose necesarios y arrancará los servicios.

# Ejecutamos el script de instalación
sudo ./install.sh --with-clair --with-chartmuseum --with-trivy # Instalación con módulos de escaneo y ChartMuseum

El script install.sh realizará las siguientes acciones:

• Generará los archivos de Docker Compose necesarios.
• Creará y ejecutará todos los contenedores de Harbor.
• Configurará la configuración básica.

El proceso puede tardar varios minutos, ya que Docker descargará todas las imágenes necesarias.

Una vez finalizada la instalación, puede verificar el estado de los contenedores en ejecución:

docker-compose ps # Verificación del estado de todos los contenedores de Harbor

Asegúrese de que todos los contenedores estén en estado "Up".

Configuración

Ahora que Harbor está instalado, necesitamos configurar el acceso HTTPS y asegurarnos de que todo funcione correctamente. Utilizaremos Caddy como proxy inverso con obtención automática de certificados TLS de Let's Encrypt.

1. Configuración de DNS

Antes de configurar Caddy, asegúrese de que su dominio (por ejemplo, your.domain.com) tenga un registro A que apunte a la dirección IP pública de su VPS. Esto es crucial para el funcionamiento de Let's Encrypt.

2. Instalación de Caddy

Caddy es un potente servidor web que simplifica la configuración de HTTPS gracias a su soporte integrado para Let's Encrypt.

# Instalamos Caddy desde el repositorio oficial
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install caddy -y

3. Configuración de Caddy para Harbor

Crearemos un archivo de configuración de Caddy (Caddyfile) para trabajar con Harbor. Caddy actuará como proxy para las solicitudes a Harbor y gestionará automáticamente TLS.

sudo nano /etc/caddy/Caddyfile

Elimine el contenido existente y agregue lo siguiente, reemplazando your.domain.com con su nombre de dominio:

your.domain.com {
    reverse_proxy 127.0.0.1:8080 { # Harbor por defecto se ejecuta en 8080 dentro del contenedor
        header_up Host {host}
        header_up X-Real-IP {remote_ip}
        header_up X-Forwarded-For {remote_ip}
        header_up X-Forwarded-Proto {scheme}
    }
    # Opcional: habilitar compresión Gzip
    encode gzip
    # Opcional: registro de logs
    log {
        output file /var/log/caddy/harbor_access.log
        format json
    }
    # Opcional: Rate Limiting básico para protección contra DoS
    # rate_limit {
    #     burst 10
    #     rate 5r/s
    # }
}

Cree un directorio para los logs de Caddy si ha habilitado el registro:

sudo mkdir -p /var/log/caddy
sudo chown caddy:caddy /var/log/caddy

Reinicie Caddy para aplicar los cambios:

sudo systemctl restart caddy
sudo systemctl enable caddy # Habilitar el inicio automático de Caddy
sudo systemctl status caddy # Verificar el estado de Caddy

Asegúrese de que Caddy se haya iniciado correctamente y haya obtenido los certificados TLS. Puede verificar los logs de Caddy: sudo journalctl -u caddy --no-pager.

4. Verificación del funcionamiento de Harbor

Ahora que Caddy está configurado, Harbor debería ser accesible a través de HTTPS.

• Acceso a través del navegador: Abra https://your.domain.com en su navegador. Debería ver la interfaz de Harbor. Inicie sesión con el nombre de usuario admin y la contraseña que especificó en harbor.yml (harbor_admin_password).
• Verificación a través de curl:

curl -I https://your.domain.com/api/v2.0/health # Verificación de la disponibilidad de la API de Harbor

Debería recibir un estado HTTP 200 OK. Si no es así, verifique los logs de Caddy y Harbor.

5. Configuración del cliente Docker

Para trabajar con su registro privado de Docker en su máquina local o agentes CI/CD, debe iniciar sesión en él:

docker login your.domain.com # Ingrese el nombre de usuario (por ejemplo, admin) y la contraseña

Después de iniciar sesión correctamente, podrá enviar (push) y extraer (pull) imágenes:

# Ejemplo: etiquetamos una imagen existente y la subimos a Harbor
docker tag hello-world your.domain.com/myproject/hello-world:latest
docker push your.domain.com/myproject/hello-world:latest

# Ejemplo: descargamos una imagen de Harbor
docker pull your.domain.com/myproject/hello-world:latest

Importante: Cree el proyecto myproject en la interfaz web de Harbor antes de intentar subir imágenes a él.

6. Secretos y variables de entorno

La contraseña del administrador de Harbor que especificó en harbor.yml es información sensible. En entornos de producción, se recomienda usar Docker Secrets o sistemas externos de gestión de secretos. Para Harbor, que se ejecuta a través de docker-compose, se puede usar un archivo .env. Aunque el instalador de Harbor no lo usa directamente, puede editar el docker-compose.yml generado y usar variables de entorno para datos sensibles. Sin embargo, para simplificar esta guía, hemos dejado la contraseña en harbor.yml.

Ejemplo de uso de .env para la contraseña del administrador (no aplicado automáticamente por el instalador de Harbor, pero demuestra el principio):

# En su archivo .env (junto a docker-compose.yml)
HARBOR_ADMIN_PASSWORD=MySuperSecurePassword123

# En docker-compose.yml o harbor.yml (si lo soportara)
# harbor_admin_password: ${HARBOR_ADMIN_PASSWORD}

Para Harbor, un enfoque más seguro es cambiar la contraseña del administrador a través de la interfaz web después de la instalación, así como usar LDAP/OIDC para la autenticación de usuarios en lugar de cuentas locales.