fix(Deploy): Ajustes diversos para deploy

2025-12-08 12:03:56 -03:00 · 2025-12-08 12:03:56 -03:00 · ffdda4f022
commit ffdda4f022
parent c315185cd5
2 changed files with 95 additions and 42 deletions
--- a/README.md
+++ b/README.md
@ -1,6 +1,6 @@
 # Configuração do Projeto Python

-Este guia descreve o passo a passo para configurar o ambiente de desenvolvimento e produção de um projeto Python, incluindo a preparação do ambiente virtual, instalação de dependências, configuração do banco de dados e ajuste de desempenho com múltiplos núcleos de CPU.
+Este guia descreve o passo a passo para configurar o ambiente de desenvolvimento e produção de um projeto Python, incluindo ambiente virtual, dependências, banco de dados, e ajuste de desempenho com múltiplos núcleos.

 ---

@ -42,14 +42,14 @@ venv\Scripts\activate

 ## 4. Instalar Dependências do Sistema

-O projeto utiliza bibliotecas que dependem do **Microsoft C++ Build Tools** (Windows) ou **build-essential** (Linux).
+O projeto depende de compiladores nativos para algumas bibliotecas Python.

 ### Windows

-Baixe e instale:
+Baixe e instale o **Microsoft C++ Build Tools**:
 [https://visualstudio.microsoft.com/pt-br/visual-cpp-build-tools/](https://visualstudio.microsoft.com/pt-br/visual-cpp-build-tools/)

-Selecione o pacote:
+Durante a instalação, selecione o pacote:

 ```
 Desktop Development With C++
@ -68,7 +68,7 @@ sudo apt install -y build-essential libpq-dev

 ## 5. Instalar as Bibliotecas do Projeto

-Com o ambiente virtual **ativado**, instale as dependências:
+Com o ambiente virtual **ativado**, instale as dependências listadas no arquivo `requirements.txt`:

 ```bash
 pip install -r requirements.txt
@ -76,7 +76,7 @@ pip install -r requirements.txt

 ---

-## 6. Configurar o Banco de Dados
+## 6. Configurar o Banco de Dados (Firebird)

 O projeto utiliza o banco **Firebird**.
 Edite o arquivo de configuração em:
@ -103,30 +103,30 @@ Exemplo:
 }
 ```

-**Campos:**
+**Campos principais:**

 | Campo               | Descrição                          |
 | ------------------- | ---------------------------------- |
 | `host`              | Endereço do servidor Firebird      |
 | `name`              | Caminho completo do arquivo `.FDB` |
-| `port`              | Porta (padrão `3050`)              |
+| `port`              | Porta padrão `3050`                |
 | `user`              | Usuário do banco                   |
 | `password`          | Senha do usuário                   |
-| `charset`           | Codificação recomendada: `UTF8`    |
-| `pool.size`         | Conexões mínimas por núcleo        |
+| `charset`           | Codificação (UTF8 recomendado)     |
+| `pool.size`         | Número de conexões fixas           |
 | `pool.max_overflow` | Conexões extras sob demanda        |

 ---

 ## 7. Modo Desenvolvimento

-Para ambiente **local**, execute:
+Para ambiente local, execute:

 ```bash
 uvicorn main:app --reload
 ```

-> O parâmetro `--reload` reinicia a aplicação automaticamente quando há alterações no código.
+> O parâmetro `--reload` reinicia automaticamente a aplicação ao detectar alterações no código.

 Acesse:

@ -138,17 +138,44 @@ http://localhost:8000/docs

 ## 8. Modo Produção

-No ambiente de **produção**, o ideal é usar o **Gunicorn** como gerenciador de processos, com o **Uvicorn** como worker ASGI.
+A execução em produção varia conforme o sistema operacional.

-### Instalação
+---
+
+### **Windows (modo produção simulado)**
+
+O **Gunicorn** não é compatível com Windows, pois depende do módulo `fcntl` exclusivo de sistemas Unix.
+Portanto, em ambiente Windows, recomenda-se usar o **Uvicorn** diretamente com múltiplos *workers*:
+
+```bash
+uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4
+```
+
+> O parâmetro `--workers` define quantos processos simultâneos serão utilizados.
+> Idealmente, use `(número_de_CPUs * 2) + 1`.
+
+#### Alternativa compatível (Windows)
+
+Instale e use o **Hypercorn**, uma alternativa semelhante ao Gunicorn:
+
+```bash
+pip install hypercorn
+hypercorn main:app --workers 4 --bind 0.0.0.0:8000
+```
+
+---
+
+### **Linux (modo produção real)**
+
+Em ambientes Linux (ou Docker), utilize o **Gunicorn** com o **Uvicorn Worker** para obter o máximo desempenho.
+
+#### Instalar Gunicorn (caso ainda não instalado)

 ```bash
 pip install gunicorn uvicorn
 ```

-### Execução com múltiplos núcleos
-
-Use o comando abaixo para inicializar a aplicação com vários *workers* (núcleos):
+#### Executar com múltiplos núcleos

 ```bash
 gunicorn main:app \
