whatsapp/DOCKER_DEV_GUIDE.md

Guía de Uso - Docker Compose Development

🚀 Inicio Rápido

Levantar entorno de desarrollo

docker-compose -f docker-compose.dev.yml up -d

Ver logs en tiempo real

docker-compose -f docker-compose.dev.yml logs -f

Detener entorno

docker-compose -f docker-compose.dev.yml down

Reconstruir contenedores

docker-compose -f docker-compose.dev.yml build --no-cache
docker-compose -f docker-compose.dev.yml up -d

---

🛠️ Herramientas Disponibles

Servicio	URL	Descripción
Aplicación	http://localhost:8080	WhatsApp Bot principal
XDebug	Puerto 9003	Debugger para IDE (VSCode, PHPStorm)
Redis Commander	http://localhost:8082	Interface web para Redis
MailHog	http://localhost:8025	Captura de emails de prueba
Adminer	http://localhost:8083	Gestor de base de datos

---

🔧 Características de Desarrollo

✅ Hot Reload Activado

Los cambios en archivos PHP/JS/CSS se reflejan inmediatamente sin reiniciar:

• ✅ Volumen mount: ./:/var/www/html
• ✅ OPcache desactivado
• ✅ No requiere rebuild

🐛 Debugging con XDebug

VSCode Configuration (.vscode/launch.json)

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Listen for XDebug",
      "type": "php",
      "request": "launch",
      "port": 9003,
      "pathMappings": {
        "/var/www/html": "${workspaceFolder}"
      }
    }
  ]
}

PHPStorm Configuration

1. Settings → PHP → Debug → XDebug
2. Port: 9003
3. Path mappings: /var/www/html → /Users/lizandro/Documents/GitHub/whatsapp

📊 Logs en Tiempo Real

# Ver logs de todos los servicios
docker-compose -f docker-compose.dev.yml logs -f

# Ver logs de un servicio específico
docker-compose -f docker-compose.dev.yml logs -f app

# Ver logs PHP-FPM
docker-compose -f docker-compose.dev.yml exec app tail -f /var/www/html/logs/php-fpm-error.log

# Ver logs de XDebug
docker-compose -f docker-compose.dev.yml exec app tail -f /var/www/html/logs/xdebug.log

---

📧 Testing de Emails con MailHog

MailHog captura todos los emails enviados desde la aplicación:

1. Configura PHP para usar MailHog:

ini_set('SMTP', 'mailhog');
ini_set('smtp_port', 1025);

2. Abre http://localhost:8025 para ver emails capturados

---

🔍 Inspeccionar Redis

Opción 1: Redis Commander (Web UI)

• URL: http://localhost:8082
• Ver claves, valores, TTL
• Ejecutar comandos Redis

Opción 2: Redis CLI

docker-compose -f docker-compose.dev.yml exec redis redis-cli

# Comandos útiles:
KEYS *              # Ver todas las claves
GET clave           # Ver valor de una clave
TTL clave           # Ver tiempo de vida
MONITOR             # Ver comandos en tiempo real

---

🗄️ Acceso a Base de Datos

Adminer (http://localhost:8083)

• Server: Tu DB_HOST del .env
• Username: Tu DB_USER del .env
• Password: Tu DB_PASS del .env
• Database: Tu DB_NAME del .env

MySQL CLI desde contenedor

docker-compose -f docker-compose.dev.yml exec app mysql -h ${DB_HOST} -u ${DB_USER} -p${DB_PASS} ${DB_NAME}

---

🧪 Comandos Útiles

Ejecutar comandos en el contenedor

# Bash interactivo
docker-compose -f docker-compose.dev.yml exec app bash

# PHP CLI
docker-compose -f docker-compose.dev.yml exec app php -v

# Composer
docker-compose -f docker-compose.dev.yml exec app composer install

# Verificar configuración PHP
docker-compose -f docker-compose.dev.yml exec app php -i | grep xdebug

Reiniciar servicios

# Reiniciar un servicio específico
docker-compose -f docker-compose.dev.yml restart app

# Reiniciar todos
docker-compose -f docker-compose.dev.yml restart

Limpiar todo (cuidado!)

# Detener y eliminar contenedores + volúmenes
docker-compose -f docker-compose.dev.yml down -v

# Limpiar imágenes no utilizadas
docker system prune -a

---

🚨 Troubleshooting

Problema: Cambios no se reflejan

# 1. Verificar que el volumen esté montado
docker-compose -f docker-compose.dev.yml exec app ls -la /var/www/html

# 2. Verificar que OPcache esté desactivado
docker-compose -f docker-compose.dev.yml exec app php -i | grep opcache.enable

# 3. Limpiar caché del navegador (Cmd+Shift+R)

Problema: XDebug no funciona

# Verificar que XDebug esté instalado
docker-compose -f docker-compose.dev.yml exec app php -m | grep xdebug

# Ver configuración de XDebug
docker-compose -f docker-compose.dev.yml exec app php -i | grep xdebug

# Ver logs de XDebug
docker-compose -f docker-compose.dev.yml exec app tail -f /var/www/html/logs/xdebug.log

Problema: Redis no conecta

# Verificar que Redis esté corriendo
docker-compose -f docker-compose.dev.yml ps

# Test de conexión
docker-compose -f docker-compose.dev.yml exec app php -r "try { \$r = new Redis(); \$r->connect('redis', 6379); echo 'OK'; } catch (Exception \$e) { echo \$e->getMessage(); }"

---

⚠️ Diferencias con Producción

Característica	Desarrollo	Producción
OPcache	❌ Desactivado	✅ Activado
Error Display	✅ Activado	❌ Desactivado
XDebug	✅ Activado	❌ Desactivado
Log Level	DEBUG	INFO/WARNING
Workers	1	2+
Rate Limiting	❌ Desactivado	✅ Activado

---

🔄 Migrar de Dev a Producción

# 1. Detener entorno de desarrollo
docker-compose -f docker-compose.dev.yml down

# 2. Levantar entorno de producción
docker-compose up -d

# 3. Verificar
docker-compose ps

---

📝 Notas

• No commitear docker-compose.dev.yml en producción
• Usar .env para configuración sensible
• Los volúmenes de desarrollo son locales (no se comparten)
• MailHog solo atrapa emails locales, no los envía realmente