Dev Hub

Cómo levantar el proyecto

De cero a todo funcionando en local. Sigue los pasos en orden la primera vez; después te bastará con make dev.

1. Prerequisitos

Antes de tocar código, necesitas instalar esto. Sólo hay que hacerlo una vez.

Coloca estos comandos en orden. Entre uno y otro no hagas nada más.

Ir a la raíz del proyecto.

cd /Users/asiergonzalezgomez/Development/amaren-ventures-apps/blank-phone

Copiar el fichero de variables de entorno y editarlo con tus claves.

cp .env.example .env

Instalar dependencias de Node y Python.

make install

Levantar postgres, redis, traefik y el resto de infra.

make docker-up

Crear los schemas de base de datos de los 8 servicios.

make migrate

Cargar datos de prueba (familias, dispositivos, políticas).

make seed

Un solo comando arranca todo en paralelo vía Turborepo.

make dev

Cuando veas todos los ready en verde, abre http://localhost:3001 y estarás aquí mismo.

Si solo quieres tocar un servicio, arráncalo suelto. Útil cuando estás depurando y no quieres el ruido de los demás.

Servicio	Comando	URL de salud
parent-dashboard	pnpm --filter parent-dashboard dev	http://localhost:5173
public-website	pnpm --filter public-website dev	http://localhost:3000
intranet	pnpm --filter intranet dev	http://localhost:3001
auth-service	cd backend/auth-service && uvicorn app.main:app --reload --port 8000	http://localhost:8000/healthz
device-service	cd backend/device-service && uvicorn app.main:app --reload --port 8001	http://localhost:8001/healthz
policy-service	cd backend/policy-service && uvicorn app.main:app --reload --port 8002	http://localhost:8002/healthz
family-service	cd backend/family-service && uvicorn app.main:app --reload --port 8003	http://localhost:8003/healthz
usage-service	cd backend/usage-service && uvicorn app.main:app --reload --port 8004	http://localhost:8004/healthz
billing-service	cd backend/billing-service && uvicorn app.main:app --reload --port 8005	http://localhost:8005/healthz
notification-service	cd backend/notification-service && uvicorn app.main:app --reload --port 8006	http://localhost:8006/healthz
content-filter-service	cd backend/content-filter-service && uvicorn app.main:app --reload --port 8007	http://localhost:8007/healthz
agent-api	cd agents && uvicorn api.main:app --reload --port 8001	http://localhost:8001/healthz

El launcher es el único trozo que no arranca con make dev. Requiere Android Studio y un Moto G conectado por USB con depuración activada.

Abrir el proyecto.

open -a 'Android Studio' android/launcher

Compilar APK de debug desde terminal.

cd android/launcher && ./gradlew :app:assembleDebug

Instalar en el teléfono conectado.

adb install -r android/launcher/app/build/outputs/apk/debug/app-debug.apk

Hacer a BLANK el device owner (solo una vez, y con cuenta Google recién borrada).

adb shell dpm set-device-owner com.blankphone.launcher/.admin.BlankDeviceAdminReceiver

Cuando termines, cierra las terminales con Ctrl+C y baja la infraestructura.

make docker-down

El puerto 3000 (o cualquier otro) está ocupado.
Busca el proceso con lsof -i :3000 y mátalo con kill -9 <PID>. Si es algo que ya tenías arrancado, ciérralo desde donde lo lanzaste.
Docker Desktop no arranca o se queda colgado.
Cierra Docker Desktop del todo, reinicia el Mac y vuelve a abrirlo. Si persiste, en Docker Desktop > Troubleshoot elige "Reset to factory defaults".
make migrate falla con "relation does not exist".
Probablemente la base de datos aún no está lista. Asegúrate de que docker-up terminó y espera unos segundos. Si sigue, borra el volumen con make docker-reset y vuelve a empezar.
Error de certificado al llamar al gateway desde el teléfono.
En desarrollo usamos certificados de Traefik autofirmados. En el teléfono hay que añadirlos como "trusted" o usar el build de debug que los ignora.
pnpm install falla con errores de permisos.
Borra node_modules y pnpm-lock.yaml, comprueba que usas Node 20 con node -v, y vuelve a correr pnpm install. Evita sudo.