Construindo um Blog com Jekyll e CI/CD - Parte 2: GitLab Runner e Ambiente Docker

Configurando o GitLab Runner na VPS e Preparando o Ambiente Docker

Nesta segunda parte do nosso tutorial, vamos focar na configuração da sua Virtual Private Server (VPS) para atuar como um ambiente de execução para o GitLab CI/CD. Isso envolve a instalação do Docker, a criação de uma rede Docker personalizada e, crucialmente, a configuração e registro de um GitLab Runner. O Runner será o agente responsável por executar os jobs definidos no seu arquivo .gitlab-ci.yml, permitindo que o pipeline de CI/CD construa e implante seu blog Jekyll diretamente na sua VPS.

Preparando a VPS: Instalação do Docker

Para que o GitLab Runner possa construir e gerenciar contêineres Docker, o Docker Engine precisa estar instalado na sua VPS. As instruções a seguir são específicas para Debian 12, mas o processo é similar para outras distribuições Linux.

1. Atualizar o sistema e instalar dependências: Comece atualizando a lista de pacotes e instalando os pré-requisitos necessários para adicionar o repositório oficial do Docker.

   sudo apt-get update
   sudo apt-get install ca-certificates curl gnupg -y
   

2. Adicionar a chave GPG oficial do Docker: Esta chave é usada para verificar a autenticidade dos pacotes do Docker que você irá baixar.

   sudo install -m 0755 -d /etc/apt/keyrings
   curl -fsSL https://download.docker.com/linux/debian/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
   sudo chmod a+r /etc/apt/keyrings/docker.gpg
   

3. Adicionar o repositório do Docker ao APT sources: Isso configura seu sistema para buscar pacotes Docker do repositório oficial.

   echo \
     "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/debian \
     $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
   

4. Instalar o Docker Engine: Atualize novamente a lista de pacotes para incluir os pacotes do Docker e, em seguida, instale o Docker Engine, o CLI e o Containerd.

   sudo apt-get update
   sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
   

5. Adicionar seu usuário ao grupo docker (opcional, mas recomendado): Para executar comandos Docker sem sudo, adicione seu usuário ao grupo docker. Você precisará sair e entrar novamente na sessão SSH (ou reiniciar a VPS) para que a alteração tenha efeito.

   sudo usermod -aG docker ${USER}
   

   Após executar este comando, reinicie sua sessão SSH ou a VPS para que as permissões sejam aplicadas.

6. Configurar o Docker para IPv6 e redes personalizadas: Para garantir que o Docker possa operar com IPv6 e para definir pools de endereços IP para suas redes, crie ou edite o arquivo /etc/docker/daemon.json. Isso é crucial para a comunicação entre contêineres e para a integração com proxies reversos.

   sudo vim /etc/docker/daemon.json
   

   Adicione o seguinte conteúdo:

   {
     "ipv6": true,
     "ip6tables": true,
     "fixed-cidr": "10.10.0.0/24", 
     "fixed-cidr-v6": "fd00:dead:beef::/64", 
     "default-address-pools": [
   {"base": "10.20.0.0/16", "size": 24}, 
   {"base": "fd00:cafe::/56", "size": 64}
     ]
   }
   

   Salve e feche o arquivo. Em seguida, reinicie o serviço Docker para aplicar as alterações:

   sudo systemctl restart docker
   

7. Verificar a instalação do Docker: Execute docker info para verificar se o Docker está funcionando corretamente e se as configurações de IPv6 foram aplicadas.

   docker info
   

   Procure por seções relacionadas a IPv6 e redes para confirmar a configuração.

Criando a Rede Docker para Contêineres

Para isolar seus contêineres e facilitar a comunicação entre eles (especialmente com um futuro proxy reverso), criaremos uma rede Docker personalizada. Esta rede terá sub-redes IPv4 e IPv6 dedicadas.

docker network create \
  --driver=bridge \
  --subnet=192.168.8.0/24 \
  --gateway=192.168.8.1 \
  --ip-range=192.168.8.0/25 \
  --ipv6 \
  --subnet=fd00:0:0:8::/64 \
  --gateway=fd00:0:0:8::1 \
  proxy-net

