setup-local.org

Setup Local - Cohete

1 Requisitos

Requisito	Versión	Notas
Nix	2.x+	Con flakes habilitados
Docker	20.x+	Para MySQL
Docker Compose	2.x+	Incluido en Docker Desktop

2 Instalación Rápida

# 1. Clonar el repositorio
git clone https://github.com/pascualmg/cohete.git
cd cohete

# 2. Entrar al entorno Nix
nix develop

# 3. Instalar dependencias PHP
composer install

# 4. Configurar variables de entorno
cp .env.example .env
# Editar .env si es necesario

# 5. Levantar MySQL (docker)
make mysql

# 6. Ejecutar migraciones
make migrate

# 7. (Opcional) Cargar datos de prueba
make fixtures

# 8. Arrancar el servidor
make run

El servidor estará disponible en http://localhost:8000

3 Paso a Paso Detallado

3.1 1. Instalar Nix (si no lo tienes)

# En Linux/macOS
curl -L https://nixos.org/nix/install | sh

# Habilitar flakes (añadir a ~/.config/nix/nix.conf)
experimental-features = nix-command flakes

O usa el Makefile:

make nix-install

3.2 2. Entrar al entorno de desarrollo

cd /path/to/cohete
nix develop

Esto te da:

• PHP 8.3 con extensiones necesarias
• Composer
• PHPUnit, PHPStan, Psalm
• php-cs-fixer
• Xdebug configurado

Si usas direnv, el entorno se carga automáticamente al entrar al directorio.

3.3 3. Instalar dependencias

composer install

3.4 4. Configurar variables de entorno

Copiar el ejemplo y editar:

cp .env.example .env

Contenido típico de .env:

APP_ENV=dev

# Servidor HTTP
HTTP_SERVER_HOST=0.0.0.0
HTTP_SERVER_PORT=8000

# Rutas
ROUTES_PATH=/home/tu-usuario/src/cohete/src/ddd/Infrastructure/HttpServer/Router/routes.json

# MySQL
MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASSWORD=root
MYSQL_DATABASE=cohete

IMPORTANTE: ROUTES_PATH debe ser una ruta absoluta.

3.5 5. Levantar MySQL

El proyecto usa docker-compose para MySQL:

make mysql

Esto ejecuta:

docker-compose up -d mysql

Verificar que está corriendo:

docker ps | grep mysql

Conectar manualmente (para debug):

docker exec -it cohete-mysql mysql -uroot -proot cohete

3.6 6. Ejecutar migraciones

make migrate

Esto crea las tablas necesarias (post, etc.).

Otros comandos de Phinx:

# Ver estado de migraciones
nix develop --command bash -c 'vendor/bin/phinx status'

# Rollback última migración
nix develop --command bash -c 'vendor/bin/phinx rollback'

# Rollback todas
nix develop --command bash -c 'vendor/bin/phinx rollback -t 0'

3.7 7. Cargar datos de prueba (opcional)

make fixtures

Esto ejecuta los seeders de Phinx que insertan posts de ejemplo.

3.8 8. Arrancar el servidor

make run

Salida esperada:

Server running at http://0.0.0.0:8000

El servidor es non-blocking - un solo proceso maneja múltiples conexiones concurrentes.

4 Verificar la Instalación

4.1 Health check

curl http://localhost:8000/health

Respuesta esperada:

{"status": "ok"}

4.2 Listar posts

curl http://localhost:8000/post | jq

4.3 Abrir el portfolio

Abre en el navegador:

http://localhost:8000/html/pascualmgPorfolio.html

5 Ejecutar Tests

5.1 Tests unitarios (PHPUnit)

nix develop --command bash -c 'vendor/bin/phpunit'

5.2 Tests BDD (Behat)

Requisito: El servidor debe estar corriendo en otra terminal.

# Terminal 1: Servidor
make run

# Terminal 2: Tests
nix develop --command bash -c 'vendor/bin/behat'

Ejecutar solo una feature:

nix develop --command bash -c 'vendor/bin/behat features/ImportOrgPost.feature'

5.3 Coverage

nix develop --command bash -c 'vendor/bin/phpunit --coverage-html coverage'
# Abrir coverage/index.html en el navegador

6 Comandos del Makefile

Comando	Descripción
make run	Arranca el servidor HTTP
make mysql	Levanta MySQL con docker-compose
make migrate	Ejecuta migraciones de BD
make fixtures	Carga datos de prueba
make behat	Ejecuta tests BDD
make fix	Ejecuta php-cs-fixer
make test_ab	Benchmark con Apache Bench
make nix-install	Instala Nix

7 Troubleshooting

7.1 “Connection refused” al conectar a MySQL

MySQL no está corriendo:

make mysql
docker ps  # Verificar que está up

7.2 “Table doesn’t exist”

Migraciones no ejecutadas:

make migrate

7.3 “Address already in use” al arrancar servidor

Puerto 8000 ocupado:

# Ver qué proceso usa el puerto
lsof -i :8000

# Matar el proceso
kill -9 <PID>

# O cambiar el puerto en .env
HTTP_SERVER_PORT=8001

7.4 Tests de Behat fallan con “Connection refused”

El servidor no está corriendo. Arrancarlo en otra terminal:

make run

7.5 “ROUTES_PATH” error

La variable debe ser una ruta absoluta. Verificar en .env:

ROUTES_PATH=/ruta/absoluta/a/routes.json

7.6 Xdebug no funciona

Verificar que está habilitado:

php -m | grep xdebug

El entorno Nix ya incluye Xdebug configurado.

8 Estructura de Archivos de Configuración

cohete/
├── .env                  # Variables de entorno (no commitear)
├── .env.example          # Plantilla de variables
├── .envrc                # Para direnv (carga nix develop)
├── composer.json         # Dependencias PHP
├── docker-compose.yml    # MySQL y RabbitMQ
├── flake.nix            # Configuración Nix
├── Makefile             # Comandos útiles
├── phpunit.xml          # Configuración PHPUnit
├── behat.yml            # Configuración Behat
└── phinx.php            # Configuración migraciones

9 Desarrollo con IDE

9.1 PhpStorm / IntelliJ

1. Abrir el proyecto
2. Configurar PHP interpreter desde Nix:
   • Settings → PHP → CLI Interpreter
   • Añadir: nix develop --command php
3. Configurar Xdebug:
   • Ya viene configurado en el entorno Nix
   • Puerto por defecto: 9003

9.2 Emacs (con php-mode)

El proyecto funciona directamente. Para LSP:

;; Usar intelephense o phpactor
(use-package lsp-mode
  :hook (php-mode . lsp))

10 Siguiente Paso

Una vez que el entorno está funcionando, puedes:

1. Explorar la API: curl http://localhost:8000/post
2. Ver el portfolio: http://localhost:8000/html/pascualmgPorfolio.html
3. Importar un post: Ver docs/feature-import-org-posts.org
4. Leer el código: Empezar por src/bootstrap.php y Kernel.php