Unregistry – envie `docker push` diretamente para um servidor sem usar registro

• Unregistry é uma ferramenta open source que permite enviar imagens Docker diretamente para um servidor remoto sem usar um registro externo
• Com o comando docker pussh, ela transfere a imagem via SSH de forma eficiente, pulando camadas que já existem no servidor
• Resolve a complexidade e ineficiência do Docker Hub tradicional, de registros próprios e do método save/load
• É especialmente vantajosa para deploy em produção, CI/CD e ambientes isolados, onde a transferência rápida e segura de imagens faz diferença
• Instalação, uso e requisitos são muito simples, sem necessidade de operar serviços extras nem expor portas

---

Introdução ao Unregistry e principais vantagens

• Unregistry é um registro leve de imagens que armazena e serve imagens diretamente a partir do storage do Docker daemon
• Com o comando docker pussh, é possível mover imagens direto para um servidor Docker remoto via SSH, sem passar por um registro externo
• Durante a transferência, as camadas que já existem no servidor são ignoradas, garantindo envio rápido apenas do que é necessário

Problemas da distribuição tradicional de imagens Docker

• Ao transferir para um servidor uma imagem criada localmente, as opções costumam ser estas
  • Docker Hub/GitHub Container Registry: o código pode ficar exposto externamente ou gerar custo no uso de repositórios privados
  • Registro próprio: aumenta a carga de operar um serviço separado e gerenciar segurança e armazenamento
  • Save/Load: sempre transfere a imagem inteira, o que é ineficiente
  • Rebuild direto no servidor: desperdiça tempo e recursos do servidor, além de dificultar o debug

A solução do Unregistry

• Com um único comando, docker pussh myapp:latest user@server, é possível fazer a transferência direta sem repositório intermediário

• Não exige configuração adicional de registro, exposição de portas, preparo de storage nem assinatura

• Processo de transferência

  • Abre um túnel SSH até o servidor remoto
  • Executa temporariamente um contêiner do unregistry
  • Conecta uma porta local aleatória à porta do unregistry
  • Envia com docker push apenas as camadas que não existem (prontas para uso imediato)
  • Encerra o contêiner do unregistry e o túnel SSH

• Funciona de forma simples e eficiente, como um rsync

• Este projeto foi desenvolvido a partir do Uncloud para simplificar a complexidade do deploy de contêineres em múltiplos hosts Docker

Exemplos de uso

Envio direto de imagem para o ambiente de deploy

• Faça o build localmente e envie direto para o servidor de produção
  • 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 e deploy sem a complexidade de um registro
  • Pode ser usado diretamente em YAML de GitHub Actions e similares

Homelab e ambientes isolados sem internet

• Permite transferir imagens com segurança para uma rede isolada sem expô-las à internet

Como usar

• A conta de usuário SSH precisa conseguir executar comandos Docker remotamente
• Há suporte a opções adicionais, como chave privada SSH e porta SSH personalizada
• Também suporta transferência de imagens multiplataforma (quando baseado em containerd)

Requisitos

Ambiente local

• Docker CLI (com suporte a plugin, 19.03+)
• Cliente OpenSSH

Servidor remoto

• Docker deve estar instalado e em execução
• O usuário SSH precisa ter permissão para usar Docker e, se necessário, conseguir executar sudo docker sem senha
• O uso do containerd image store melhora o desempenho
  • Adicione a seguinte configuração em /etc/docker/daemon.json e reinicie o Docker

    {
      "features": {
        "containerd-snapshotter": true
      }
    }
    

Uso avançado

Uso como registro local independente

• É possível operar o unregistry facilmente como um registro local, sem componentes adicionais
• Dá para fazer deploy e push com comandos Docker

Uso de opções SSH personalizadas

• É possível aproveitar o arquivo de configuração do SSH para definir autenticação extra, portas e outros detalhes conforme o ambiente

Contribuição e comunidade

• Se encontrar bugs, use as issues do GitHub
• No Discord da comunidade Uncloud, é possível discutir recursos, roadmap e detalhes de implementação

Inspiração e projetos open source de referência

• Spegel: serviu de inspiração pela implementação de registro P2P de imagens de contêiner baseado em containerd
• Docker Distribution: usado como base da implementação real do registro

Resumo

• Unregistry é uma ferramenta para mover imagens Docker de forma direta, rápida e simples para servidores remotos, eliminando a necessidade de montar e gerenciar um registro
• Oferece grandes vantagens em cenários como deploy em produção, CI/CD e redes isoladas
• É ideal quando servidores e administradores só querem mover imagens de forma simples, sem processos adicionais

[GN⁺]

Comentários do Hacker News

• Pelas características do servidor, pelos limites de segurança e pela questão de hardening, eu não recomendaria usar Homebrew no Linux; embora exista uma instalação para Linux, ela parece mais um remendo posterior, e o comportamento fica menos de um gerenciador de pacotes e mais como um pombo num tabuleiro de xadrez

