ferramentas/GitLab-Pipelines.md

+Esta página descreve a ferramenta de _pipelines_ da plataforma GitLab e faz parte do [Catálogo do LabES](../home).
 
-**O runner deve estar em servidor diferente do que roda o GitLab**
-No LabES:
-    - GitLab em gitlab.labes.inf.ufes.br
-    - Runner em dev.labes.inf.ufes.br
 
-Docker - Instruções de instalação:
-https://docs.docker.com/engine/install/
+## O que é?
+
+O GitLab é uma plataforma para desenvolvimento e operação (_DevOps_) de software e encontra-se descrito em [sua própria página no catálogo](ferramentas/gitlab). Dentre as ferramentas úteis para projetos de desenvolvimento de software oferecidas pela plataforma, os _pipelines_ (linhas de produção) permitem a realização de integração e implantação contínuas (CI/CD) dos projetos hospedados no GitLab.
+
+
+## Quando se aplica?
+
+Quando se deseja desenvolver um projeto de software e realizar integração e implantação contínuas (CI/CD).
+
+
+## Como instalar?
+
+Para realizar CI/CD, é preciso ter acesso a um servidor (ou máquina virtual) diferente do servidor onde foi instalado o GitLab para instalação de um componente chamado _Runner_. Por exemplo, no LabES o GitLab roda em `gitlab.labes.inf.ufes.br` e o _Runner_ em `dev.labes.inf.ufes.br`.
+
+Para facilitar a implantação (_deploy_) e substituição (_undeploy_ e _redeploy_) dos sistemas nas _pipelines_ de CI/CD, será utilizado o [Docker](https://www.docker.com/), uma solução de conteinerização que permite a criação de contêineres (_containers_) separados para cada sistema. Para instalá-lo, siga as [instruções de instalação no site do Docker](https://docs.docker.com/engine/install/). Por exemplo, no Ubuntu instalado em `dev.labes.inf.ufes.br`:
 
 ```shell
 sudo apt update
-sudo apt install ca-certificates curl gnupg lsb-release
-sudo mkdir -p /etc/apt/keyrings
+sudo apt install ca-certificates curl gnupg
+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
 echo \
-  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
-  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+  "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
 sudo apt update
-sudo apt install docker-ce docker-ce-cli containerd.io docker-compose-plugin
+sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
 sudo docker run hello-world
 ```
 
-(O último comando é só pra testar)
+O último comando é só para testar se a instalação funcionou.
+
+Na sequência, instale o _GitLab Runner_, seguindo suas [instruções de instalação](https://docs.gitlab.com/runner/install/):
 
-GitLab Runner - Instruções de instalação:
-https://docs.gitlab.com/runner/install/
 
 ```shell
 curl -LJO "https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb"
-sudo dpkg -i gitlab-runner_amd64.deb 
+sudo dpkg -i gitlab-runner_amd64.deb
 ```
 
-Registro do Runner - Instruções:
-https://docs.gitlab.com/runner/register/index.html
+Após a instalação, é preciso [registrar o _Runner_ no seu GitLab](https://docs.gitlab.com/runner/register/index.html). Acesse a área de administração do GitLab, siga para a opção **CI/CD > Runners**, clique em **New instance runner**, indique o sistema operacional em que o _Runner_ foi instalado, marque a opção **Run untagged jobs** e clique em **Create runner**. 
 
-No GitLab, pra registrar um Shared Runner, vai em Admin Area > Overview > Runners, clica no botão _Register an instance runner_ e copia o token.
+Na tela seguinte, o GitLab já te fornece um comando que pode ser usado na máquina onde foi instalado o _Runner_ para concluir seu registro. No entanto, deste comando nos interessa apenas o _token_, pois utilizaremos um comando mais completo adaptado de [um tutorial da DigitalOcean](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-continuous-deployment-pipeline-with-gitlab-ci-cd-on-ubuntu-18-04):
 
 ```shell
-sudo gitlab-runner register
+sudo gitlab-runner register -n --url https://gitlab.labes.inf.ufes.br --token <INSIRA_O_TOKEN_AQUI> --executor docker --description "LabES Deployment Runner" --docker-image "docker:stable" --docker-privileged
 ```
 
-Siga as instruções. No meu caso: GitLab instance URL = https://gitlab.labes.inf.ufes.br. Tag obtida do GitLab. Runner executor = docker. Default image = maven:3.8-openjdk-18-slim. As demais opções em branco (default).
-
-(Defult image = docker:stable ??)
-(From: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-continuous-deployment-pipeline-with-gitlab-ci-cd-on-ubuntu-18-04)
-
------------ Implantação Contínua (CD) -----------
-
-Adaptando de: https://www.digitalocean.com/community/tutorials/how-to-set-up-a-continuous-deployment-pipeline-with-gitlab-ci-cd-on-ubuntu-18-04
-
-sudo gitlab-runner register -n --url https://gitlab.labes.inf.ufes.br --registration-token <project_token> --executor docker --description "dev-labes-deployment" --docker-image "docker:latest" --tag-list deployment --docker-privileged –docker-volumes /var/run/docker.sock:/var/run/docker.sock
+Em seguida, crie um usuário específico para as atividades de _deploy_, adicione-o ao grupo `docker` e crie uma chave SSH para registrá-lo no GitLab (deixe a _passphrase_ vazia, pois a _pipeline_ de CI/CD roda em modo não interativo, então não será possível fornecer esta senha quando o comando SSH for utilizado):
 
+```shell
 sudo adduser deployer
 sudo usermod -aG docker deployer
 su deployer
 ssh-keygen -b 4096
 cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys
+```
 
-Copia conteúdo de ~/.ssh/id_rsa (todo e adiciona uma quebra de linha no final) e cola em Settings > CI / CD > Variables > Add Variable:
-- Key: ID_RSA
-- Value <o valor>
-- Type: File
-- Environment Scope: All (default)
-- Protect variable: Checked
-- Mask variable: Unchecked
-
-Outra variável:
-- Key: SERVER_IP
-- Value: <your_server_IP>
-- Type: Variable
-- Environment scope: All (default)
-- Protect variable: Checked
-- Mask variable: Checked
-
-Mais uma:
-- Key: SERVER_USER
-- Value: deployer
-- Type: Variable
-- Environment scope: All (default)
-- Protect variable: Checked
-- Mask variable: Checked
-
-Vai pro arquivo .gitlab-ci.yml e modifica conforme instruções. Antes era só o stage test, agora são especificados 3 stages. Comentários originais (removidos do arquivo):
-
-# Based on the GitLab Maven template:
-# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Maven.gitlab-ci.yml
-
-# Using docker images from:
-# https://hub.docker.com/_/maven/
-
-# For general lifecycle information see:
-# https://maven.apache.org/guides/introduction/introduction-to-the-lifecycle.html
-
-# This configures a pipeline to:
-# * Caches downloaded dependencies and plugins between invocation;
-# * Verify the Maven project at every commit.
+Copie o conteúdo do arquivo `~/.ssh/id_rsa`, volte à área de administração do GitLab, abra **Settings > CD/CD > Variables**, clique em **Add variable** e adicione a seguinte variável:
 
-# TODO:
-# * See if other verifications can be added (e.g., a linter for code convention/formatting)
-# * Continuous Deployment triggered when code is merged into main.
+- **Key**: `STAGING_SERVER_ID_FILE`
+- **Value**: o conteúdo copiado, com uma quebra de linha ao final
+- **Type**: File
+- **Protect variable**: sim
+- **Mask variable**: não
+- **Expand variable reference**: não
 
-Tive que modificar conforme este comentário num bug report do GitLab por conta do docker-dind:
-https://gitlab.com/gitlab-org/gitlab-runner/-/issues/27300#note_571697847
+Em nossos scripts de CI/CD, precisaremos ainda de variáveis para o nome do servidor, nome do usuário para conexão SSH, nome de usuário do banco de dados e senha do banco de dados. Adicione as variáveis abaixo usando o mesmo procedimento acima, porém marcando, para todas elas, **Type**: Variable, **Protec variable**: sim, **Mask variable**: sim (exceto `STAGING_SERVER_PSQL_USERNAME`), e **Expand variable reference**: não:
 
-Adicionei build do Maven como parte do processo, inspirado neste post:
-https://about.gitlab.com/blog/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/
+- `STAGING_SERVER_HOSTNAME`: `dev.labes.inf.ufes.br`
+- `STAGING_SERVER_USER`: `deployer`
+- `STAGING_SERVER_PSQL_USERNAME`: `labes`
+- `STAGING_SERVER_PSQL_PASSWORD`: (defina uma senha para este usuário e insira-a aqui)
 
-Troquei o uso do docker build pelo docker-compose basedo nesse post:
-https://medium.com/@vitalypanukhin/docker-compose-and-gitlab-b209d09210f6
+Como pode ser visto nas duas últimas variáveis acima, usaremos no servidor o sistema gerenciador de bancos de dados PostgreSQL. Para [instalar o PostgreSQL no Ubuntu], basta:
 
-Known hosts pra conectar via SSH do docker-compose:
-https://stackoverflow.com/questions/57290734/ssh-host-key-verification-failed-inside-gitlab-ci
+```shell
+sudo apt update
+sudo apt install postgresql postgresql-contrib
+```
 
-Docker Hub - coloquei a imagem base do WildFly JEE9 lá:
-https://docs.docker.com/docker-hub/
+Para criar o usuário que será dono das bases de dados dos sistemas implantados via _pipeline_:
+1. Entre na conta do admin do PostgreSQL: `sudo -i -u postgres`;
+2. Na conta `postgres`, acesse o PostgreSQL via linha de comando: `psql`;
+3. Crie uma senha para o usuário `postgres` no `psql`: `\password postgres`;
+4. Crie o usuário `labes` no `psql`: `CREATE USER labes WITH PASSWORD '<INSIRA_SENHA_AQUI>';`.
 
------------ Hub ES+ Java no Docker -----------
+Será preciso ainda criar um arquivo de senha para que o usuário `deployer` consiga acessar o PostgreSQL como usuário `postgres`, porém sem ter que especificar a senha na configuração do _pipeline_ do projeto. Para isso, entre na conta do usuário `deployer` (`sudo -i -u deployer`), crie o arquivo `~/.pgpass` com permissão de leitura apenas para o próprio usuário (`chmod 0600 ~/.pgpass`) e insira como seu conteúdo a seguinte linha de configuração:
 
-Usei como base para construir o meu build personalizado:
-https://github.com/jboss-dockerfiles/wildfly/blob/master/Dockerfile
-https://github.com/christianmetz/wildfly-mysql/blob/master/Dockerfile
+```shell
+localhost:5432:*:postgres:<INSIRA_A_SENHA_DO_USUARIO_postgres_AQUI>
+```
 
-Usei como base para fazer o docker compose do WildFly com MySQL:
-https://betterprogramming.pub/setting-up-mysql-database-in-a-docker-d6c69a3e9afe
+Para testar, execute `psql -h localhost -U postgres` como usuário `deployer` e veja se consegue acessar o PostgreSQL via linha de comando.
 
-Documentação Docker compose:
-https://docs.docker.com/compose/
+Por fim, usaremos um aplicativo chamado [Portainer](https://www.portainer.io/) para gerenciar o Docker instalado no servidor. Para instalar a versão _Community Edition_ do Portainer, siga as [instruções de sua documentação](https://docs.portainer.io/start/install-ce/server/docker/linux):
 
-Imagens MySQL:
-https://hub.docker.com/_/mysql
+```shell
+sudo docker volume create portainer_data
+sudo docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -v /var/run/docker.sock:/var/run/docker.sock -v portainer_data:/data portainer/portainer-ce:latest
+```
 
-Pra desativar o JASPI:
-https://github.com/vitorsouza/jakarta-security-example
-https://stackoverflow.com/a/70240973/361343
-https://github.com/wildfly/quickstart/tree/main/ee-security#configure-the-server
-https://stackoverflow.com/questions/56060964/how-run-jboss-cli-on-start-docker-container-with-dockerfile
+Acesse, então, `https://dev.labes.inf.ufes.br:9443/`, crie um usuário administrador do Portainer e na sequência escolha a opção **Proceed using the local environment which Portainer is running in**. Ao clicar em **Dashboard** será possível ver imagens e contêineres, iniciar e parar contêineres, excluir imagens, etc.
 
+{+ Em construção! +}