OriusTecnologia/saas_api
6
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(Readme): Adiciona configurações de servidor em produção

Browse source
This commit is contained in:
Keven 2025-12-08 10:51:08 -03:00
parent 8258ee97c3
commit c315185cd5
1 changed files with 140 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

181
README.md
View file

@ -1,12 +1,12 @@
# Configuração do Projeto Python
Este guia descreve o passo a passo para configurar o ambiente de desenvolvimento de um projeto Python, incluindo a preparação do ambiente virtual, instalação de dependências e configuração do banco de dados.
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
Primeiro, clone o repositório do projeto a partir do Git:
Clone o repositório do projeto a partir do Git:
```bash
git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git
@ -16,7 +16,7 @@ git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git
## 2. Criar o Ambiente Virtual
O uso de um **ambiente virtual** garante que as bibliotecas instaladas para este projeto não afetem o Python global da sua máquina.
Crie um **ambiente virtual** isolado para o projeto:
```bash
python -m venv venv
@ -26,14 +26,13 @@ python -m venv venv
## 3. Ativar o Ambiente Virtual
Ative o ambiente virtual antes de instalar as dependências ou executar a aplicação.
Ative o ambiente virtual antes de instalar as dependências:
```bash
venv\Scripts\activate
```
> **Observação:**
> Em sistemas Unix (Linux/Mac), o comando pode ser:
> **Em sistemas Linux/Mac:**
>
> ```bash
> source venv/bin/activate
@ -43,22 +42,33 @@ venv\Scripts\activate
## 4. Instalar Dependências do Sistema
A biblioteca de criptografia utilizada no projeto requer uma extensão da Microsoft para ser instalada.
Baixe e instale o **Microsoft C++ Build Tools** através do link abaixo:
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/](https://visualstudio.microsoft.com/pt-br/visual-cpp-build-tools/)
Durante a instalação, selecione o pacote:
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`:
Com o ambiente virtual **ativado**, instale as dependências:
```bash
pip install -r requirements.txt
@ -68,19 +78,19 @@ pip install -r requirements.txt
## 6. Configurar o Banco de Dados
O projeto utiliza um banco **Firebird**.
Edite o arquivo de configuração localizado em:
O projeto utiliza o banco **Firebird**.
Edite o arquivo de configuração em:
```
api/config/database/firebird.json
```
Exemplo do conteúdo padrão:
Exemplo:
```json
{
"host": "localhost",
"name": "D:/Orius/Base/CAIAPONIA.FDB",
"name": "/data/base/CAIAPONIA.FDB",
"port": 3050,
"user": "SYSDBA",
"password": "",
@ -93,50 +103,139 @@ Exemplo do conteúdo padrão:
}
```
### Ajustes Necessários:
**Campos:**
* **host**: Endereço do servidor do banco de dados.
* **name**: Caminho completo do arquivo `.FDB`.
* **port**: Porta do Firebird (padrão: `3050`).
* **user**: Usuário do banco de dados.
* **password**: Senha do usuário configurado.
| 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. Iniciar a Aplicação
## 7. Modo Desenvolvimento
Com o ambiente virtual **ativado**, execute o comando abaixo para iniciar a aplicação:
Para ambiente **local**, execute:
```bash
uvicorn main:app --reload
```
> **Dica:**
> O parâmetro `--reload` reinicia automaticamente a aplicação sempre que houver alterações no código.
> O parâmetro `--reload` reinicia a aplicação automaticamente quando há alterações no código.
---
Acesse:
## 8. Testando a Aplicação
Após iniciar a aplicação, abra o navegador e acesse o seguinte endereço:
```http
```
http://localhost:8000/docs
```
Você deverá visualizar a interface do **Swagger**, onde estarão listados todos os endpoints disponíveis da API.
---
> **Observação:**
> O Swagger permite testar os endpoints diretamente pelo navegador, sem necessidade de ferramentas externas como Postman ou Insomnia.
## 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
```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):
```bash
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`.
---
## Resumo dos Comandos
### Executar em background (Linux)
| Etapa | Comando |
| ----------------------- | ------------------------------------------------------------------------------- |
| Clonar o projeto | `git clone https://git.oriustecnologia.com/OriusTecnologia/saas_api.git` |
| Criar ambiente virtual | `python -m venv venv` |
| Ativar ambiente virtual | `venv\Scripts\activate` *(Windows)*<br>`source venv/bin/activate` *(Linux/Mac)* |
| Instalar dependências | `pip install -r requirements.txt` |
| Iniciar a aplicação | `uvicorn main:app --reload` |
Para executar de forma persistente, use **systemd** ou **supervisor**.
Exemplo com `nohup` (execução simples):
```bash
nohup gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000 &
```
Para verificar se está rodando:
```bash
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:
```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
```bash
/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 | `gunicorn main:app -k uvicorn.workers.UvicornWorker --workers 4 --bind 0.0.0.0:8000` |