Instalação¶

Overview¶

Esta página descreve o processo de instalação, configuração e execução local da aplicação.

Instalação das ferramentas¶

Para executar o projeto localmente, é necessário instalar as seguintes ferramentas:

Python (^3.12)
venv
pipx (opcional porém recomendado)
Poetry
Docker

Python¶

Instalação do intérprete pode ser realizada de acordo com o manual disponível na documentação oficial. Pode ser necessário realizar a instalação através dos repositórios do deadsnakes.

venv¶

Ambientes virtuais são a maneira mais convencional de isolar a instalação de pacotes python no contexto do sistema operacional. A ferramenta pode ser instalada de acordo com a documentação oficial. Pode ser necessário realizar a instalação através dos repositórios do deadsnakes.

pipx¶

pipx é um gerenciador de pacotes que permite a execução de apliações Python em ambientes isolados. A instalação da ferramenta é opcional, porém recomendada para instalar o Python Poetry (ver próxima seção), que é utilizado para o gerenciamento de dependências do projeto. O processo de instalação está disponível na documentação oficial.

Poetry¶

O Poetry é a ferramenta de gerenciamento de dependências do projeto; pode ser instalada de acordo com o manual encontrado na documentação oficial; recomenda-se realizar a instalação através do pipx.

Docker e Compose¶

Docker e a ferramenta auxiliar Compose são utilizados para isolar a execução de processos e aplicações em máquinas virtualizadas separadamente do ambiente do sistema operacional. Para instalar as ferramentas, siga os passos especificados para a distribuição do seu SO de acordo com a documentação oficial.

Instalação das dependências do projeto¶

Antes de instalar qualquer módulo adicional no intérprete python, é importante isolar o ambiente da aplicação através de um ambiente virutal. Caso seja a primeira vez executando o sistema, talvez seja necessário criar os arquivos do ambiente local:

python3.12 -m venv venv

Para instalar as dependências do projeto basta inicializar o ambiente virtual e executar o comando de instalação:

source venv/bin/activate
poetry install

Executando a aplicação localmente¶

Antes de inicializar a aplicação, é necessário ativar o container do banco de dados do projeto no docker. Para verificar o status atual do container execute o comando docker ps:

docker ps
CONTAINER ID   IMAGE                  COMMAND                  CREATED        STATUS             PORTS                                       NAMES
918266dc5863   mongo                  "docker-entrypoint.s…"   6 days ago     Up About an hour   27017/tcp                                   metrify_mongo_1

Caso o container do metrify não conste na lista apresentada, execute o compose (dentro do projeto) para ativar os containers:

# Dependendo da versão do Docker instalada no sistema, execute "docker compose" ou "docker-compose", se o compose for instalado separadamente. Consultar documentação oficial.

docker compose up -d mongo
Creating metrify_mongo_1 ... done

É necessário exportar as credenciais da aplicação em um arquivo .env para que seja possível realizar a integração com os serviços do Github; para fazer isso, adicione o arquivo na raiz do projeto da seguinte maneira:

    .
    ├── .coverage
    ├── docker-compose.yml
    ├── docs
    │   ├── build
    │   ├── make.bat
    │   ├── Makefile
    │   └── source
+   ├── .env
    ├── .flaskenv
    ├── .github
    │   └── workflows
    ├── .gitignore
    ├── LICENSE.rst
    ├── metrify
    ...

Registre os dados de configuração para a integração:

# .env
APP_ID="app_id"
PRIVATE_KEY_PATH="./.private-key.pem"
INSTALLATION_ID="your_installation_id"

As variáveis APP_ID e INSTALLATION_ID são referentes ao ID universal do Github App e ID da instalação do app na organização de destino, respectivamente. A variável de ambiente PRIVATE_KEY_PATH deve apontar para a localização do arquivo .pem da chave privada da aplicação (consultar com equipe de desenvolvimento para adquirir uma chave de acesso).