Explicação dos parâmetros:

• --driver=bridge: Cria uma rede do tipo bridge, que é o tipo padrão e mais comum para redes de contêineres.
• --subnet=192.168.8.0/24: Define a sub-rede IPv4 para esta rede. Todos os contêineres conectados a proxy-net receberão IPs dentro deste range.
• --gateway=192.168.8.1: Define o gateway IPv4 para a rede.
• --ip-range=192.168.8.0/25: Importante! Este parâmetro define um sub-range dentro da sub-rede principal (/24) de onde o Docker alocará IPs para os contêineres. Ao definir um range menor (/25), garantimos que uma parte da sub-rede (192.168.8.128/25 neste caso) fique livre para alocação manual de IPs, como para um contêiner de proxy reverso que pode precisar de um IP fixo para evitar conflitos com o DHCP interno do Docker. Isso é uma boa prática para evitar problemas de endereçamento.
• --ipv6: Habilita o suporte a IPv6 para esta rede.
• --subnet=fd00:0:0:8::/64: Define a sub-rede IPv6 para a rede.
• --gateway=fd00:0:0:8::1: Define o gateway IPv6 para a rede.
• proxy-net: O nome da rede que estamos criando. Este nome será referenciado no seu .gitlab-ci.yml para conectar os contêineres do blog a esta rede.

Configurando o GitLab Runner

O GitLab Runner é o agente que executa os jobs do seu pipeline de CI/CD. Vamos instalá-lo e configurá-lo na sua VPS como um contêiner Docker, o que facilita o gerenciamento e a atualização.

1. Executar o GitLab Runner como contêiner Docker: Baixe a imagem do GitLab Runner e inicie um contêiner. Este contêiner será persistente e reiniciará automaticamente.

   docker run -d --name gitlab-runner \
       --restart always \
       -v /srv/gitlab-runner/config:/etc/gitlab-runner \
       -v /var/run/docker.sock:/var/run/docker.sock \
       gitlab/gitlab-runner:latest
   

   Explicação dos parâmetros:

   • -d: Executa o contêiner em modo detached (em segundo plano).
   • --name gitlab-runner: Atribui o nome gitlab-runner ao contêiner.
   • --restart always: Garante que o contêiner do Runner sempre reinicie, mesmo após uma reinicialização da VPS.
   • -v /srv/gitlab-runner/config:/etc/gitlab-runner: Mapeia o diretório /srv/gitlab-runner/config da sua VPS para /etc/gitlab-runner dentro do contêiner. Isso é crucial para persistir a configuração do Runner (o arquivo config.toml) mesmo se o contêiner for removido ou recriado.
   • -v /var/run/docker.sock:/var/run/docker.sock: Mapeia o socket do Docker da sua VPS para dentro do contêiner do Runner. Isso permite que o Runner execute comandos Docker diretamente no host (sua VPS), o que é necessário para construir e implantar as imagens do seu blog.
   • gitlab/gitlab-runner:latest: A imagem Docker oficial do GitLab Runner.
2. Verificar se o contêiner está rodando: Confirme se o contêiner gitlab-runner foi iniciado com sucesso.

   docker ps
   

   Você deverá ver uma linha listando o contêiner gitlab-runner com o status Up.

Registrando o GitLab Runner no seu Projeto GitLab

Agora que o contêiner do Runner está em execução, precisamos registrá-lo no seu projeto GitLab. Isso cria uma conexão entre o Runner na sua VPS e o seu repositório no GitLab, permitindo que ele receba e execute os jobs do pipeline.

1. Obter o Token de Registro do GitLab:
   • Acesse o seu repositório jekyll-chirpy no GitLab (no navegador).
   • No menu lateral esquerdo, navegue até Settings > CI/CD.
   • Role para baixo até a seção Runners e clique em Expand.
   • Na subseseção Project runners, clique em New project runner.
   • Na tela de configuração do novo Runner:
     • Platform: Selecione Linux.
     • Tags: No campo Tags, digite jekyll-chirpy. Esta tag é fundamental, pois é a mesma tag que especificamos nos jobs de deploy e cleanup no seu .gitlab-ci.yml. Isso garante que apenas este Runner específico (ou outros com a mesma tag) execute esses jobs sensíveis.
     • Deixe as outras opções como padrão, a menos que você tenha requisitos específicos.
   • Clique em Create runner.
   • O GitLab exibirá um token de registro (uma string alfanumérica longa). Copie este token, pois você precisará dele no próximo passo.
