Configuracao de Ambiente¶

Este guia explica como configurar os ambientes de development (sandbox) e production (live) da FDPlay API.

Ambientes Disponíveis¶

A API utiliza a variavel de ambiente FDPLAY_ENV para controlar qual configuracao usar.

Ambiente	Valor FDPLAY_ENV	Gateway	Uso
Development	`development` (padrao)	Stripe Test + Asaas Sandbox	Testes com cartoes sandbox
Production	`production`	Stripe Live + Asaas Producao	Cobranças reais de clientes

Arquivo de Configuração¶

Localização¶

.secrets/credentials.toml

Estrutura¶

# Ambiente de desenvolvimento (sandbox)
[development]
ENVIRONMENT = "development"

[development.mongodb]
uri = "mongodb://admin:password@localhost:27017"
database_name = "fdplay_dev"

[development.stripe]
api_key = "sk_test_SEU_KEY_STRIPE_TEST"
webhook_secret = "whsec_SEU_WEBHOOK_SECRET_STRIPE_TEST"
publishable_key = "pk_test_SEU_PUBLISHABLE_KEY"

[development.asaas]
base_url = "https://sandbox.asaas.com/api/v3"
api_key = "SEU_API_KEY_ASAAS_SANDBOX"
webhook_token = "SEU_WEBHOOK_TOKEN_ASAAS_SANDBOX"

[development.resend]
api_key = "re_SUA_API_KEY_RESEND"
from_email = "FDPlay <onboarding@resend.dev>"

[development.smtp]
enabled = true
host = "smtp.mailtrap.io"
port = 2525
username = "seu_usuario_mailtrap"
password = "sua_senha_mailtrap"
from_email = "noreply@fdplay-dev.com"

# Ambiente de producao
[production]
ENVIRONMENT = "production"

[production.mongodb]
uri = "mongodb://admin:senha_forte@mongodb:27017"
database_name = "fdplay_production"

[production.stripe]
api_key = "sk_live_SEU_KEY_STRIPE_LIVE"
webhook_secret = "whsec_SEU_WEBHOOK_SECRET_STRIPE_LIVE"
publishable_key = "pk_live_SEU_PUBLISHABLE_KEY"

[production.asaas]
base_url = "https://api.asaas.com/api/v3"
api_key = "SEU_API_KEY_ASAAS_PRODUCAO"
webhook_token = "SEU_WEBHOOK_TOKEN_ASAAS_PRODUCAO"

[production.resend]
api_key = "re_SUA_API_KEY_RESEND"
from_email = "FDPlay <noreply@fdplay.com>"

[production.smtp]
enabled = true
host = "smtp.sendgrid.net"
port = 587
username = "apikey"
password = "SUA_API_KEY_SENDGRID"
from_email = "noreply@fdplay.com"

Execucao Local¶

Development (Padrao)¶

# Nao precisa definir FDPLAY_ENV (usa development por padrao)
uvicorn application.main:app --reload --host 0.0.0.0 --port 8000

O que acontece: - Usa secao [development] do credentials.toml - Conecta ao Stripe Test Mode + Asaas Sandbox - Aceita cartoes de teste - Emails enviados para Mailtrap (nao chegam aos clientes)

Production (Explícito)¶

# Define FDPLAY_ENV=production
FDPLAY_ENV=production uvicorn application.main:app --host 0.0.0.0 --port 8000

O que acontece: - Usa secao [production] do credentials.toml - Conecta ao Stripe Live + Asaas Producao - Cobranças reais processadas - Emails reais enviados aos clientes

Docker Compose¶

Arquivo: `docker-compose.yml`¶

version: '3.8'

services:
    fdplay-api:
        build: .
        container_name: fdplay-api
        environment:
            - FDPLAY_ENV=production  # <- Define ambiente aqui
        ports:
            - "8000:8000"
        volumes:
            - ./.secrets:/app/.secrets:ro  # Monta credenciais
        depends_on:
            - mongodb

    mongodb:
        image: mongo:7.0
        container_name: fdplay-mongodb
        ports:
            - "27017:27017"
        environment:
            MONGO_INITDB_ROOT_USERNAME: admin
            MONGO_INITDB_ROOT_PASSWORD: senha_forte
        volumes:
            - mongodb_data:/data/db

volumes:
    mongodb_data:

Deploy¶

# Development
docker compose up -d

# Production (override environment)
FDPLAY_ENV=production docker compose up -d

GitHub Actions (CI/CD)¶

Workflow: `.github/workflows/deploy-to-vps.yml`¶

name: Deploy to VPS

on:
    push:
        branches: [main]

