DEPLOYMENT.md•10.5 kB
# Guia de Deployment - MCP WPPConnect Server
Este guia fornece instruções detalhadas para fazer deployment do MCP WPPConnect Server em diferentes ambientes.
## 📋 Índice
1. [Preparação](#preparação)
2. [Deployment Local](#deployment-local)
3. [Deployment em Servidor](#deployment-em-servidor)
4. [Deployment com Docker](#deployment-com-docker)
5. [Deployment com PM2](#deployment-com-pm2)
6. [Configuração de Produção](#configuração-de-produção)
7. [Monitoramento](#monitoramento)
8. [Backup e Recuperação](#backup-e-recuperação)
9. [Troubleshooting de Deployment](#troubleshooting-de-deployment)
---
## 🚀 Preparação
### 1. Verificar Requisitos
```bash
# Verificar Node.js (requer 18+)
node --version
# Verificar npm
npm --version
```
### 2. Clonar e Preparar o Projeto
```bash
# Clone o repositório
git clone <url-do-repositorio>
cd mcp-wppconnect-server
# Instalar dependências
npm install
# Build do projeto
npm run build
```
### 3. Testar Localmente
```bash
# Testar build
npm run build
# Testar execução
npm start
```
---
## 🏠 Deployment Local
### Opção 1: Execução Direta
```bash
# Build
npm run build
# Executar
npm start
```
### Opção 2: Com PM2 Local
```bash
# Instalar PM2 globalmente
npm install -g pm2
# Criar configuração PM2
echo 'module.exports = {
apps: [{
name: "mcp-wppconnect-server",
script: "./build/index.js",
instances: 1,
autorestart: true,
watch: false,
max_memory_restart: "1G",
env: {
NODE_ENV: "development",
DEBUG: "mcp-wppconnect:*"
},
env_production: {
NODE_ENV: "production"
}
}]
};' > ecosystem.config.js
# Iniciar com PM2
pm2 start ecosystem.config.js
```
---
## 🖥️ Deployment em Servidor
### 1. Preparar Servidor
```bash
# Atualizar sistema (Ubuntu/Debian)
sudo apt update && sudo apt upgrade -y
# Instalar Node.js 18+
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt-get install -y nodejs
# Instalar build essentials
sudo apt install -y build-essential
```
### 2. Configurar Usuário
```bash
# Criar usuário dedicado
sudo adduser mcp-wppconnect
sudo usermod -aG sudo mcp-wppconnect
# Mudar para o novo usuário
su - mcp-wppconnect
```
### 3. Instalar e Configurar
```bash
# Clone o repositório
git clone <url-do-repositorio>
cd mcp-wppconnect-server
# Instalar dependências
npm install
# Build
npm run build
```
### 4. Configurar como Serviço Systemd
```bash
# Criar arquivo de serviço
sudo nano /etc/systemd/system/mcp-wppconnect.service
```
Conteúdo do arquivo:
```ini
[Unit]
Description=MCP WPPConnect Server
After=network.target
[Service]
Type=simple
User=mcp-wppconnect
WorkingDirectory=/home/mcp-wppconnect/mcp-wppconnect-server
ExecStart=/usr/bin/node /home/mcp-wppconnect/mcp-wppconnect-server/build/index.js
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
Environment=MAX_SESSIONS=10
Environment=QR_EXPIRY_MINUTES=5
[Install]
WantedBy=multi-user.target
```
```bash
# Recarregar systemd
sudo systemctl daemon-reload
# Habilitar e iniciar serviço
sudo systemctl enable mcp-wppconnect
sudo systemctl start mcp-wppconnect
# Verificar status
sudo systemctl status mcp-wppconnect
```
---
## 🐳 Deployment com Docker
### 1. Criar Dockerfile
```dockerfile
# Dockerfile
FROM node:18-alpine
# Criar diretório do app
WORKDIR /app
# Copiar arquivos de configuração
COPY package*.json ./
COPY tsconfig.json ./
# Instalar dependências
RUN npm ci --only=production
# Copiar código fonte
COPY src/ ./src/
# Build do projeto
RUN npm run build
# Criar usuário não-root
RUN addgroup -g 1001 -S nodejs
RUN adduser -S mcp-wppconnect -u 1001
# Mudar permissões
RUN chown -R mcp-wppconnect:nodejs /app
USER mcp-wppconnect
# Expor porta (se necessário)
EXPOSE 3000
# Comando para iniciar
CMD ["node", "build/index.js"]
```
### 2. Criar docker-compose.yml
```yaml
version: '3.8'
services:
mcp-wppconnect:
build: .
container_name: mcp-wppconnect-server
restart: unless-stopped
environment:
- NODE_ENV=production
- MAX_SESSIONS=10
- QR_EXPIRY_MINUTES=5
- TOKEN_STORAGE_PATH=/app/data/tokens
volumes:
- ./data:/app/data
networks:
- mcp-network
networks:
mcp-network:
driver: bridge
```
### 3. Construir e Executar
```bash
# Construir imagem
docker build -t mcp-wppconnect-server .
# Executar com docker-compose
docker-compose up -d
# Verificar logs
docker-compose logs -f
```
---
## 📊 Deployment com PM2 em Produção
### 1. Instalar PM2 Globalmente
```bash
npm install -g pm2
```
### 2. Criar Configuração Avançada
```javascript
// ecosystem.config.js
module.exports = {
apps: [{
name: "mcp-wppconnect-server",
script: "./build/index.js",
instances: 1,
exec_mode: "fork",
// Ambiente
env: {
NODE_ENV: "development",
DEBUG: "mcp-wppconnect:*",
MAX_SESSIONS: 10,
QR_EXPIRY_MINUTES: 5,
TOKEN_STORAGE_PATH: "~/.mcp-wppconnect/tokens"
},
env_production: {
NODE_ENV: "production",
MAX_SESSIONS: 20,
QR_EXPIRY_MINUTES: 10,
TOKEN_STORAGE_PATH: "/opt/mcp-wppconnect/tokens"
},
// Reinicialização automática
autorestart: true,
watch: false,
max_memory_restart: "1G",
// Logs
log_file: "./logs/combined.log",
out_file: "./logs/out.log",
error_file: "./logs/error.log",
log_date_format: "YYYY-MM-DD HH:mm:ss Z",
// Monitoramento
monitoring: false,
// Tempo de vida
min_uptime: "10s",
max_restarts: 5,
// Sinais
kill_timeout: 5000,
listen_timeout: 3000,
// PMX (monitoramento)
pmx: false
}]
};
```
### 3. Configurar Inicialização do Sistema
```bash
# Salvar configuração PM2
pm2 save
# Configurar startup do sistema
pm2 startup
# Seguir as instruções do comando acima
# Exemplo para Ubuntu:
sudo env PATH=$PATH:/usr/bin pm2 startup systemd -u mcp-wppconnect --hp /home/mcp-wppconnect
```
### 4. Comandos PM2 Úteis
```bash
# Iniciar aplicação
pm2 start ecosystem.config.js --env production
# Verificar status
pm2 status
# Ver logs
pm2 logs mcp-wppconnect-server
# Reiniciar
pm2 restart mcp-wppconnect-server
# Parar
pm2 stop mcp-wppconnect-server
# Recarregar configuração
pm2 reload ecosystem.config.js
```
---
## ⚙️ Configuração de Produção
### 1. Variáveis de Ambiente
```bash
# Criar arquivo .env
NODE_ENV=production
MAX_SESSIONS=20
QR_EXPIRY_MINUTES=10
TOKEN_STORAGE_PATH=/opt/mcp-wppconnect/tokens
DEBUG=mcp-wppconnect:error
```
### 2. Configuração de Segurança
```bash
# Criar diretórios com permissões adequadas
sudo mkdir -p /opt/mcp-wppconnect/tokens
sudo chown mcp-wppconnect:mcp-wppconnect /opt/mcp-wppconnect/tokens
sudo chmod 750 /opt/mcp-wppconnect/tokens
```
### 3. Firewall (UFW)
```bash
# Habilitar firewall
sudo ufw enable
# Permitir SSH
sudo ufw allow ssh
# Se necessário, permitir outras portas
# sudo ufw allow 3000/tcp
```
### 4. Fail2ban (Proteção contra força bruta)
```bash
# Instalar
sudo apt install fail2ban
# Configurar
sudo nano /etc/fail2ban/jail.local
```
---
## 📈 Monitoramento
### 1. Logs do Sistema
```bash
# Ver logs do serviço systemd
sudo journalctl -u mcp-wppconnect -f
# Ver logs do PM2
pm2 logs mcp-wppconnect-server --lines 100
```
### 2. Monitoramento de Recursos
```bash
# Uso de memória
pm2 monit
# Uso de CPU e memória
htop
# Espaço em disco
df -h
```
### 3. Health Check
Crie um script para verificar se o servidor está respondendo:
```bash
#!/bin/bash
# health-check.sh
if ! pm2 status | grep -q "online"; then
echo "Servidor fora do ar! Reiniciando..."
pm2 restart mcp-wppconnect-server
fi
```
---
## 💾 Backup e Recuperação
### 1. Backup de Tokens
```bash
#!/bin/bash
# backup-tokens.sh
BACKUP_DIR="/backup/mcp-wppconnect"
DATA_DIR="/opt/mcp-wppconnect/tokens"
# Criar backup
tar -czf "$BACKUP_DIR/tokens-$(date +%Y%m%d-%H%M%S).tar.gz" "$DATA_DIR"
# Remover backups antigos (manter últimos 7 dias)
find "$BACKUP_DIR" -name "tokens-*.tar.gz" -mtime +7 -delete
```
### 2. Backup Completo
```bash
#!/bin/bash
# backup-completo.sh
BACKUP_DIR="/backup/mcp-wppconnect"
APP_DIR="/opt/mcp-wppconnect-server"
# Parar serviço
pm2 stop mcp-wppconnect-server
# Criar backup completo
tar -czf "$BACKUP_DIR/complete-$(date +%Y%m%d-%H%M%S).tar.gz" "$APP_DIR"
# Iniciar serviço
pm2 start mcp-wppconnect-server
```
### 3. Agendamento com Cron
```bash
# Adicionar ao crontab
0 2 * * * /opt/mcp-wppconnect-server/scripts/backup-tokens.sh
0 3 * * 0 /opt/mcp-wppconnect-server/scripts/backup-completo.sh
```
---
## 🔧 Troubleshooting de Deployment
### Problema: Servidor não inicia
```bash
# Verificar logs
pm2 logs mcp-wppconnect-server --lines 50
# Verificar status do serviço
systemctl status mcp-wppconnect
# Verificar permissões
ls -la /opt/mcp-wppconnect-server/
```
### Problema: Erro de permissão
```bash
# Corrigir permissões
sudo chown -R mcp-wppconnect:mcp-wppconnect /opt/mcp-wppconnect-server
sudo chmod -R 755 /opt/mcp-wppconnect-server
```
### Problema: Porta já em uso
```bash
# Verificar processos usando a porta
sudo netstat -tulpn | grep :3000
# Matar processo
sudo kill -9 <PID>
```
### Problema: Alto uso de memória
```bash
# Verificar uso de memória
pm2 monit
# Reiniciar se necessário
pm2 restart mcp-wppconnect-server
```
### Problema: Sessões não persistem
```bash
# Verificar diretório de tokens
ls -la /opt/mcp-wppconnect/tokens/
# Verificar permissões
sudo chown mcp-wppconnect:mcp-wppconnect /opt/mcp-wppconnect/tokens
sudo chmod 750 /opt/mcp-wppconnect/tokens
```
---
## 📞 Suporte Pós-Deployment
### Verificações Diárias
1. Verificar se o serviço está rodando
2. Checar logs de erro
3. Monitorar uso de recursos
4. Verificar backups
### Manutenção Semanal
1. Atualizar dependências de segurança
2. Limpar logs antigos
3. Verificar espaço em disco
4. Testar restauração de backup
### Manutenção Mensal
1. Revisar logs de erro
2. Atualizar sistema operacional
3. Testar procedimentos de disaster recovery
4. Documentar qualquer mudança
---
## 🔗 Referências
- [PM2 Documentation](https://pm2.keymetrics.io/docs/usage/quick-start/)
- [Systemd Services](https://www.freedesktop.org/software/systemd/man/systemd.service.html)
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
- [Node.js Production Best Practices](https://nodejs.org/en/docs/guides/simple-profiling/)