• Parece uma ótima ideia que combina bem com ambientes que já usam ferramentas de deploy por push como Ansible, e também soa adequada como técnica de distribuição de hotfix em empresas onde um Docker registry não tem suporte 24 horas por dia; fiquei curioso se isso se integra de forma limpa com ferramentas OCI (como buildah) ou se exige a instalação completa do Docker nos dois lados; ainda não investiguei a fundo, mas pretendo mexer nisso, e achei que faltava ao skopeo a capacidade de bootstrapar seu próprio registry no servidor remoto para funcionar nesse tipo de ambiente

  • O servidor remoto precisa de containerd (Docker e Kubernetes também usam containerd), e do lado do cliente pode ser qualquer coisa que entenda a API de registry (OCI Distribution spec: https://github.com/opencontainers/distribution-spec); o Unregistry reutiliza o código oficial do Docker registry como camada de API, então ele lembra o registry do Docker Hub; é possível usar skopeo, crane, regclient, BuildKit e outros clientes de OCI registry, mas para isso é preciso rodar o unregistry diretamente no host remoto; o comando docker pussh serve para automatizar todo esse fluxo aproveitando o Docker local; como é um script bash, vale a pena dar uma olhada https://github.com/psviderski/unregistry/blob/main/docker-pussh, e é fácil adaptar como quiser

  • É necessário ter docker daemon nos dois lados; essa abordagem usa uma forma engenhosa de compartilhar layers entre os dois daemons via ssh

• Acho que o comando pussh é fácil de lembrar, autoexplicativo e faz um trocadilho ótimo por diferir em apenas uma letra de um comando padrão já existente

  • "pussh" funciona, mas em automação talvez fosse melhor um alias mais explícito como "docker push-over-ssh"; quem vê "pussh" pela primeira vez pode achar que é só um erro de digitação, gerando confusão desnecessária; seria bom oferecer tanto a versão curta quanto a versão completa com flag

  • Houve um comentário em tom de piada dizendo que o s extra seria para representar "sssh"; outra pessoa disse que parece só um typo mesmo

  • O nome "pussh" pode entrar em conflito com outros comandos

• Isso deveria existir há muito tempo e é muito legal; Docker registry tem seu valor, mas no geral ficou complexo demais e se afastou do espírito hacker

  • Como a Docker era uma empresa com investimento de VC, ela precisava monetizar de algum jeito

• O projeto e a abordagem são impressionantes; já tentei hospedar algo como o Zot(https://zotregistry.dev) por conta própria por estar cansado de registries caros, mas esse método parece bem mais simples para certos casos de uso; tomara que serviços de registry privado fáceis, baratos e cobrados por uso se tornem mais comuns

  • Comentário avisando que o certificado SSL de zothub.io expirou

• Acho que o Docker deveria ter funcionado assim desde o começo; parece uma ideia excelente

  • Também dá para chegar a algo parecido salvando a imagem em arquivo, transferindo para o servidor e depois carregando; por exemplo, salvar com docker save -o my-app.tar my-app:latest e carregar com docker load -i /path/to/my-app.tar; combinando isso com ferramentas de automação como Ansible, dá para fazer manualmente o que o Unregistry automatiza; porém, o método save/load exige transferir a imagem inteira toda vez, e gerenciar imagens também é mais conveniente do que lidar com arquivos de archive, como o repositório no GitHub aponta

• Fico feliz em ver esse retorno ao self-hosting com ferramentas desse tipo e tooling baseado em SSH; parece um trabalho bem feito, e pretendo testar

• Foi por causa dessa ferramenta que conheci o projeto uncloud pela primeira vez, e achei interessante porque parece uma solução de deploy em servidor tipo dokku, mas mais poderosa, exatamente o que eu queria

  • Concordo com o feedback de que o uncloud se encaixa muito bem nesse cenário; se houver dúvidas, podem chamar no Discord

  • Vale também conferir https://skateco.github.io/, que segue uma abordagem parecida

  • Recomendo o Portainer; uso Portainer Community Edition com o Portainer Agent em duas instâncias AWS EC2 e funciona muito bem; o recurso de stacks (baseado em docker compose) é um destaque, e em uma das EC2 o portainer agent roda Caddy em contêiner para fazer balanceamento de carga e reverse proxy

• É uma ideia inovadora, mas esse modelo fica fortemente acoplado ao deploy do serviço e exige lógica extra que “entenda” o push para coisas como rollout e escala, por exemplo em blue/green deploy; pensando bem, percebi que é exatamente esse tipo de papel que o uncloud implementa; no fim, porém, é tudo trade-off, e se a prioridade for simplicidade em uma única VM da Hetzner, poder construir a imagem localmente já pode ser uma escolha totalmente satisfatória

  • Como sempre, tudo tem trade-offs, e o melhor é poder escolher a ferramenta mais adequada para cada contexto