Unregistry – envía `docker push` directamente a un servidor sin usar un registro

 (github.com/psviderski)
4 puntos por GN⁺ 2025-06-19 | 1 comentarios | Compartir por WhatsApp
  • Unregistry es una herramienta open source que permite transferir imágenes de Docker directamente a un servidor remoto sin usar un registro externo
  • Con el comando docker pussh, envía imágenes al servidor remoto por SSH de forma eficiente, omitiendo las capas que ya existen
  • Resuelve la complejidad e ineficiencia de Docker Hub tradicional, un registro propio y el método save/load
  • Su gran ventaja es la transferencia rápida y segura de imágenes en despliegues a producción, CI/CD y entornos aislados sin internet
  • La instalación, el uso y los requisitos son muy simples, y no hace falta operar servicios adicionales ni exponer puertos

Introducción a Unregistry y principales ventajas

  • Unregistry es un registro de imágenes liviano que guarda y sirve imágenes directamente desde el almacenamiento del daemon de Docker
  • Con el comando docker pussh, es posible mover imágenes a un servidor Docker remoto por SSH sin pasar por un registro externo
  • Durante la transferencia, excluye las capas que ya existen en el servidor y ofrece la eficiencia de enviar rápido solo lo necesario

Problemas del despliegue tradicional de imágenes Docker

  • Al transferir una imagen construida localmente al servidor, las opciones suelen ser las siguientes
    • Docker Hub/GitHub Container Registry: el código puede quedar expuesto externamente o generar costos al usar repositorios privados
    • Registro propio: aumenta la carga de operar un servicio adicional y gestionar seguridad y almacenamiento
    • Save/Load: siempre transfiere la imagen completa, lo que resulta ineficiente
    • Reconstrucción directa en el servidor: desperdicia tiempo y recursos del servidor, además de generar problemas de depuración

La solución de Unregistry

  • Con un solo comando, docker pussh myapp:latest user@server, se puede hacer una transferencia directa sin almacenamiento intermedio

  • No requiere configuración adicional de registro, exposición de puertos, preparación de almacenamiento ni suscripciones

  • Proceso de transferencia

    • Abre un túnel SSH hacia el servidor remoto
    • Ejecuta temporalmente un contenedor de unregistry
    • Conecta un puerto local aleatorio con el puerto de unregistry
    • Envía con docker push solo las capas inexistentes (listas para usar de inmediato)
    • Cierra el contenedor de unregistry y el túnel SSH

  • Funciona de forma simple y eficiente, como rsync

  • Este proyecto fue desarrollado en Uncloud para simplificar la complejidad de desplegar contenedores en múltiples hosts Docker

Ejemplos de uso

Envío directo de imágenes al entorno de despliegue

  • Haz build localmente y luego push directo al servidor de producción
    • docker build --platform linux/amd64 -t myapp:1.2.3 .
    • docker pussh myapp:1.2.3 deploy@prod-server
    • ssh deploy@prod-server docker run -d myapp:1.2.3

Pipeline de CI/CD

  • Permite build y despliegue sin la complejidad de un registro
    • Puede usarse la transferencia directa en un YAML de GitHub Actions, por ejemplo

Homelab y entornos aislados sin internet

  • Transfiere imágenes de forma segura a una red aislada sin exponerlas a internet

Cómo usarlo

  • La cuenta de usuario SSH debe poder ejecutar comandos de Docker en el servidor remoto
  • Soporta opciones adicionales como clave privada SSH o puerto SSH personalizado
  • También admite transferencia de imágenes multiplataforma (si está basado en containerd)

Requisitos

Entorno local

  • Docker CLI (con soporte para plugins, 19.03+)
  • Cliente OpenSSH

Servidor remoto

  • Docker debe estar instalado y en ejecución
  • El usuario de SSH debe tener permisos sobre Docker y, si hace falta, poder ejecutar sudo docker sin contraseña
  • El uso de containerd image store mejora el rendimiento
    • Hay que agregar la siguiente configuración en /etc/docker/daemon.json y reiniciar Docker 
      {
  "features": {
    "containerd-snapshotter": true
  }
}

Uso avanzado

Uso como registro local independiente

  • Es posible operar unregistry fácilmente como un registro local sin componentes adicionales
  • Se puede hacer deploy y push con comandos de Docker

Uso de opciones SSH personalizadas

  • Se puede usar el archivo de configuración SSH para definir ajustes detallados según las condiciones necesarias, como autenticación adicional o puertos

Contribuciones y comunidad

  • Si encuentras errores, puedes registrarlos en GitHub Issues
  • En la comunidad de Discord de Uncloud se pueden discutir features, roadmap y detalles de implementación

Inspiración y proyectos open source de referencia

  • Spegel: inspiró parte de la implementación de un registro de imágenes de contenedores P2P basado en containerd
  • Docker Distribution: se usa como base para la implementación real del registro

