Implantação, Docker e Documentação

O Menthor é implantado como uma API FastAPI conteinerizada, projetada para rodar em Máquinas Virtuais Linux utilizando Docker Engine e NGINX.

Esta aplicação utiliza uma arquitetura Docker-out-of-Docker (DooD), o que permite que a API principal instancie contêineres efêmeros isolados (Sandbox) para a execução dinâmica e segura de códigos Python.

Nota

Os valores de porta e IPs utilizados nesta documentação (como 8000 e 127.0.0.0) são exemplificativos. Deve-se utilizar parâmetros de acordo com a sua infraestrutura.

Ambiente de Servidor

Runtime: Uvicorn (dentro do container).
Orquestração: Docker Compose e Docker Engine.
Proxy Reverso: NGINX (recomendado para gerir SSL e porta 80/443).

Fluxo de Implantação (Step-by-Step)

1. Construir a Imagem do Sandbox

Antes de iniciar a API, é obrigatório construir a imagem do ambiente isolado localmente no host. Na raiz do repositório, execute:

docker build -f Dockerfile.sandbox -t mia-sandbox:py312-sci --no-cache .

Nota

Proteção contra rotinas de limpeza no servidor (Prune): Caso o servidor execute scripts periódicos de limpeza automática do Docker (ex: docker system prune), a imagem do sandbox pode ser removida por ser considerada sem uso. Para ancorar a imagem e evitar sua exclusão acidental, crie um contêiner âncora com o comando:

docker create --name ancora_mia_sandbox mia-sandbox:py312-sci

2. Configuração de Volumes (Atenção ao Caminho Absoluto)

Para que o Docker Host consiga repassar os arquivos gerados pela API (como scripts e .json de resultados) para o Sandbox, o contêiner da API precisa estar sincronizado fisicamente com o servidor.

No seu arquivo docker-compose.yml, o mapeamento do projeto deve utilizar caminhos absolutos idênticos nos dois lados do volume.

Exemplo estrutural:

services:
  fastapi-api:
    # ...
    volumes:
      # Habilita o DooD (Comunicação com o Docker Host)
      - /var/run/docker.sock:/var/run/docker.sock

      # Sincronização Absoluta: Substitua pelo caminho real do servidor
      - /root/menthor:/root/menthor

3. Subir a Aplicação

Com o sandbox preparado e os caminhos absolutos ajustados no compose, inicie a infraestrutura:

docker-compose up -d --build

Para acompanhar a execução e eventuais erros na inicialização da API:

docker-compose logs -f fastapi-api

Manutenção e Monitorização

Caso precise reiniciar o ambiente, limpar o cache ou investigar os arquivos gerados pela API diretamente por dentro do contêiner, utilize os comandos de apoio abaixo:

Derrubar a infraestrutura: Encerra e remove o contêiner da API e a rede criada de forma segura.

docker-compose down

Limpeza Profunda (Reconstrução Limpa): Se precisar forçar a recriação da imagem do zero (útil após alterar bibliotecas no requirements.txt ou instruções no Dockerfile), derrube a estrutura, remova a imagem local e suba novamente.

docker-compose down
docker rmi menthor_fastapi-api:latest
docker-compose up -d --build

Inspecionar por dentro do contêiner: Para abrir um terminal interativo (bash) diretamente dentro da aplicação e validar caminhos ou arquivos temporários, execute:

docker exec -it menthor-fastapi-app bash

Dica

Ao acessar o terminal do contêiner, você pode navegar pelos diretórios espelhados (ex: cd /root/menthor/sandboxes) e utilizar o comando ls -la para verificar a persistência, integridade e as permissões dos arquivos gerados pelo código (.py e .json) antes de eles serem enviados ao Sandbox pelo Host.

Considerações de NGINX

Certifique-se de que a configuração do NGINX aponta o proxy_pass para o host/porta corretos e que o firewall do servidor permite o tráfego necessário.

Abaixo, um exemplo de bloco (server) para mapeamento de um subdomínio para a aplicação rodando no servidor:

server {
    server_name menthor.seudominio.com.br;

    location / {
        proxy_pass http://127.0.0.0:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Geração e Compilação com Sphinx

A documentação técnica do sistema é gerada como um site estático HTML utilizando o Sphinx.

Compilação do HTML

Navegue até o diretório docs e execute o fluxo de compilação:

cd docs
make clean
make html

Os arquivos estáticos serão gerados no diretório docs/build/html/index.html.

Correção de Caracteres e Esquema OpenAPI

Se houver falhas com encoding ou caracteres especiais ao compilar endpoints da API, obtenha um arquivo openapi.json limpo extraído diretamente da API em execução:

# 1. Certifique-se de que a API está rodando
uvicorn projects.menthor.main_menthor:app --port 8000

# 2. Baixe o esquema OpenAPI atualizado
curl http://127.0.0.0:8000/openapi.json -o openapi.json

Publicação da Documentação no NGINX

A publicação do site estático da documentação no servidor de produção é realizada servindo diretamente o diretório gerado pelo Sphinx através de um bloco dedicado no NGINX.

1. Aplicar Permissões de Leitura e Travessia

O usuário do NGINX (geralmente www-data) precisa de permissão de travessia nos diretórios até a pasta de build:

# Permissão de travessia no caminho
chmod +x /root /root/menthor /root/menthor/docs /root/menthor/docs/build

# Permissão de leitura recursiva no HTML gerado
chmod -R 755 /root/menthor/docs/build/html

2. Bloco do NGINX para o Subdomínio de Docs

Adicione a configuração ao arquivo de site do NGINX (ex: /etc/nginx/sites-available/default):

server {
    server_name docs.menthor.aplicacoesmia.com.br;

    root /root/menthor/docs/build/html;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }

    listen 80;
}

3. Reiniciar o Serviço NGINX

sudo systemctl restart nginx

Nota

Sempre que o comando make html for executado no servidor, a documentação pública em docs.menthor.aplicacoesmia.com.br será atualizada automaticamente sem a necessidade de reiniciar o NGINX.