From ffdda4f022f786bec51163eff6442258fd149412 Mon Sep 17 00:00:00 2001 From: Keven Date: Mon, 8 Dec 2025 12:03:56 -0300 Subject: [PATCH] fix(Deploy): Ajustes diversos para deploy --- README.md | 122 +++++++++++++++++++++++++++++++---------------- requirements.txt | 15 ++++++ 2 files changed, 95 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index bf99970..551ae36 100644 --- 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)*
`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)*
`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. + +--- diff --git a/requirements.txt b/requirements.txt index 5cbebd6..bdfb56f 100644 --- 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