2. Registrar o Runner via linha de comando: No terminal da sua VPS, execute o comando de registro dentro do contêiner do GitLab Runner. Você será guiado por um processo interativo.

   docker exec -it gitlab-runner gitlab-runner register
   

   Siga as instruções interativas, fornecendo as seguintes informações:

   • Enter the GitLab instance URL (for example, https://gitlab.com/): Digite https://gitlab.com
   • Enter the registration token:: Cole o token que você copiou do GitLab.
   • Enter a description for the runner. This is displayed in GitLab:: Digite jekyll-chirpy-runner (ou um nome descritivo de sua escolha).
   • Enter tags for the runner (comma-separated):: Digite jekyll-chirpy (a mesma tag que você configurou no GitLab).
   • Enter an executor: docker-windows, docker+machine, instance, ssh, docker, parallels, virtualbox, kubernetes, docker-autoscaler, custom, shell:: Digite docker. Este executor permite que o Runner use o Docker para executar os jobs do pipeline.
   • Enter the default Docker image (for example, ruby:2.7):: Digite docker:latest. Esta será a imagem padrão usada para jobs que não especificam uma imagem.

   Após o registro bem-sucedido, você verá uma mensagem como: Runner registered successfully. Feel free to start it, but if it\'s running already the config should be automatically reloaded! Configuration (with the authentication token) was saved in "/etc/gitlab-runner/config.toml"

Verificando a Configuração do Runner

É importante verificar se o Runner foi configurado corretamente e se o arquivo config.toml reflete as configurações esperadas.

1. Verificar o arquivo config.toml: O arquivo de configuração do Runner está persistido no volume que mapeamos. Você pode visualizá-lo na sua VPS:

   sudo cat /srv/gitlab-runner/config/config.toml
   

   Procure pela seção [[runners]] e verifique se as tags, o URL do GitLab e o token estão corretos. Além disso, confirme se a linha volumes = ["/cache", "/var/run/docker.sock:/var/run/docker.sock"] está presente, garantindo que o cache e o socket Docker estão corretamente mapeados.

2. Reiniciar o Runner para aplicar as alterações: Após qualquer alteração no config.toml ou para garantir que o Runner carregue a configuração mais recente, reinicie o contêiner do GitLab Runner:

   docker restart gitlab-runner
   

Testando o GitLab Runner

Para confirmar que o GitLab Runner está funcionando corretamente e que ele pode executar os jobs do seu pipeline, vamos disparar um pipeline de teste.

1. Faça um commit na branch homolog para disparar o pipeline: Certifique-se de que você está na branch homolog localmente. Se não estiver, use git checkout homolog.

   git checkout homolog
   git commit --allow-empty -m "Testando o GitLab Runner para homologação" # Um commit vazio é suficiente para disparar o pipeline
   git push
   

   Este git push acionará o pipeline de CI/CD para a branch homolog no GitLab.

2. Verifique a execução do pipeline no GitLab:
   • Acesse o repositório jekyll-chirpy no GitLab através do seu navegador.
   • No menu lateral, navegue até CI/CD > Pipelines.
   • Você deverá ver um novo pipeline em execução para a branch homolog. Clique nele para ver o progresso dos jobs (build:homolog, deploy:homolog, cleanup:homolog, etc.).
   • Monitore os logs de cada job. Se houver algum erro, os logs fornecerão informações para depuração.
3. Repita o processo para a branch main (opcional): Após validar o ambiente de homologação, você pode repetir o processo para a branch main (produção) para garantir que o Runner também funcione para o ambiente de produção. Isso geralmente é feito após um merge de homolog para main.

Com a configuração do GitLab Runner concluída e testada, você está pronto para a próxima etapa, que é a configuração do proxy reverso Nginx para servir seu blog nos ambientes de homologação e produção. Esta etapa será abordada na Parte 3 do tutorial.