saas_api/README.md

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.

---

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 utiliza bibliotecas que dependem do Microsoft C++ Build Tools (Windows) ou build-essential (Linux).

Windows

Baixe e instale: https://visualstudio.microsoft.com/pt-br/visual-cpp-build-tools/

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:

pip install -r requirements.txt

---

6. Configurar o Banco de Dados

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:

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 recomendada: UTF8
pool.size	Conexões mínimas por núcleo
pool.max_overflow	Conexões extras sob demanda

---

7. Modo Desenvolvimento

Para ambiente local, execute:

uvicorn main:app --reload

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

Acesse:

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.

Instalação

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

gunicorn main:app \
  -k uvicorn.workers.UvicornWorker \
  --workers 4 \
  --bind 0.0.0.0:8000 \
  --timeout 120 \
  --log-level info

Parâmetros explicados

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

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.

---

Executar em background (Linux)

Para executar de forma persistente, use systemd ou supervisor. Exemplo com nohup (execução simples):

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

Para verificar se está rodando:

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:

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	gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000