Primeros pasos · Trazo Docs

Esta guía lleva de cero a un cambio publicado. Cada paso enlaza al documento que lo explica en detalle.

1. Lo que hace falta en el equipo

Docker con Compose v2 (Docker Desktop en Windows y macOS, o Docker Engine en Linux).
Git.
Node 24, solo para trabajar en la interfaz fuera de los contenedores (pruebas y análisis del frontend).
Unos 4 GB de memoria libres y los puertos 8088 y 8025 sin usar.

No hace falta instalar PHP, Composer ni MySQL: todo corre dentro de los contenedores.

2. Levantar Trazo

git clone https://github.com/Daniuh/trazo.git trazo
cd trazo
docker compose up -d

La primera vez tarda unos minutos: construye las imágenes, prepara la base y carga 600 incidentes de prueba con su historial. Cuando docker compose ps muestre los servicios como healthy, Trazo está en http://localhost:8088 y el buzón de correo de prueba (Mailpit) en http://localhost:8025.

En Windows conviene clonar cerca de la raíz del disco (por ejemplo C:\proyectos\trazo): algunas rutas del backend son largas y superan el límite de 260 caracteres.

3. Entrar

Todas las cuentas de prueba usan la contraseña Cometa.Demo.2026:

Rol	Correo
Super admin	`superadmin@trazo.test`
Administrador	`admin@trazo.test`
Supervisor	`supervisor@trazo.test`
Agente	`agente1@trazo.test`, `agente2@trazo.test`, `agente3@trazo.test`
Solicitante	`solicitante1@trazo.test`, `solicitante2@trazo.test`, `solicitante3@trazo.test`

La verificación en dos pasos está activa también en local: el primer ingreso deja posponerla y desde el segundo pide escanear el QR con una aplicación de autenticación. Qué puede hacer cada rol está en Roles.

4. Trabajar en el código

El comando del paso 2 levanta Trazo como lo verá quien lo use. Para cambiar código hay un modo desarrollo: monta la carpeta del equipo, recarga la interfaz al guardar y trae las herramientas de prueba.

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

Antes de tocar nada conviene leer cómo está organizado:

Arquitectura en capas: dominio, aplicación, infraestructura y HTTP, y qué va en cada una.
Backend y Frontend: módulos y dónde vive cada cosa.
Decisiones: por qué se hizo así, con las alternativas que se descartaron.

5. Probar

# API: pruebas, estilo (Pint) y análisis estático (Larastan nivel 8), con el modo desarrollo levantado
docker compose exec app composer check

# Interfaz: tipos, lint, estilos y pruebas unitarias
cd frontend && npm ci && npm run check

# De extremo a extremo en las cuatro vistas, con revisión de accesibilidad
npm run test:e2e

Qué cubre cada tipo de prueba y qué cobertura se exige está en la estrategia de pruebas.

6. Ramas, commits y publicación

Cada cambio va en su rama (feature/, fix/, docs/ o chore/) creada desde dev.
Los commits siguen Conventional Commits: tipo y ámbito en inglés, descripción en español. Un hook lo revisa antes de cada commit, junto con el estilo y la búsqueda de secretos.
La rama entra a dev aplastada en un solo commit; de ahí pasa a stage y a main. Nada se fusiona con el CI en rojo.

Todo el detalle en Flujo de trabajo con Git, Integración continua y Despliegue.

7. Si algo no arranca

docker compose logs init o docker compose logs app muestran el error.
Si el puerto 8088 está ocupado, se cambia con TRAZO_HTTP_PORT en un .env.
Los problemas más comunes y su solución están en Soporte.