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. Configuração do Banco de Dados (Firebird)

Crie o arquivo .env na raiz do projeto e configure as variáveis de ambiente necessárias para a conexão com o banco de dados Firebird:

ORIUS_API_FDB_HOST=localhost
ORIUS_API_FDB_NAME=S:/Bases/SANTARITA.FDB
ORIUS_API_FDB_PORT=3050
ORIUS_API_FDB_USER=SYSDBA
ORIUS_API_FDB_PASSWORD=302b3c
ORIUS_API_FDB_CHARSET=UTF8
ORIUS_API_FDB_POOL_PRE_PING=true
ORIUS_API_FDB_POOL_SIZE=5
ORIUS_API_FDB_POOL_MAX_OVERFLOW=10
ORIUS_CLIENT_STATE=go

Essas configurações definem o acesso ao banco, o charset e o gerenciamento de conexões da aplicação.

---

7. Modo Desenvolvimento

Execute a aplicação em ambiente local:

uvicorn main:app --reload

O modo --reload recarrega a aplicação automaticamente ao detectar alterações no código.

Acesse a documentação da API em:

http://localhost:8000/docs

Opcionalmente, para expor a aplicação na rede:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

---

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.

---