jobs:
    deploy:
        runs-on: ubuntu-latest
        steps:
            - uses: actions/checkout@v3

            - name: Deploy to VPS
                env:
                    SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }}
                    VPS_HOST: ${{ secrets.VPS_HOST }}
                    VPS_USER: ${{ secrets.VPS_USER }}
                run: |
                    # Setup SSH
                    mkdir -p ~/.ssh
                    echo "$SSH_PRIVATE_KEY" > ~/.ssh/id_rsa
                    chmod 600 ~/.ssh/id_rsa

                    # Deploy
                    ssh $VPS_USER@$VPS_HOST << 'EOF'
                        cd /root/fdplay-api
                        git pull origin main

                        # Define ambiente (mude para production quando aprovado)
                        export FDPLAY_ENV=development

                        # Restart
                        docker compose down
                        docker compose up -d --build
                    EOF

Status atual: Deploy usa FDPLAY_ENV=development (sandbox).

Para ir para producao: Trocar export FDPLAY_ENV=development por export FDPLAY_ENV=production apos configurar credenciais de producao do Stripe e Asaas.

Validacao de Ambiente¶

Via Python¶

from application.infrastructure.common.config import CONFIG

print(f"Ambiente: {CONFIG.ENVIRONMENT}")
print(f"MongoDB: {CONFIG.MONGODB['database_name']}")

Output esperado (development):

Ambiente: development
MongoDB: fdplay_dev

Output esperado (production):

Ambiente: production
MongoDB: fdplay_production

Via API (Endpoint de Debug — Removido)¶

⚠️ GET /api/v1/debug/environment não existe na API. Este endpoint foi removido e não deve ser usado nem referenciado. Use a validação via Python descrita acima para verificar o ambiente em execução.

Dados de Teste (Sandbox)¶

Cartoes de Teste Stripe¶

Numero	Resultado
`4242 4242 4242 4242`	Aprovado
`4000 0000 0000 0002`	Recusado
`4000 0025 0000 3155`	Requer autenticacao 3D Secure

CVV: qualquer 3 digitos. Validade: qualquer data futura.

Cartoes de Teste Asaas Sandbox¶

Utilize os cartoes de teste fornecidos na documentacao Asaas para testar pagamentos em ambiente sandbox.

CPFs Validos¶

12345678909
11144477735
98765432100

Sandbox Only

Estes dados so funcionam em ambiente development (sandbox). Em producao, use dados reais.

Seguranca¶

Boas Praticas¶

Nunca commitar .secrets/credentials.toml
- Arquivo esta no .gitignore
- Use credentials.exemple.toml como template
Chaves diferentes por ambiente
- Chaves sandbox/test para development
- Chaves de producao para production
- Nunca use chaves de producao em testes
Webhook secrets diferentes por ambiente
- Um secret para sandbox/test
- Outro secret para producao

Troubleshooting¶

Erro: `KeyError: 'production'`¶

Causa: Secao [production] nao existe em credentials.toml.

Solucao:

# Copiar template
cp .secrets/credentials.exemple.toml .secrets/credentials.toml

# Editar e preencher valores reais
nano .secrets/credentials.toml

Erro: `ValueError: Invalid FDPLAY_ENV value`¶

Causa: Valor invalido em FDPLAY_ENV.

Solucao: Use apenas development ou production:

FDPLAY_ENV=development  # OK
FDPLAY_ENV=production   # OK
FDPLAY_ENV=staging      # Invalido

Deploy usa ambiente errado¶

Verificar:

# No servidor
docker compose exec fdplay-api env | grep FDPLAY_ENV

Corrigir:

# Re-deploy com environment correto
export FDPLAY_ENV=production
docker compose down
docker compose up -d

Checklist de Go-Live¶

Antes de mudar para FDPLAY_ENV=production:

[ ] Conta Stripe configurada com chaves de producao
[ ] Webhook Stripe configurado (URL de producao, whsec_* salvo)
[ ] Conta Asaas configurada com API key de producao
[ ] Webhook Asaas configurado (token de producao salvo)
[ ] SMTP configurado com enabled = true (Gmail/SendGrid/SES) para emails reais
[ ] Resend API key configurada (fallback se SMTP falhar)
[ ] Banco de dados de producao com backup configurado
[ ] Testes completos em sandbox executados com sucesso
[ ] Monitoramento de logs configurado
[ ] Plano de rollback definido

Referencias¶

ADR-024: Decisao de usar variavel de ambiente FDPLAY_ENV
12-Factor App: https://12factor.net/config
Stripe Test Mode: https://docs.stripe.com/testing
Asaas Sandbox: https://docs.asaas.com/docs/sandbox
Template de Credenciais: .secrets/credentials.exemple.toml