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:

git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git

---

2. Criar o Ambiente Virtual

Crie um ambiente virtual isolado para o projeto:

python -m venv venv

---

3. Ativar o Ambiente Virtual

Ative o ambiente virtual antes de instalar as dependências:

venv\Scripts\activate

Em sistemas Linux/Mac:

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/

Durante a instalação, selecione o pacote:

Desktop Development With C++

Linux

Execute no terminal:

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:

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:

{
  "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:

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:

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:

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)

pip install gunicorn uvicorn

Executar com múltiplos núcleos

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:

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

Verifique se está rodando:

ps aux | grep gunicorn

---

9. Logs e Monitoramento

É possível direcionar os logs de acesso e erro para arquivos dedicados:

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) 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 --reload