@ -159,36 +186,35 @@ gunicorn main:app \
  --log-level info
 ```

-#### Parâmetros explicados
+#### Parâmetros principais

 | Parâmetro                          | Função                                   |
 | ---------------------------------- | ---------------------------------------- |
 | `-k uvicorn.workers.UvicornWorker` | Usa o Uvicorn como worker ASGI           |
 | `--workers 4`                      | Define o número de núcleos usados        |
 | `--bind 0.0.0.0:8000`              | Expõe a aplicação em todas as interfaces |
-| `--timeout 120`                    | Tempo limite de resposta (segundos)      |
-| `--log-level info`                 | Define o nível de log padrão             |
+| `--timeout 120`                    | Tempo limite de resposta (em segundos)   |
+| `--log-level info`                 | Define o nível de logs                   |

-> **Dica:** o número de workers ideal é calculado por:
->
-> ```
-> (número_de_CPUs * 2) + 1
-> ```
->
-> Exemplo: para um servidor com 2 CPUs, use `--workers 5`.
+#### Dica de cálculo de workers
+
+```
+(número_de_CPUs * 2) + 1
+```
+
+Exemplo: servidor com 2 CPUs → `--workers 5`

 ---

-### Executar em background (Linux)
+### **Execução em segundo plano (Linux)**

-Para executar de forma persistente, use **systemd** ou **supervisor**.
-Exemplo com `nohup` (execução simples):
+Para rodar a aplicação continuamente:

 ```bash
 nohup gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000 &
 ```

-Para verificar se está rodando:
+Verifique se está rodando:

 ```bash
 ps aux | grep gunicorn
@ -198,8 +224,7 @@ ps aux | grep gunicorn

 ## 9. Logs e Monitoramento

-Os logs da aplicação são gerados pelo próprio Gunicorn.
-É recomendado redirecioná-los para arquivos:
+É possível direcionar os logs de acesso e erro para arquivos dedicados:

 ```bash
 gunicorn main:app \
@ -214,7 +239,7 @@ gunicorn main:app \

 ## 10. Estrutura Recomendada de Deploy

-```bash
+```
 /app
 ├── main.py
 ├── api/
@ -231,11 +256,24 @@ gunicorn main:app \

 ## 11. Resumo dos Comandos

-| Etapa                    | Comando                                                                              |
-| ------------------------ | ------------------------------------------------------------------------------------ |
-| Clonar projeto           | `git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git`             |
-| Criar venv               | `python -m venv venv`                                                                |
-| Ativar venv              | `venv\Scripts\activate` *(Windows)*<br>`source venv/bin/activate` *(Linux/Mac)*      |
-| Instalar dependências    | `pip install -r requirements.txt`                                                    |
-| Rodar em desenvolvimento | `uvicorn main:app --reload`                                                          |
-| Rodar em produção        | `gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000` |
+| Etapa                       | Comando                                                                              |
+| --------------------------- | ------------------------------------------------------------------------------------ |
+| Clonar projeto              | `git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git`             |
+| Criar venv                  | `python -m venv venv`                                                                |
+| Ativar venv                 | `venv\Scripts\activate` *(Windows)*<br>`source venv/bin/activate` *(Linux/Mac)*      |
+| Instalar dependências       | `pip install -r requirements.txt`                                                    |
+| Rodar em desenvolvimento    | `uvicorn main:app --reload`                                                          |
+| Rodar em produção (Windows) | `uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4`                            |
+| Rodar em produção (Linux)   | `gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000` |
+| Alternativa (Windows)       | `hypercorn main:app --workers 4 --bind 0.0.0.0:8000`                                 |
+
+---
+
+## 12. Recomendações Finais
+
+* Em **Windows**, use Uvicorn ou Hypercorn apenas para testes e ambientes locais.
+* Para **produção real**, use **Linux** com Gunicorn + Uvicorn Worker, idealmente em container **Docker**.
+* Monitore o consumo de CPU/RAM e ajuste o número de *workers* conforme o ambiente.
+* Automatize o serviço em produção via **systemd** (ex: `/etc/systemd/system/saas_api.service`) para iniciar junto com o servidor.
+
+---
--- a/requirements.txt
+++ b/requirements.txt
@ -1,6 +1,7 @@
 annotated-types==0.7.0
 anyio==4.10.0
 bcrypt==3.1.7
+certifi==2025.10.5
 cffi==1.17.1
 click==8.2.1
 colorama==0.4.6
@ -11,24 +12,38 @@ fastapi==0.116.1
 firebird-base==2.0.2
 firebird-driver==2.0.2
 greenlet==3.2.4
+gunicorn==23.0.0
 h11==0.16.0
+html2text==2025.4.15
 idna==3.10
+itsdangerous==2.2.0
+lxml==6.0.2
+markdown-it-py==4.0.0
+mdurl==0.1.2
 packaging==25.0
 passlib==1.7.4
 protobuf==5.29.5
 pyasn1==0.6.1
 pycparser==2.22
+pycurl==7.45.7
 pydantic==2.11.7
 pydantic_core==2.33.2
+Pygments==2.19.2
+pypandoc==1.15
 python-dateutil==2.9.0.post0
 python-jose==3.5.0
 pytz==2025.2
+rich==14.2.0
 rsa==4.9.1
+setuptools==80.9.0
 six==1.17.0
 sniffio==1.3.1
 SQLAlchemy==2.0.42
 sqlalchemy-firebird==2.1
 starlette==0.47.2
+striprtf==0.0.29
 typing-inspection==0.4.1
 typing_extensions==4.14.1
 uvicorn==0.35.0
+wheel==0.45.1
+wptools==0.4.17