ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad-web/docs/deployment-guide.md

567 lines
12 KiB
Markdown
Raw Blame History

# BMAD Web - Guia de Deploy
Este guia cobre todas as opcoes de deploy para a aplicacao BMAD Web.
---
## Sumario
1. [Arquitetura de Deploy](#arquitetura-de-deploy)
2. [Opcao 1: Vercel + Railway (Recomendado)](#opcao-1-vercel--railway-recomendado)
3. [Opcao 2: Docker Compose (Self-hosted)](#opcao-2-docker-compose-self-hosted)
4. [Opcao 3: Kubernetes](#opcao-3-kubernetes)
5. [Configuracao de Banco de Dados](#configuracao-de-banco-de-dados)
6. [Variaveis de Ambiente](#variaveis-de-ambiente)
7. [CI/CD com GitHub Actions](#cicd-com-github-actions)
8. [Monitoramento](#monitoramento)
9. [Checklist de Producao](#checklist-de-producao)
---
## Arquitetura de Deploy
```
┌─────────────────────────────────────────────────────────────────────┐
│ PRODUCAO │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Vercel │ │ Railway │ │ Supabase │ │
│ │ (Next.js) │◄───────►│ (API) │◄───────►│ (Postgres)│ │
│ │ │ │ │ │ │ │
│ │ Frontend │ REST │ Backend │ SQL │ Database │ │
│ │ + CDN │ + WS │ + Socket │ │ + Auth │ │
│ └──────────────┘ └──────────────┘ └────────────┘ │
│ │ │ │ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Cloudflare │ │ Upstash │ │ S3 │ │
│ │ (DNS) │ │ (Redis) │ │ (Assets) │ │
│ └──────────────┘ └──────────────┘ └────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
```
---
## Opcao 1: Vercel + Railway (Recomendado)
A opcao mais simples para comecar. Zero configuracao de infraestrutura.
### 1.1 Deploy do Frontend (Vercel)
#### Passo 1: Conectar repositorio
```bash
# Instalar Vercel CLI
npm i -g vercel
# Login
vercel login
# Na pasta bmad-web/apps/web
cd bmad-web/apps/web
vercel
```
#### Passo 2: Configurar no Dashboard Vercel
1. Acesse https://vercel.com/dashboard
2. Import o repositorio do GitHub
3. Configure:
- **Framework Preset**: Next.js
- **Root Directory**: `bmad-web/apps/web`
- **Build Command**: `npm run build`
- **Output Directory**: `.next`
#### Passo 3: Variaveis de Ambiente
No dashboard Vercel, adicione:
```
NEXT_PUBLIC_API_URL=https://sua-api.railway.app
NEXT_PUBLIC_WS_URL=wss://sua-api.railway.app
NEXT_PUBLIC_APP_URL=https://seu-app.vercel.app
```
#### Passo 4: Deploy
```bash
# Deploy de producao
vercel --prod
```
---
### 1.2 Deploy da API (Railway)
#### Passo 1: Criar projeto Railway
1. Acesse https://railway.app
2. New Project > Deploy from GitHub repo
3. Selecione o repositorio
#### Passo 2: Configurar servico
No dashboard Railway:
1. **Root Directory**: `bmad-web/apps/api`
2. **Build Command**: `npm run build`
3. **Start Command**: `npm start`
#### Passo 3: Variaveis de Ambiente
```
NODE_ENV=production
PORT=4000
FRONTEND_URL=https://seu-app.vercel.app
JWT_SECRET=sua-chave-super-secreta-aqui
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
BMAD_ROOT=/app/../../..
```
#### Passo 4: Adicionar Postgres (Railway)
1. No projeto Railway, clique em "New"
2. Selecione "Database" > "PostgreSQL"
3. Copie a DATABASE_URL gerada
#### Passo 5: Adicionar Redis (Upstash)
1. Acesse https://upstash.com
2. Crie um banco Redis
3. Copie a REDIS_URL
---
### 1.3 Comandos Rapidos (Vercel + Railway)
```bash
# Frontend
cd bmad-web/apps/web
vercel --prod
# Backend (Railway CLI)
npm i -g @railway/cli
railway login
cd bmad-web/apps/api
railway up
```
---
## Opcao 2: Docker Compose (Self-hosted)
Para quem quer controle total ou rodar on-premise.
### 2.1 Arquivos Docker
Os arquivos ja estao criados:
- `bmad-web/Dockerfile.web` - Frontend
- `bmad-web/Dockerfile.api` - Backend
- `bmad-web/docker-compose.yml` - Orquestracao
- `bmad-web/docker-compose.prod.yml` - Producao
### 2.2 Build e Run Local
```bash
cd bmad-web
# Desenvolvimento
docker-compose up -d
# Producao
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
```
### 2.3 Deploy em VPS (DigitalOcean, Hetzner, etc.)
```bash
# 1. SSH na VPS
ssh root@seu-servidor
# 2. Instalar Docker
curl -fsSL https://get.docker.com | sh
# 3. Clonar repositorio
git clone https://github.com/seu-usuario/BMAD-METHOD.git
cd BMAD-METHOD/bmad-web
# 4. Configurar ambiente
cp .env.example .env
nano .env # Editar variaveis
# 5. Subir servicos
docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d
# 6. Configurar Nginx (proxy reverso)
apt install nginx
# Copiar config do nginx.conf
```
### 2.4 Com Traefik (HTTPS automatico)
```bash
# Usar docker-compose.traefik.yml para HTTPS automatico
docker-compose -f docker-compose.yml -f docker-compose.traefik.yml up -d
```
---
## Opcao 3: Kubernetes
Para escala enterprise.
### 3.1 Estrutura
```
bmad-web/k8s/
├── namespace.yaml
├── configmap.yaml
├── secrets.yaml
├── web-deployment.yaml
├── api-deployment.yaml
├── postgres-deployment.yaml
├── redis-deployment.yaml
├── ingress.yaml
└── hpa.yaml
```
### 3.2 Deploy
```bash
# Criar namespace
kubectl apply -f k8s/namespace.yaml
# Aplicar configs
kubectl apply -f k8s/
# Verificar status
kubectl get pods -n bmad
```
---
## Configuracao de Banco de Dados
### Opcao A: Supabase (Recomendado)
1. Crie conta em https://supabase.com
2. Crie novo projeto
3. Copie a connection string:
```
DATABASE_URL=postgresql://postgres:[senha]@db.[ref].supabase.co:5432/postgres
```
### Opcao B: PlanetScale (MySQL)
1. Crie conta em https://planetscale.com
2. Crie database
3. Copie connection string
### Opcao C: Neon (Postgres Serverless)
1. Crie conta em https://neon.tech
2. Crie projeto
3. Copie connection string
### Migrations
```bash
cd bmad-web/apps/api
# Gerar cliente Prisma
npx prisma generate
# Push schema para banco
npx prisma db push
# Ou usar migrations
npx prisma migrate deploy
```
---
## Variaveis de Ambiente
### Frontend (.env.local)
```bash
# API
NEXT_PUBLIC_API_URL=https://api.bmad.app
NEXT_PUBLIC_WS_URL=wss://api.bmad.app
# App
NEXT_PUBLIC_APP_URL=https://bmad.app
NEXT_PUBLIC_APP_NAME=BMAD
# Analytics (opcional)
NEXT_PUBLIC_MIXPANEL_TOKEN=xxx
NEXT_PUBLIC_GA_ID=G-xxx
# Feature Flags (opcional)
NEXT_PUBLIC_ENABLE_BILLING=true
```
### Backend (.env)
```bash
# Server
NODE_ENV=production
PORT=4000
# URLs
FRONTEND_URL=https://bmad.app
# Auth
JWT_SECRET=sua-chave-jwt-muito-secreta-minimo-32-chars
# Database
DATABASE_URL=postgresql://user:pass@host:5432/bmad
# Redis
REDIS_URL=redis://default:pass@host:6379
# BMAD Core
BMAD_ROOT=/app/bmad-core
# AI Providers
OPENAI_API_KEY=sk-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
# Stripe (billing)
STRIPE_SECRET_KEY=sk_live_xxx
STRIPE_WEBHOOK_SECRET=whsec_xxx
# Email (opcional)
SMTP_HOST=smtp.sendgrid.net
SMTP_USER=apikey
SMTP_PASS=SG.xxx
# Monitoring (opcional)
SENTRY_DSN=https://xxx@sentry.io/xxx
```
### Gerar JWT_SECRET Seguro
```bash
openssl rand -base64 32
```
---
## CI/CD com GitHub Actions
### Arquivo: `.github/workflows/deploy.yml`
```yaml
name: Deploy
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: cd bmad-web && npm ci
- name: Lint
run: cd bmad-web && npm run lint
- name: Test
run: cd bmad-web && npm test
deploy-frontend:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: amondnet/vercel-action@v25
with:
vercel-token: ${{ secrets.VERCEL_TOKEN }}
vercel-org-id: ${{ secrets.VERCEL_ORG_ID }}
vercel-project-id: ${{ secrets.VERCEL_PROJECT_ID }}
working-directory: bmad-web/apps/web
vercel-args: '--prod'
deploy-backend:
needs: test
if: github.ref == 'refs/heads/main'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: railwayapp/railway-action@v1
with:
railway-token: ${{ secrets.RAILWAY_TOKEN }}
service: api
```
---
## Monitoramento
### Sentry (Error Tracking)
```bash
# Instalar
npm install @sentry/nextjs @sentry/node
# Configurar em next.config.js e api/src/index.ts
```
### Uptime Monitoring
- **Better Uptime**: https://betteruptime.com
- **UptimeRobot**: https://uptimerobot.com
Endpoints para monitorar:
- `https://bmad.app` (frontend)
- `https://api.bmad.app/health` (backend)
### Analytics
- **Mixpanel**: Eventos de produto
- **Google Analytics**: Trafego
- **PostHog**: Open-source alternativa
---
## Checklist de Producao
### Seguranca
- [ ] JWT_SECRET forte (32+ chars)
- [ ] HTTPS em todos os endpoints
- [ ] Rate limiting configurado
- [ ] CORS configurado corretamente
- [ ] Headers de seguranca (helmet)
- [ ] Variaveis sensiveis em secrets manager
### Performance
- [ ] CDN para assets estaticos
- [ ] Cache Redis funcionando
- [ ] Compressao gzip habilitada
- [ ] Images otimizadas (next/image)
- [ ] Bundle size otimizado
### Banco de Dados
- [ ] Backups automaticos configurados
- [ ] Connection pooling (PgBouncer)
- [ ] Indices criados para queries frequentes
- [ ] SSL habilitado na conexao
### Monitoramento
- [ ] Error tracking (Sentry)
- [ ] Uptime monitoring
- [ ] Log aggregation
- [ ] Alertas configurados
### Legal/Compliance
- [ ] Termos de Servico
- [ ] Politica de Privacidade
- [ ] Cookie consent
- [ ] LGPD/GDPR compliance
---
## Troubleshooting
### Erro: "WebSocket connection failed"
```bash
# Verificar se WebSocket esta habilitado no Railway/Vercel
# Railway: ja suporta nativamente
# Vercel: usar Vercel Serverless Functions com upgrade
```
### Erro: "Database connection timeout"
```bash
# Verificar DATABASE_URL
# Adicionar ?connect_timeout=10&pool_timeout=10
DATABASE_URL=postgresql://...?connect_timeout=10
```
### Erro: "JWT invalid"
```bash
# Verificar se JWT_SECRET e o mesmo em todos os servicos
# Verificar timezone dos servidores
```
### Build falha no Vercel
```bash
# Verificar se todas as deps estao no package.json
# Verificar se NEXT_PUBLIC_* estao configuradas
# Verificar Root Directory
```
---
## Comandos Uteis
```bash
# Logs da API (Railway)
railway logs
# Logs do Frontend (Vercel)
vercel logs
# SSH no container Docker
docker exec -it bmad-api sh
# Prisma Studio (visualizar banco)
npx prisma studio
# Reset do banco (CUIDADO!)
npx prisma migrate reset
```
---
## Custos Estimados
### Startup (0-1000 usuarios)
| Servico | Custo/mes |
|---------|-----------|
| Vercel (Hobby) | $0 |
| Railway (Starter) | $5 |
| Supabase (Free) | $0 |
| Upstash (Free) | $0 |
| **Total** | **$5/mes** |
### Growth (1000-10000 usuarios)
| Servico | Custo/mes |
|---------|-----------|
| Vercel (Pro) | $20 |
| Railway (Pro) | $20 |
| Supabase (Pro) | $25 |
| Upstash (Pay-as-go) | $10 |
| **Total** | **$75/mes** |
### Scale (10000+ usuarios)
| Servico | Custo/mes |
|---------|-----------|
| Vercel (Enterprise) | $150+ |
| Railway (Team) | $50+ |
| Supabase (Team) | $599+ |
| Redis (Managed) | $50+ |
| **Total** | **$850+/mes** |
View Git Blame Copy Permalink