Resumen

  • Unregistry es una herramienta para transferir imágenes de Docker de forma fácil y rápida directamente a un servidor remoto, eliminando la carga de montar y administrar un registro
  • Ofrece ventajas muy fuertes en escenarios como despliegues a producción, CI/CD y redes aisladas
  • Es una opción muy adecuada cuando se quiere mover imágenes entre servidor y administrador de forma simple, sin procesos adicionales

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-06-19
Opiniones en Hacker News

  • Por las características del servidor, los límites de seguridad y el hardening, no me gustaría recomendar usar Homebrew en Linux; aunque existe una instalación para Linux, se siente más como algo agregado a posteriori, y más que un gestor de paquetes parece una paloma sobre un tablero de ajedrez

  • Me parece una gran idea que encaja muy bien en lugares donde ya se usa tooling de despliegue push como Ansible; además, da la impresión de que también sirve como técnica de despliegue de hotfixes para empresas donde el Docker registry no está disponible 24/7. Me pregunto si se integra de forma limpia con tooling OCI (como buildah), o si hace falta tener una instalación completa de Docker en ambos lados. Todavía no lo he investigado a fondo, pero pienso trabajar en algo relacionado, y sentí que a skopeo le faltaba la capacidad de bootstrapear su propio registry en el servidor remoto para que funcione en este tipo de entorno

    • El servidor remoto necesita containerd (Docker y Kubernetes también usan containerd), y del lado del cliente sirve cualquier cosa que entienda la API del registry (OCI Distribution spec: https://github.com/opencontainers/distribution-spec). Unregistry reutiliza el código oficial del Docker registry como capa de API, así que se siente parecido al registry de Docker Hub. Puedes usar skopeo, crane, regclient, BuildKit y otras herramientas que usan OCI registry, pero para eso hace falta ejecutar unregistry directamente en el host remoto. El comando docker pussh usa Docker local para automatizar todo ese flujo. Como es un script de bash, vale la pena echarle un vistazo: https://github.com/psviderski/unregistry/blob/main/docker-pussh, y también es fácil modificarlo a gusto

    • Se necesita un docker daemon en ambos lados; este método usa una forma ingeniosa de compartir layers por ssh entre los dos daemons

  • Creo que el comando pussh es fácil de recordar, autoexplicativo y muestra un buen juego de palabras al diferenciarse por una sola letra del comando estándar existente

    • pussh está bien, pero para automatización quizá sería mejor un alias más claro como docker push-over-ssh; alguien que vea pussh por primera vez podría pensar que es un error tipográfico y causar confusión innecesaria. Estaría bueno soportar tanto la versión corta como la versión completa con flags

    • Hay una explicación en tono de broma de que la s extra representa sssh; otros dicen que simplemente es un typo

    • El nombre pussh podría entrar en conflicto con otros comandos

  • Esto debió existir desde hace tiempo y me parece muy genial; el Docker registry tiene valor por sí mismo, pero en general se ha vuelto demasiado complejo y cada vez más alejado del espíritu hacker

    • Como Docker era una empresa con inversión de VC, estaba en una situación donde de algún modo tenía que generar ingresos

  • El proyecto y el enfoque me parecen impresionantes; cansado de registries caros, llegué a hostear algo como Zot(https://zotregistry.dev) por mi cuenta, pero este método se ve mucho más simple para ciertos casos de uso. Ojalá los servicios de private registry que sean fáciles, baratos y basados en consumo fueran más comunes

    • Comentario avisando que el certificado SSL de zothub.io está vencido

  • Creo que Docker debió funcionar así desde el principio; me parece una idea genial

    • También se puede lograr un resultado similar guardando el archivo de imagen como un archivo y transfiriéndolo al servidor para luego cargarlo. Por ejemplo, guardar con docker save -o my-app.tar my-app:latest y cargar con docker load -i /path/to/my-app.tar. Combinado con herramientas de automatización como ansible, se puede hacer manualmente lo que Unregistry automatiza. Sin embargo, el repo de GitHub menciona como desventaja que el método save/load obliga a transferir siempre la imagen completa, y además gestionar imágenes es más cómodo que trabajar con archivos de archivo

  • Me alegra este regreso al self-hosting usando herramientas como esta y tooling basado en SSH; me parece un trabajo bien hecho y planeo probarlo personalmente

  • Gracias a esta herramienta conocí por primera vez un proyecto llamado uncloud, y me parece interesante porque se ve como una solución de despliegue en servidor tipo dokku, pero más potente, justo lo que quería

    • Coincido con el comentario de que uncloud le queda muy bien a ciertas personas; si tienen dudas, son bienvenidas en Discord

    • También recomiendo ver https://skateco.github.io/, que ofrece un enfoque parecido

    • Recomiendo Portainer; estoy operando bien con Portainer Community Edition y Portainer Agent en dos instancias de AWS EC2. La función de stacks (basada en docker compose) es su punto fuerte, y en una de las EC2 el portainer agent ejecuta Caddy como contenedor para cumplir el rol de load balancer y reverse proxy

  • Es una idea novedosa, aunque este enfoque queda muy acoplado al despliegue del servicio, y para despliegue y escalado —por ejemplo, en un despliegue blue/green— hace falta lógica adicional que entienda el “push”. Pensándolo mejor, veo que esa función es parte de la estructura implementada en uncloud. Pero al final todo es un trade-off, y si priorizas la simplicidad en una sola VM de Hetzner, puede ser una opción totalmente satisfactoria incluso con solo hacer build local de las imágenes

    • Como siempre, todo tiene trade-offs, y lo mejor es poder elegir la herramienta óptima según cada situación.