Onboarding — primeiros 60 minutos¶

Objetivo: ter o sistema rodando localmente e ler 1 sinal real.

0. Pré-requisitos¶

Ferramenta	Versão mínima	Instalar
Python	3.11+	python.org
Docker Desktop	4.0+	docker.com
Git	2.30+	git-scm.com
MetaTrader 5	última	corretora
PowerShell	5.1+ (Windows)	built-in
WireGuard	0.5+	wireguard.com

Conta no Backblaze B2 (para backup local) — opcional inicialmente.

1. Clone¶

cd C:\Users\henri\Documents\PROJETOS
git clone https://github.com/henriqueferrazmoura/ML-Forex.git
cd ML-Forex

2. Python venv + dependências¶

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Tempo: ~3-5 min.

3. `.env` local¶

Copiar template e preencher:

Copy-Item .env.template .env
notepad .env

Variáveis críticas:

# DB local (Docker)
DATABASE_URL=postgresql+asyncpg://forex:<senha>@localhost:5432/forex
DB_PASSWORD=<senha>
DB_HOST=localhost

# API
API_KEY=dev-key-aqui
ADMIN_SECRET=admin-secret-dev

# Redis local
REDIS_URL=redis://localhost:6379/0

# Eduzz (dev: vazio = webhook bloqueado, seguro)
EDUZZ_SECRET=

# SMTP (dev: vazio = emails em log apenas)
SMTP_USER=
SMTP_PASS=

# Backblaze (dev: opcional)
B2_KEY_ID=
B2_APP_KEY=
B2_BUCKET_NAME=

Nunca commitar .env

Já está em .gitignore. Confira antes de git add.

4. Subir DB + Redis (Docker)¶

docker compose up -d db redis

Aguardar healthy:

docker compose ps
# Status esperado: forex_db (healthy), forex_redis (healthy)

5. Aplicar schema¶

O DB foi criado vazio. Aplicar init.sql:

docker exec -i forex_db psql -U forex -d forex < docker/init.sql

Validar:

docker exec forex_db psql -U forex -d forex -c "\dt"
# Esperado: candles, predictions, executions, api_keys, symbols, timeframes, etc.

6. Bootstrap de candles (histórico)¶

.venv\Scripts\python.exe scripts\download_history.py EURUSD H1

Demora ~30 segundos. Conferir:

docker exec forex_db psql -U forex -d forex -c "SELECT COUNT(*) FROM candles;"
# Esperado: ~10000+ rows

7. Treinar primeiro modelo¶

.venv\Scripts\python.exe scripts\run_training.py --symbol EURUSD --tf H1

Demora ~5-10 min (depende da CPU). Output:

[train] LGBM finished. AUC=0.612, ECE=0.21
[train] XGB finished. AUC=0.598, ECE=0.23
[train] CatBoost finished. AUC=0.595, ECE=0.20
[train] Ensemble blend. AUC=0.621
[train] Promoted as champion EURUSD_H1.
[train] Saved models/lgbm_EURUSD_H1_v<hash>.pkl

8. Subir worker + API¶

docker compose up -d --build worker api

Conferir logs:

docker logs forex_worker --tail 30
docker logs forex_api --tail 10

9. Primeira request¶

curl http://localhost:8000/api/health
# {"status":"ok","db":"ok",...}

curl -H "X-API-Key: dev-key-aqui" http://localhost:8000/api/scan
# {"items":[...],"plan_tier":"owner"}

10. Acessar frontend¶

Abrir browser em http://localhost:8000.

Landing page → /
Minha conta → /minha-conta (digite dev-key-aqui → entra como owner)
Dashboard → /dashboard

Próximos passos¶

Retreino de Modelos — adicionar mais símbolos/TFs
Ambiente Local — configurar MT5 + EA local
API endpoints — exploração completa

Troubleshooting¶

Erro	Solução
`psycopg2.OperationalError: connection refused`	`docker compose up -d db` ainda inicializando, aguarde 30s
`redis.exceptions.ConnectionError`	`docker compose up -d redis`
`KeyError: 'API_KEY'`	`.env` não tem `API_KEY` definido
`ModuleNotFoundError: asyncpg`	`.venv` não ativado ou `pip install -r requirements.txt` falhou
API retorna 401 mesmo com chave	Verificar `X-API-Key:` header (não `Authorization:`)
`/api/scan` retorna lista vazia	Modelos ainda não treinados (passo 7)