GitHub Packages no Linux: Hospedagem de Contêineres

Você já perdeu horas tentando configurar um repositório privado para suas imagens Docker, apenas para se deparar com erros de autenticação 401 ou falhas na transferência de camadas pesadas? Neste tutorial completo, você aprenderá a integrar o GitHub Packages ao seu fluxo de trabalho DevOps, transformando sua VPS Linux em um nó seguro e eficiente para hospedagem de contêineres.

Pré-requisitos

Antes de executar qualquer comando, certifique-se de que seu ambiente está preparado para a integração entre o Docker e a API do GitHub. A configuração correta evita erros de permissão e latência na rede durante o build.

• Conta GitHub: Necessária para acessar o ghcr.io. Contas gratuitas permitem repositórios públicos ilimitados e privados limitados.
• VPS Linux: Recomendamos Ubuntu 22.04 LTS ou Debian 12. A instância deve ter acesso à internet e portas 80/443 abertas se houver necessidade de exposição pública.
• Docker Engine: Versão 20.10 ou superior instalada e rodando no serviço docker.
• GitHub CLI (gh): Ferramenta de linha de comando para facilitar a geração de tokens e autenticação.
• Token de Acesso Pessoal (PAT): Um token com escopo write:packages e read:packages.

Verifique a versão do Docker com o comando abaixo:

docker --version
docker-compose --version

Se o Docker CLI não estiver instalado, utilize o gerenciador de pacotes da sua distribuição. No Ubuntu, execute sudo apt update && sudo apt install docker.io. Lembre-se de adicionar seu usuário ao grupo docker para evitar o uso constante de sudo.

Passo a passo: Autenticação e Configuração

O GitHub Packages utiliza um registry OCI (Open Container Initiative) hospedado em ghcr.io. A chave para o sucesso é a configuração correta das credenciais no daemon do Docker na sua VPS.

Passo 1: Gerar Token e Autenticar no GitHub

Vamos utilizar o GitHub CLI para gerar um token com as permissões necessárias. Isso é mais seguro e rápido do que criar manualmente via interface web.

gh auth login
# Selecione: GitHub.com
# Selecione: Git operations and read-only access to public code (ou scopes específicos)
# Selecione: Full control of private repositories (necessário para repositórios privados)

Agora, exporte o token como uma variável de ambiente temporária para uso imediato:

GITHUB_TOKEN=$(gh auth token)

Passo 2: Login no Registry ghcr.io

O Docker precisa ser autenticado contra o registry. Utilize seu nome de usuário do GitHub e o token gerado.

echo $GITHUB_TOKEN | docker login ghcr.io -u SEU_USUARIO_GITHUB --password-stdin

Se a resposta for Login Succeeded, sua VPS está autorizada a enviar e receber imagens. Teste a conexão sem fazer login, apenas para verificar latência:

docker pull ghcr.io/SEU_USUARIO_GITHUB/hello-world:latest

Passo 2: Push e Versionamento de Imagens

Agora que a comunicação está estabelecida, vamos construir uma imagem Docker e enviá-la para o GitHub Packages. Utilizaremos um exemplo prático de uma aplicação Node.js simples.

Criação do Dockerfile

Crie um arquivo Dockerfile na raiz do seu projeto:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
EXPOSE 3000
CMD ["node", "index.js"]

Build da Imagem

Dê um nome à imagem seguindo a convenção do GitHub Packages. O formato é ghcr.io/usuario/repositorio:tag.

docker build -t ghcr.io/SEU_USUARIO_GITHUB/meu-app:v1.0 .

Este comando cria uma imagem localmente. Verifique se ela existe com docker images | grep ghcr.

Push para o Registry

Envie a imagem para o repositório no GitHub. Isso pode levar alguns minutos dependendo do tamanho da camada base.

docker push ghcr.io/SEU_USUARIO_GITHUB/meu-app:v1.0

O progresso mostrará o upload de camadas. Ao finalizar, você poderá ver a imagem na aba "Packages" do seu repositório no GitHub.

Passo 3: Pull e Execução na VPS

Com a imagem hospedada, o próximo passo é baixá-la e executá-la em um ambiente isolado. Isso simula o ciclo de CI/CD completo.

Remoção da Imagem Local

Para garantir que estamos baixando do registry e não usando uma versão cacheada, remova a imagem local:

docker rmi ghcr.io/SEU_USUARIO_GITHUB/meu-app:v1.0

Execução do Contêiner

Baixe e inicie o contêiner mapeando a porta interna para uma porta externa.

docker run -d --name meu-app-container -p 8080:3000 ghcr.io/SEU_USUARIO_GITHUB/meu-app:v1.0

O sinalizador -d executa o contêiner em segundo plano (detached). A flag -p mapeia a porta 3000 do contêiner para a porta 8080 da VPS.

Verificação de Logs

Confira se a aplicação iniciou corretamente:

docker logs meu-app-container

