Skip to content

Changes

Page history
feat: concluída documentação das pipelines authored by Vítor E. Silva Souza's avatar Vítor E. Silva Souza
Hide whitespace changes
Inline Side-by-side
ferramentas/GitLab-Pipelines.md
View page @ e0ebc7de
......@@ -13,7 +13,21 @@ Quando se deseja desenvolver um projeto de software e realizar integração e im
## 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`.
Em primeiro lugar, 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_. Os projetos são implantados nesse servidor separado. Por exemplo, no LabES o GitLab roda em `gitlab.labes.inf.ufes.br` e o _Runner_ em `dev.labes.inf.ufes.br`.
Além disso, é preciso que o servidor do GitLab funcione também como um _registry_, um registro de imagens de projetos criadas durante os processos de CI/CD. Para isso, assegure-se de que a configuração `registry_external_url` foi feita durante a instalação do GitLab (conforme instruções na [página do GitLab no Catálogo](ferramentas/gitlab)).
Satisfeitos os pré-requisitos, para a forma que fazemos CI/CD e os tipos de projetos que desenvolvemos no LabES, precisaremos instalar uma série de ferramentas. Em resumo:
- Utilizamos [Docker](https://www.docker.com/) para executar as ações de CI/CD e hospedar as aplicações implantadas no servidor;
- O [GitLab Runner](https://docs.gitlab.com/runner/) é essencial para o funcionamento das _pipelines_;
- O [PostgreSQL](https://www.postgresql.org/) serve de banco de dados para os sistemas de informação desenvolvidos nos projetos do LabES;
- O [Portainer](https://www.portainer.io/) provê uma interface amigável para gerenciarmos os contêineres Docker das diferentes aplicações implantadas;
- O [Apache HTTP Server](https://httpd.apache.org/) fará o redirecionamento de uma URL amigável para as URLs específicas de cada contêiner Docker.
Alguns dos itens acima pode não ser necessário dependendo do contexto no qual você quer utilizar as _pipelines_ de CI/CD do GitLab. Nas subseções a seguir detalhamos cada uma das instalações e você pode pular as subseções que não se aplicam ao seu caso.
### Docker
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`:
......@@ -34,6 +48,8 @@ sudo docker run hello-world
O último comando é só para testar se a instalação funcionou.
### GitLab Runner
Na sequência, instale o _GitLab Runner_, seguindo suas [instruções de instalação](https://docs.gitlab.com/runner/install/):
......@@ -42,7 +58,7 @@ curl -LJO "https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-ru
sudo dpkg -i gitlab-runner_amd64.deb
```
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**.
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, em **Tags** adicione `deployment`, marque a opção **Run untagged jobs** e clique em **Create runner**.
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):
......@@ -76,7 +92,9 @@ Em nossos scripts de CI/CD, precisaremos ainda de variáveis para o nome do serv
- `STAGING_SERVER_PSQL_USERNAME`: `labes`
- `STAGING_SERVER_PSQL_PASSWORD`: (defina uma senha para este usuário e insira-a aqui)
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:
### PostgreSQL
Como pode ser visto nas duas últimas variáveis acima, usaremos no servidor o sistema gerenciador de bancos de dados [PostgreSQL](https://www.postgresql.org/). Para [instalar o PostgreSQL no Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-install-postgresql-on-ubuntu-22-04-quickstart), basta:
```shell
sudo apt update
......@@ -89,7 +107,7 @@ Para criar o usuário que será dono das bases de dados dos sistemas implantados
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>';`.
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:
Será preciso ainda [criar um arquivo de senha](https://tableplus.com/blog/2019/09/how-to-use-pgpass-in-postgresql.html) 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:
```shell
localhost:5432:*:postgres:<INSIRA_A_SENHA_DO_USUARIO_postgres_AQUI>
......@@ -97,7 +115,29 @@ localhost:5432:*:postgres:<INSIRA_A_SENHA_DO_USUARIO_postgres_AQUI>
Para testar, execute `psql -h localhost -U postgres` como usuário `deployer` e veja se consegue acessar o PostgreSQL via linha de comando.
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):
Outra configuração necessária no PostgreSQL é permitir que as imagens Docker se conectem com o banco de dados, visto que, por padrão (questão de segurança), o PostgreSQL permite apenas conexões vindo de `localhost`, mas os contêineres Docker funcionam como servidores externos (não são consideradas conexões locais). Primeiro, descomente e modifique a seguinte configuração em `/etc/postgresql/14/main/postgresql.conf` (a localização deste arquivo pode mudar dependendo da sua instalação):
```shell
listen_addresses = '*'
```
Em seguida, adicione uma entrada ao final do arquivo `/etc/postgresql/14/main/pg_hba.conf` (novamente, a localização pode ser diferente):
```shell
# TYPE DATABASE USER ADDRESS METHOD
host all labes 172.0.0.0/8 md5
```
Reinicie o PostgreSQL e verifique se está rodando, pra certificar que a mudança nas configurações não causou nenhum problema:
```shell
sudo systemctl restart postgresql@14-main.service
sudo systemctl status postgresql@14-main.service
```
### Portainer
Para facilitar o gerenciamento do Docker no servidor, usaremos um aplicativo chamado [Portainer](https://www.portainer.io/). 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):
```shell
sudo docker volume create portainer_data
......@@ -106,5 +146,229 @@ sudo docker run -d -p 8000:8000 -p 9443:9443 --name portainer --restart=always -
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! +}
### Apache HTTP Server
Por fim, o [Apache HTTP Server](https://httpd.apache.org/) servirá para redirecionar acessos a URLs amigáveis (ex.: `http://dev.labes.inf.ufes.br/marvin`) para as URLs dos servidores executando dentro de cada contêiner Docker (ex.: `http://dev.labes.inf.ufes.br:8082/marvin`). Para [instalar o Apache HTTP Server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-ubuntu-20-04), execute:
```shell
sudo apt install apache2
```
Em seguida, habilite o módulo que irá fazer os redirecionamentos e reinicie o Apache:
```shell
sudo a2enmod proxy proxy_http
sudo systemctl restart apache2
```
As configurações de redirecionamento são feitas para cada sistema após sua implantação, conforme explicado na seção a seguir.
## Como usar/aplicar?
Para que um projeto utilize a ferramenta de _pipelines_ CI/CD do GitLab, ele precisa ter na raiz do projeto um arquivo chamado `.gitlab-ci.yml` que define os passos daquela _pipeline_ (linha de produção). Para ilustrar, usaremos como exemplo a _pipeline_ do projeto [Marvin](https://gitlab.labes.inf.ufes.br/marvin/marvin), que é um projeto desenvolvido em[Java com Jakarta EE (WildFly), PostgreSQL e Maven](plataformas/java,-jakarta-ee-(wildfly),-postgresql-e-maven):
```yaml
# Four stages in this pipeline: run tests with Maven, build the application with Maven,
# publish image in Docker registry, deploy using Docker.
stages:
- test
- build
- publish
- deploy
variables:
# Maven options: suppress download/dependency messages and show passed time.
MAVEN_OPTS: "-Dhttps.protocols=TLSv1.2 -Dmaven.repo.local=$CI_PROJECT_DIR/.m2/repository -Dorg.slf4j.simpleLogger.log.org.apache.maven.cli.transfer.Slf4jMavenTransferListener=WARN -Dorg.slf4j.simpleLogger.showDateTime=true -Djava.awt.headless=true"
# Provide tags for the latest commit and a different one for each commit.
TAG_LATEST: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_NAME:latest
TAG_COMMIT: $CI_REGISTRY_IMAGE/$CI_COMMIT_REF_NAME:$CI_COMMIT_SHORT_SHA
# Directory in which to perform the deployment in the server.
DEPLOY_DIR: ~/gitlab-deployments/$CI_PROJECT_NAMESPACE/$CI_PROJECT_NAME
# Name of the database to be created, if it doesn't already exist.
DATABASE_NAME: marvin
# Cache downloaded dependencies and plugins between Maven builds (test stage).
cache:
paths:
- .m2/repository
# JOB: test (test stage). For every commit, verify the project (e.g., run unit tests).
test:
image: maven:3.8-openjdk-18-slim
stage: test
script:
- mvn $MAVEN_OPTS verify
# JOB: build (build stage). Build the Web application with Maven.
build:
image: maven:3.8-openjdk-18-slim
stage: build
script:
# The sed commands replace the development-stage database config with the one used in the staging server.
- sed -i -e "s/localhost/host.docker.internal/g" src/main/webapp/WEB-INF/web.xml
- sed -i -e "s/CDATA\[$STAGING_SERVER_PSQL_USERNAME\]/CDATA\[$STAGING_SERVER_PSQL_PASSWORD\]/g" src/main/webapp/WEB-INF/web.xml
- mvn $MAVEN_OPTS -Dmaven.test.skip package
artifacts:
paths:
- target/*.war
# Job build (build stage) should only run when the branch is the default, i.e., on merge requests being merged into main.
only:
variables:
- $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
# JOB: publish (publish stage). Build the docker image for the Web application.
publish:
image: docker:20-dind
stage: publish
tags:
- deployment
variables:
DOCKER_HOST: tcp://docker:2375
DOCKER_DRIVER: overlay2
DOCKER_TLS_CERTDIR: ""
services:
- name: docker:20-dind
alias: docker
command: ["--tls=false"]
script:
- docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
- docker build -t $TAG_COMMIT -t $TAG_LATEST .
- docker push $TAG_COMMIT
- docker push $TAG_LATEST
# Job publish (publish stage) should only run when the branch is the default, i.e., on merge requests being merged into main.
only:
variables:
- $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
# JOB: deploy (deploy stage). Deploys the Web application image (and the database).
deploy:
image: alpine:latest
stage: deploy
tags:
- deployment
script:
# Creates a deploy script and an .env file with variables to be used in docker-compose.yml.
- echo "#!/bin/sh" > deploy.sh
- echo "echo \"SELECT 'CREATE DATABASE $DATABASE_NAME OWNER $STAGING_SERVER_PSQL_USERNAME' WHERE NOT EXISTS (SELECT FROM pg_database WHERE datname = '$DATABASE_NAME')\\gexec\" | psql -h localhost -U postgres" >> deploy.sh
- echo "docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY" >> deploy.sh
- echo "docker compose down --remove-orphans" >> deploy.sh
- echo "docker compose pull" >> deploy.sh
- echo "docker compose up -d --no-build" >> deploy.sh
- echo "WEB_SERVER_IMAGE_NAME=$TAG_COMMIT" > .env
# Installs SSH and copies the files to a temporary folder in the staging server.
- apk update && apk add openssh-client
- chmod og= $STAGING_SERVER_ID_FILE
- ssh -i $STAGING_SERVER_ID_FILE -o StrictHostKeyChecking=no $STAGING_SERVER_USER@$STAGING_SERVER_HOSTNAME "mkdir -p $DEPLOY_DIR"
- scp -i $STAGING_SERVER_ID_FILE -o StrictHostKeyChecking=no deploy.sh .env docker-compose-gitlab.yml $STAGING_SERVER_USER@$STAGING_SERVER_HOSTNAME:$DEPLOY_DIR/
# Runs the deploy script on the server.
- ssh -i $STAGING_SERVER_ID_FILE -o StrictHostKeyChecking=no $STAGING_SERVER_USER@$STAGING_SERVER_HOSTNAME "cd $DEPLOY_DIR && mv docker-compose-gitlab.yml docker-compose.yml && chmod +x deploy.sh && ./deploy.sh"
environment:
name: staging
url: http://dev.labes.inf.ufes.br:8080
# Job deploy (deploy stage) should only run when the branch is the default, i.e., on merge requests being merged into main.
only:
variables:
- $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```
Primeiro, a seção `stages` indica os estágios da _pipeline_, neste caso: `test`, `build`, `publish` e `deploy`. Em seguida, a seção `variables` define variáveis que serão usadas nos scripts de cada um dos estágios e a seção `cache` configura um cache para que os artefatos que o Maven obtiver na Web possam em um estágio possam ser reutilizados noutro.
Passa-se então à definição de cada estágio:
1. **Testes**: o estágio `test` executa os testes automatizados (em geral testes unitários) do projeto, de modo que se algum teste falhar, a _pipeline_ é interrompida e a implantação não acontece. Isso é feito a partir de uma imagem Docker que contém o Maven e a execução do comando `mvn verify`;
2. **Construção**: o estágio `build` constrói a aplicação que será implantada, compilando as classes e organizando outros recursos que devem ser enviados ao servidor. Isso também é feito pelo Maven com o comando `mvn package`, no entanto o script deste estágio realiza substituições no arquivo `web.xml` de configuração da aplicação Web Java, substituindo a configuração da conexão com o banco de dados utilizada no desenvolvimento pela configuração necessária para executar no servidor após implantação. Na configuração deste estágio há duas novidades em relação ao anterior:
- Em `artifacts` se indica quais arquivos devem ser publicados no estágio seguinte. Estes artefatos ficam também disponíveis no GitLab, dentro do projeto, na opção **Build > Artifacts**;
- Em `only` é incluída uma restrição de que este estágio deve executar apenas se o _commit_ for feito no ramo _default_, ou seja, na `main`. Essa restrição é repetida nos estágios seguintes, de modo que os testes rodam em todos os _commits_, mas a implantação apenas quando um _Merge Request_ é mesclado no ramo principal;
3. **Publicação**: antes de ser implantada, a aplicação construída no estágio anterior é publicada no registro de imagens de aplicações do GitLab no estágio `publish`. Para isso, é utilizada uma imagem _Docker in Docker_ e o script consiste de comandos para efetuar login no _registry_ do GitLab, construir a aplicação (de acordo com seu `Dockerfile`) e enviá-la ao registro. Na área do projeto no GitLab, é possível ver o que foi adicionado no registro em **Deploy > Container Registry**;
4. **Implantação**: enfim, em `deploy` é feita a implantação da aplicação construída e publicada no _registry_. A publicação consiste da criação de um script (`deploy.sh`) com alguns comandos que precisam executar no servidor para verificar se o banco de dados existe (se não, criá-lo) e executar o Docker Compose (a partir da configuração em `docker-compose-gitlab.yml`) no servidor. O script é enviado ao servidor via SCP e executado via SSH.
Caso o leitor se interesse, o arquivo [`Dockerfile`](https://gitlab.labes.inf.ufes.br/marvin/marvin/-/blob/main/Dockerfile) pode ser visto no [repositório do Marvin no GitLab](https://gitlab.labes.inf.ufes.br/marvin/marvin/-/tree/main). Ele utiliza uma imagem do WildFly personalizada para o LabES, que encontra-se também no GitLab, no [projeto Docker Images do LabES](https://gitlab.labes.inf.ufes.br/labes/docker-images).
Já o arquivo `docker-compose-gitlab.yml` (que também pode ser visto no repositório) contém um detalhe importante, de modo que o reproduzimos aqui:
```yaml
# Some versions of docker-compose require this.
version: '3'
services:
# WildFly Web Server with the application deployed.
web-server:
container_name: "wildfly-marvin"
image: $WEB_SERVER_IMAGE_NAME
environment:
- WILDFLY_USER=admin
- WILDFLY_PASS=DLeY&S5uw6Z2VU!@
ports:
- "8082:8080"
- "9992:9990"
extra_hosts:
- "host.docker.internal:host-gateway"
```
Na seção `ports` as portas padrão do WildFly, 8080 e 9990, são direcionadas para as portas 8082 e 9992 respectivamente. Cada projeto deve direcionar para uma porta diferente para não ter conflito na hora da implantação no servidor. O controle de quais portas já foram utilizadas pode ser feito na configuração dos redirecionamentos feitos pelo Apache, que mostrarmeos a seguir.
Para configurar o Apache HTTP Server para redirecionar de URLs amigáveis (ex.: `http://dev.labes.inf.ufes.br/marvin`) para as URLs dos servidores executando dentro de cada contêiner Docker (ex.: `http://dev.labes.inf.ufes.br:8082/marvin`), edite (como `root`) o arquivo `/etc/apache2/sites-available/000-default.conf` e faça uma configuração parecida com a demonstrada a seguir:
```shell
<VirtualHost *:80>
#
# Manter outras configurações como estão. Adicionar ao final:
#
ProxyPreserveHost On
# Hub ES+
ProxyPass /hub-es-mais http://localhost:8081/hub-es-mais
ProxyPassReverse /hub-es-mais http://localhost:8081/hub-es-mais
# Marvin
ProxyPass /marvin http://localhost:8082/marvin
ProxyPassReverse /marvin http://localhost:8082/marvin
</VirtualHost>
```
Como visto, a implantação do Hub ES+ (outro projeto do LabES) já utilizava a porta 8081, de modo que o Marvin teve que ser configurado para 8082. A porta 8080 foi preservada, caso se queira instalar o WildFly diretamente no servidor.
Ao realizar modificações no arquivo acima, é preciso reiniciar o Apache HTTP Server. Recomenda-se em seguida verificar se ele está executando pra saber se as mudanças não introduziram erros na configuração:
```shell
sudo systemctl restart apache2
sudo systemctl status apache2
```
## Perguntas frequentes
Ainda não há dúvidas frequentes registradas pelos(as) usuários(as) do GitLab no LabES.
## Referências
- [Página do GitLab no catálogo](ferramentas/gitlab);
- [Documentação do Docker](https://docs.docker.com/);
- [Documentação do GitLab](https://docs.gitlab.com/);
- [Documentação do PostgreSQL](https://www.postgresql.org/docs/);
- [Documentação do Portainer](https://docs.portainer.io/).
## Autores(as)
- @vitorsouza.
\ No newline at end of file