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.

.. note::
   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:

.. code-block:: bash

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

.. note::
   **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:

   .. code-block:: bash

      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:

.. code-block:: yaml

   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:

.. code-block:: bash

   docker-compose up -d --build

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

.. code-block:: bash

   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.

.. code-block:: bash

   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.

.. code-block:: bash

   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:

.. code-block:: bash

   docker exec -it menthor-fastapi-app bash

.. tip::
   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:

.. code-block:: nginx

   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:

.. code-block:: bash

   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:

.. code-block:: bash

   # 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:

.. code-block:: bash

   # 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``):

.. code-block:: nginx

   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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: bash

   sudo systemctl restart nginx

.. note::
   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.