Se houver erros de dependência ou permissão, eles aparecerão aqui. Se a saída indicar que o servidor está escutando na porta 3000, a instalação está correta.

Passo 4: Integração com Docker Compose

Em ambientes de produção, raramente usamos comandos docker run isolados. O Docker Compose permite orquestrar serviços complexos. Vamos configurar um arquivo docker-compose.yml que puxa a imagem do GitHub Packages.

Configuração do Arquivo YAML

Crie o arquivo docker-compose.yml na raiz do projeto:

version: '3.8'

services:
  app:
    image: ghcr.io/SEU_USUARIO_GITHUB/meu-app:v1.0
    ports:
      - "8080:3000"
    environment:
      - NODE_ENV=production
    restart: unless-stopped

Este arquivo define que o serviço app deve usar a imagem específica do registry. A diretiva restart: unless-stopped garante que o contêiner reinicie automaticamente em caso de falha ou reboot da VPS.

Iniciação com Compose

Execute a orquestração:

docker-compose up -d

O Docker Compose verificará se a imagem existe localmente. Se não existir, ele tentará fazer o pull do ghcr.io. Como já autenticamos anteriormente, o pull será bem-sucedido.

Verificação/Teste

Após a configuração, é crucial validar a integridade do sistema. Siga este checklist técnico.

1. Status do Contêiner: Execute docker ps. O status deve ser Up. Se estiver Exited, verifique os logs.
2. Acessibilidade HTTP: Use curl http://localhost:8080. Você deve receber a resposta da sua aplicação (ex: JSON ou HTML).
3. Integridade da Imagem: Verifique o ID da imagem no container com docker inspect meu-app-container | grep Image. Confirme que corresponde à tag enviada.
4. Permissões de Arquivo: Se sua aplicação escreve em disco, verifique se os volumes ou diretórios têm as permissões corretas para o usuário dentro do contêiner (geralmente UID 1000 em imagens base alpine/node).

Se o curl retornar timeout, verifique o firewall da sua VPS (UFW ou Firewalld) e as regras de segurança do grupo de instância na nuvem.

Troubleshooting

Erros em registries remotos são comuns. Abaixo, resolvemos os problemas mais frequentes encontrados por administradores de sistemas.

Atenção: Tokens do GitHub expiram por padrão após 8 horas se forem tokens de instalação, mas PATs (Personal Access Tokens) podem ser configurados para nunca expirar ou ter prazos longos. Não armazene tokens sensíveis no docker-compose.yml em texto puro; use variáveis de ambiente (.env).

Perguntas frequentes

Posso usar GitHub Packages para imagens públicas?

Sim. Contas gratuitas do GitHub permitem repositórios públicos ilimitados, e as imagens hospedadas no GitHub Packages são acessíveis publicamente sem necessidade de autenticação, desde que o repositório seja público.

Qual é o limite de tamanho para imagens no GitHub Packages?

O limite padrão para pacotes individuais é de 2 GB. Para imagens Docker grandes, considere otimizar o Dockerfile usando multi-stage builds e imagens base menores (como Alpine ou Distroless) para evitar atingir esse teto.

Como automatizar o login em pipelines CI/CD?

No GitHub Actions, você pode usar o passo docker/login-action. Em sua VPS, utilize scripts shell que leiam segredos do sistema (como /etc/secrets/docker-token) e executem o login antes do docker pull.

O GitHub Packages substitui um registry dedicado como Harbor?

Não necessariamente. O GitHub Packages é excelente para CI/CD e armazenamento temporário ou de pequeno porte. Para produção de alta escala com necessidade de replicação global, escaneamento profundo de vulnerabilidades e retenção de dados massiva, um registry dedicado (Harbor, JFrog, AWS ECR) é mais robusto.

Como lidar com a expiração de tokens em servidores longos?

Crie um script cron que verifique a validade do token e realize um novo docker login automaticamente. Isso evita que seus contêineres falhem ao tentar atualizações automáticas devido à revogação de credenciais.

Conclusão

A integração entre Docker e GitHub Packages oferece um fluxo de trabalho unificado, eliminando a necessidade de gerenciar múltiplos registries externos para projetos em desenvolvimento. Ao seguir os passos de autenticação, build e push detalhados, você estabelece uma infraestrutura DevOps sólida onde o versionamento de código e a entrega de contêineres estão intrinsecamente ligados.

A segurança e a facilidade de versionamento do GitHub tornam essa abordagem ideal para equipes que buscam agilidade sem abrir mão da rastreabilidade. No entanto, para ambientes de produção crítica, monitore sempre os custos de armazenamento e a latência de rede entre sua VPS e o registry.

Se você busca performance consistente e infraestrutura escalável para suportar seus contêineres e microsserviços, experimente hospedagem cloud na Toda Solução. Nossos servidores VPS são otimizados para cargas de trabalho de containerização, garantindo alta disponibilidade e baixa latência para suas aplicações.