Recomenda-se salvar a chave de acesso em um arquivo .private-key.pem na raiz do projeto, como demonstrado no exemplo de configuração, da seguinte maneira:

    .
    ├── .coverage
    ├── docker-compose.yml
    ├── docs
    │   ├── build
    │   ├── make.bat
    │   ├── Makefile
    │   └── source
    ├── .env
+   ├── .private-key.pem
    ├── .flaskenv
    ├── .github
    │   └── workflows
    ├── .gitignore
    ├── LICENSE.rst
    ├── metrify
    ...

Após a instalação de todos os recursos, certifique-se de ativar o ambiente virtual para executar o servidor Flask:

source venv/bin/activate
flask run

A aplicação estará disponível em no endereço 127.0.0.1:5000.

Identificando diagnósticos via logs¶

Por padrão, os logs do sistema serão amazenados em logs/, em formato .jsonl. Recomenda-se a ferramenta jq para navegação dos logs durante a depuração do código em desenvolvimento.

cat logs/metrify.jsonl | jq '. | select ( .level == "DEBUG" )'
{
  "level": "DEBUG",
  "message": "2 found:\n {'/etc/timezone': 'America/Sao_Paulo', '/etc/localtime is a symlink to': 'America/Sao_Paulo'}",
  "timestamp": "2024-07-05T03:00:20.359235+00:00",
  "logger": "tzlocal",
  "module": "unix",
  "function": "_get_localzone_name",
  "line": 139,
  "thread_name": "MainThread"
}
{
  "level": "DEBUG",
  "message": "Looking for jobs to run",
  "timestamp": "2024-07-05T03:00:20.504614+00:00",
  "logger": "apscheduler.scheduler",
  "module": "base",
  "function": "_process_jobs",
  "line": 954,
  "thread_name": "APScheduler"
}
...

pre-commit¶

O projeto é configurado para executar uma checagem rápida do código antes de cada commit no controle de versão. Para habilitar os hooks, basta executar o comando de instalação:

# Com o ambiente virtual ativo e após instalar as dependências do projeto (poetry install)
pre-commit install

Testes unitários¶

Estrutura¶

O repositório do projeto é disposto de acordo com a estrutura a seguir:

.
├── metrify
│   ├── hello
│   │   ├── __init__.py
│   │   ├── strategies.py
│   │   └── routes.py
│   ├── __init__.py
│   └── metrify.py
├── poetry.lock
├── pyproject.toml
├── README.md
├── tests
│   ├── hello
│   │   ├── __init__.py
│   │   └── test_strategies.py
│   └── __init__.py
└── tox.ini

Onde os arquivos de teste no diretório tests/ devem espelhar a disposição dos arquivos no diretório-fonte (metrify/).

A estrutura de diretórios deve ser identica aos pacotes de código de serviço; a nomenclatura dos arquivos de teste deve seguir o padrão “test_<src>.py”, onde “src” refere-se ao nome do arquivo que está sendo testado.
A estrutura do código de teste deve espelhar o código que está sendo testado; o arquivo de teste deve seguir o padrão de um suite de testes (em forma de classe) por função testada, seguindo a nomenclatura “Test<Subject>”, onde “Subject” refere-se ao nome função sendo testada, em PascalCase; cada caso de teste deve ser representado por um método da classe, com um nome descritivo.

# file: tests.hello.test_strategies

from metrify.hello.strategies import hello

class TestHello:
    """Test suite for `hello` function"""

    def test_hello(self):
        """Returns 'Hello, World!'"""
        assert hello() == "Hello, World!"

Executando testes e checagem com tox¶

O projeto está configurado para realizar a execução dos testes, formatação, linting e checagem através do pytest, autopep8, pylint e mypy, e automatizado através do tox.

É possível executar todos as checagens do sistema através do tox (via Poetry):

poetry run tox

Executar etapas do processo de checagem separadamente:

poetry run pytest                   # testes
poetry run pylint metrify tests     # linter
poetry run mypy metrify tests       # type check

Ou em arquivos individuais:

poetry run pylint metrify/hello/strategies.py
poetry run pytest tests/hello/test_strategies.py
...