281 lines
7 KiB
Markdown
281 lines
7 KiB
Markdown
# 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 ambiente virtual, dependências, banco de dados, e ajuste de desempenho com múltiplos núcleos.
|
|
|
|
---
|
|
|
|
## 1. Clonar o Projeto
|
|
|
|
Clone o repositório do projeto a partir do Git:
|
|
|
|
```bash
|
|
git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Criar o Ambiente Virtual
|
|
|
|
Crie um **ambiente virtual** isolado para o projeto:
|
|
|
|
```bash
|
|
python -m venv venv
|
|
```
|
|
|
|
---
|
|
|
|
## 3. Ativar o Ambiente Virtual
|
|
|
|
Ative o ambiente virtual antes de instalar as dependências:
|
|
|
|
```bash
|
|
venv\Scripts\activate
|
|
```
|
|
|
|
> **Em sistemas Linux/Mac:**
|
|
>
|
|
> ```bash
|
|
> source venv/bin/activate
|
|
> ```
|
|
|
|
---
|
|
|
|
## 4. Instalar Dependências do Sistema
|
|
|
|
O projeto depende de compiladores nativos para algumas bibliotecas Python.
|
|
|
|
### Windows
|
|
|
|
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/)
|
|
|
|
Durante a instalação, selecione o pacote:
|
|
|
|
```
|
|
Desktop Development With C++
|
|
```
|
|
|
|
### Linux
|
|
|
|
Execute no terminal:
|
|
|
|
```bash
|
|
sudo apt update
|
|
sudo apt install -y build-essential libpq-dev
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Instalar as Bibliotecas do Projeto
|
|
|
|
Com o ambiente virtual **ativado**, instale as dependências listadas no arquivo `requirements.txt`:
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Configurar o Banco de Dados (Firebird)
|
|
|
|
O projeto utiliza o banco **Firebird**.
|
|
Edite o arquivo de configuração em:
|
|
|
|
```
|
|
api/config/database/firebird.json
|
|
```
|
|
|
|
Exemplo:
|
|
|
|
```json
|
|
{
|
|
"host": "localhost",
|
|
"name": "/data/base/CAIAPONIA.FDB",
|
|
"port": 3050,
|
|
"user": "SYSDBA",
|
|
"password": "",
|
|
"charset": "UTF8",
|
|
"pool": {
|
|
"pre_ping": true,
|
|
"size": 5,
|
|
"max_overflow": 10
|
|
}
|
|
}
|
|
```
|
|
|
|
**Campos principais:**
|
|
|
|
| Campo | Descrição |
|
|
| ------------------- | ---------------------------------- |
|
|
| `host` | Endereço do servidor Firebird |
|
|
| `name` | Caminho completo do arquivo `.FDB` |
|
|
| `port` | Porta padrão `3050` |
|
|
| `user` | Usuário do banco |
|
|
| `password` | Senha do usuário |
|
|
| `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:
|
|
|
|
```bash
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
> O parâmetro `--reload` reinicia automaticamente a aplicação ao detectar alterações no código.
|
|
|
|
Acesse:
|
|
|
|
```
|
|
http://localhost:8000/docs
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Modo Produção
|
|
|
|
A execução em produção varia conforme o sistema operacional.
|
|
|
|
---
|
|
|
|
### **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
|
|
```
|
|
|
|
#### Executar com múltiplos núcleos
|
|
|
|
```bash
|
|
gunicorn main:app \
|
|
-k uvicorn.workers.UvicornWorker \
|
|
--workers 4 \
|
|
--bind 0.0.0.0:8000 \
|
|
--timeout 120 \
|
|
--log-level info
|
|
```
|
|
|
|
#### 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 (em segundos) |
|
|
| `--log-level info` | Define o nível de logs |
|
|
|
|
#### Dica de cálculo de workers
|
|
|
|
```
|
|
(número_de_CPUs * 2) + 1
|
|
```
|
|
|
|
Exemplo: servidor com 2 CPUs → `--workers 5`
|
|
|
|
---
|
|
|
|
### **Execução em segundo plano (Linux)**
|
|
|
|
Para rodar a aplicação continuamente:
|
|
|
|
```bash
|
|
nohup gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000 &
|
|
```
|
|
|
|
Verifique se está rodando:
|
|
|
|
```bash
|
|
ps aux | grep gunicorn
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Logs e Monitoramento
|
|
|
|
É possível direcionar os logs de acesso e erro para arquivos dedicados:
|
|
|
|
```bash
|
|
gunicorn main:app \
|
|
-k uvicorn.workers.UvicornWorker \
|
|
--workers 4 \
|
|
--bind 0.0.0.0:8000 \
|
|
--access-logfile logs/access.log \
|
|
--error-logfile logs/error.log
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Estrutura Recomendada de Deploy
|
|
|
|
```
|
|
/app
|
|
├── main.py
|
|
├── api/
|
|
├── packages/
|
|
├── requirements.txt
|
|
├── logs/
|
|
│ ├── access.log
|
|
│ └── error.log
|
|
└── systemd/
|
|
└── saas_api.service
|
|
```
|
|
|
|
---
|
|
|
|
## 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 (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.
|
|
|
|
---
|
|
|
|
uvicorn main:app --host 0.0.0.0 --port 8000
|