Brief de Deployment para IA de Hosting¶

Este documento es el contexto maestro para la IA que administra el hosting y va a subir suno-local a un subdominio web. Léelo de principio a fin antes de hacer cualquier cambio.

⚠️ Regla absoluta — NO NEGOCIABLE¶

TODOS los cambios, modificaciones, configuraciones, archivos nuevos, fixes o ajustes que necesites hacer para adaptar este proyecto al hosting DEBEN hacerse sobre la ruta local del proyecto:

/Users/mac_mini2/Documents/AI MUSICA

Prohibido: - ❌ Clonar el repo a otra ubicación para modificar ahí. - ❌ Copiar archivos a una carpeta paralela del hosting y editarlos ahí. - ❌ Crear forks, duplicados o "versiones del hosting" del código.

Permitido / obligatorio: - ✅ Cualquier Dockerfile, nginx.conf, systemd unit, .env, supervisord.conf, CI/CD, ajuste de imports, etc. → escribirlo dentro de /Users/mac_mini2/Documents/AI MUSICA/deploy/ o donde corresponda dentro del repo. - ✅ Si descubres un bug en src/ → arreglarlo ahí. - ✅ Si necesitas un script de build, puente WSGI/ASGI, healthcheck → vivirá dentro del repo. - ✅ Después de cambios, ejecutar python scripts/smoke_test.py para validar que no rompiste nada.

Razón: el proyecto se desarrolla activamente sobre esa ruta local. Tener dos versiones del código causa pérdida de cambios entre sesiones.

1. Qué es este proyecto¶

suno-local — Plataforma soberana de generación musical end-to-end tipo Suno AI / Udio, construida desde cero. 167 archivos Python (~12 000 LOC), arquitectura completa (MVP + capa soberana ACE-Step/DiffRhythm/SongGen + 13 capas PhD avanzadas).

Estado actual: - ✅ Código completo, sintaxis verificada, 3 smoke tests pasando. - ✅ FastAPI + Celery + Gradio + CLI typer funcionando. - ❌ Modelos sin pesos entrenados → output actual = ruido sintético. - Para output musical real → opciones en sección 8.

2. Ruta del proyecto y estructura clave¶

/Users/mac_mini2/Documents/AI MUSICA/
├── README.md                          ← lee primero
├── MODEL_CARD.md / DATASHEET.md
├── LICENSE                            ← Apache-2.0
├── pyproject.toml / requirements.txt
├── setup_env.sh                       ← bootstrap Mac M4
├── scripts/
│   ├── provision_sovereign.sh         ← bootstrap Linux + CUDA (producción)
│   ├── smoke_test.py                  ← validación puro-Python (sin torch)
│   ├── smoke_torch.py                 ← 13 módulos torch forward-pass
│   ├── smoke_advanced.py              ← 10 capas PhD
│   ├── seed_synthetic_corpus.py       ← genera datasets demo
│   └── …
├── src/
│   ├── api/                           ← FastAPI app empresarial
│   │   ├── main.py                    ← entry point uvicorn
│   │   ├── worker.py                  ← Celery worker GPU
│   │   ├── router.py                  ← SmartRouter
│   │   └── registry.py                ← ModelSingleton
│   ├── cli/main.py                    ← CLI `suno`
│   ├── pipeline/song_generator.py     ← orquestador E2E
│   ├── ace/                           ← ACE-Step (Planner+DiT+VAE+DCW)
│   ├── songgen/                       ← Dual-Track interleaving
│   ├── codec/ lm/ lyrics/ melody/ svs/
│   ├── analysis/                      ← MIR (beat/key/chord/loudness/mood)
│   ├── theory/                        ← Engine de armonía + escalas
│   ├── mixing/advanced/               ← DSP pro (Apache, sin pedalboard)
│   ├── safety/                        ← Auth + rate limit + audit + …
│   ├── observability/                 ← Logging + Prometheus + tracing
│   ├── workspace/                     ← Version control de canciones
│   ├── ux/                            ← Prompt helper + visualizer + AB
│   ├── lyrics/advanced/               ← G2P 5 idiomas + quality
│   ├── producer/                      ← Arrangements + samples + tempo/key
│   └── …
├── ui/
│   ├── gradio_app.py                  ← UI básica
│   └── advanced_app.py                ← UI 6 tabs (RECOMENDADA)
├── docs/
│   ├── phd_capabilities.md
│   ├── sovereign_architecture.md
│   ├── api_reference.md
│   └── HOSTING_DEPLOYMENT_BRIEF.md    ← este archivo
├── configs/                           ← YAMLs por componente
├── data/                              ← corpus sintéticos + manifests
├── tokenizer/                         ← SentencePiece ya entrenado
├── checkpoints/                       ← VACÍO (no hay pesos entrenados)
└── deploy/                            ← ★ scaffolding deployment (ver abajo)

3. Stack tecnológico¶

Backend: Python 3.10+ (recomendado 3.11), FastAPI, Celery, Redis, uvicorn, gunicorn.
ML: PyTorch 2.x con torch/torchaudio (MPS en Mac, CUDA en Linux).
UI: Gradio 4.x (tabs avanzados con matplotlib).
DSP: NumPy/SciPy puros (Apache); opcional pedalboard (GPLv3, no para distribución comercial).
Audio I/O: soundfile, librosa.
NLP: SentencePiece, phonemizer, silabeador.
CLI: typer + rich.

4. Componentes que se exponen¶

Componente	Puerto	Función	Comando
FastAPI	8000	API REST + OpenAPI	`uvicorn src.api.main:app`
Gradio UI	7860	Web UI con 6 tabs	`python ui/advanced_app.py`
Celery worker	—	Procesa tareas GPU	`celery -A src.api.worker.app worker -P solo --concurrency=1`
Redis	6379	Broker + result backend	`docker run redis:7`
Prometheus	/metrics	Métricas (opcional)	montar middleware

5. Decisiones del hosting según capacidades¶

A) Hosting compartido típico (cPanel/Plesk sin Docker, sin worker)¶

⚠️ Limitado. Sólo viable si el provider soporta Python ASGI + WebSockets.
Funciona: API FastAPI sincrónica + UI estática.
NO funciona: Celery worker, Redis, generación pesada con torch (>5 GB instalado).
Recomendación: NO uses hosting compartido tradicional. Si es lo único disponible, despliega únicamente el panel estático MIR/análisis y deja generación deshabilitada vía variable de entorno SUNO_DISABLE_GENERATION=true.

B) VPS Linux (DigitalOcean / Hetzner / Linode / Contabo)¶

✅ Opción recomendada sin GPU.
Mínimo: 4 GB RAM, 2 vCPU, 40 GB SSD, Ubuntu 22.04 LTS.
Soporta Docker → usa deploy/docker-compose.yml.
Funciona: API, Celery, Redis, UI, análisis MIR completo, mezcla DSP, teoría musical, workspace.
NO produce audio musical generado (sin GPU + sin pesos), pero todas las herramientas de análisis/mezcla/teoría/UX SÍ.

C) VPS Linux + GPU NVIDIA (cloud-GPU: RunPod, Vast.ai, Lambda Cloud)¶

✅ Único modo con generación musical real posible.
Mínimo recomendado: 1× RTX 3090/4090 24 GB, 16 GB RAM, Ubuntu 22.04 + CUDA 11.8.
Ejecutar scripts/provision_sovereign.sh para bootstrap completo (instala CUDA wheels, flash-attn, Celery, Redis).

D) Plataforma serverless (Vercel/Cloud Run/Fly.io)¶

❌ No recomendado. El proyecto tiene state (Redis, workspace, models en VRAM). Serverless no encaja salvo que separes la UI estática.

6. Pasos de deployment (VPS Docker — flujo principal)¶

En el VPS, clonar/sincronizar el repo (opciones a, b o c):
a) Si el VPS y la máquina local están en la misma red → rsync -avz /Users/mac_mini2/Documents/AI\ MUSICA/ user@vps:/srv/suno-local/
b) Push a GitHub privado y git clone en el VPS.
c) scp -r tar comprimido.

⚠️ El directorio destino en el servidor (/srv/suno-local) es réplica espejo de /Users/mac_mini2/Documents/AI MUSICA. Cualquier cambio en producción debe rsync de vuelta o commit al repo central para mantener la ruta local actualizada. No edites archivos directamente en el VPS sin sincronizarlos de vuelta.

Configurar .env copiando deploy/.env.example y editándolo.

Levantar con docker-compose:

cd /srv/suno-local
cp deploy/.env.example deploy/.env
# editar deploy/.env con tu dominio + secret
docker compose -f deploy/docker-compose.yml up -d

Configurar nginx (host) con deploy/nginx.conf y SSL con Let's Encrypt:
```
sudo certbot --nginx -d musica.tudominio.com
```

Verificar:

curl https://musica.tudominio.com/health
curl https://musica.tudominio.com/api/v1/voices

(Opcional) Habilitar auth: setear SUNO_API_REQUIRE_AUTH=true y generar API keys con python -m src.cli.main (extender CLI con auth create-key si hace falta).

7. Variables de entorno (todas las que el proyecto consume)¶

Variable	Default	Descripción
`SUNO_CKPTS_DIR`	`checkpoints`	Directorio de pesos
`SUNO_EXPORT_DIR`	`out/api`	Donde se guardan los WAV
`SUNO_AUDIT_DIR`	`logs/audit`	Audit log JSONL
`CELERY_BROKER_URL`	`redis://localhost:6379/0`	Redis broker
`CELERY_RESULT_BACKEND`	`redis://localhost:6379/1`	Result backend
`REDIS_RATE_LIMIT_URL`	`redis://localhost:6379/2`	Rate limit store
`SUNO_API_REQUIRE_AUTH`	`false`	`true` para forzar API keys
`SUNO_MASTER_SECRET`	autogen	Secreto HMAC firma API keys
`OTEL_EXPORTER_OTLP_ENDPOINT`	—	Opcional OpenTelemetry
`ACE_VAE_CHECKPOINT`	—	Override VAE ckpt path
`PYTORCH_ENABLE_MPS_FALLBACK`	`1`	Necesario en macOS

8. Salida de audio real (limitación crítica)¶

El proyecto NO tiene pesos entrenados. Sin entrenar: - Análisis MIR ✅ funciona - Teoría musical ✅ funciona - Mezcla / mastering DSP ✅ funciona - Workspace + version control ✅ funciona - UI completa ✅ funciona - Generación de música ❌ produce ruido (codec/LM/SVS aleatorios)

Opciones para producir música real en producción (ordenadas por costo):

Modo "demo HuggingFace" (no implementado aún) — descargar pesos open-source pre-entrenados (MusicGen-small ~300 MB, Stable Audio Open ~1.3 GB) y usarlos como backbone. → Audio real inmediato. Tarea pendiente: integrar transformers.MusicgenForConditionalGeneration en src/instrumental/.
Entrenar modelos propios — 6-10 meses + $1.400-3.000 en cloud GPU.
Solo análisis/mezcla — deshabilitar generación y exponer únicamente las herramientas MIR + teoría + DSP. Setear SUNO_DISABLE_GENERATION=true y ocultar el tab "Generar" en la UI.

Recomendación inmediata para hosting: ir con opción 3 ("solo análisis") o opción 1 (HF demo) según presupuesto. Generación local sin GPU es muy lenta (~30 s por cada segundo de audio).

9. Scripts y comandos clave¶

# Setup en VPS Linux
./scripts/provision_sovereign.sh

# Smoke tests (validar antes y después de cambios)
python scripts/smoke_test.py
python scripts/smoke_torch.py        # requiere torch
python scripts/smoke_advanced.py     # capas PhD

# CLI unificado
python -m src.cli.main --help
python -m src.cli.main serve --port 8000
python -m src.cli.main ui --advanced
python -m src.cli.main analyze track <wav>

# API directa
uvicorn src.api.main:app --host 0.0.0.0 --port 8000

# Celery worker
celery -A src.api.worker.app worker -P solo --concurrency=1 --loglevel=info

10. Healthchecks expuestos¶

GET /health → {"status": "ok"}
GET /api/v1/voices → lista VAEs/LoRAs/routes
GET /openapi.json → schema OpenAPI 3.1

Recomendación: usar /health como liveness probe y /api/v1/voices como readiness probe (asegura que los singletons de modelo cargaron).

11. Logs y observabilidad¶

Logs en stdout (JSON estructurado) → recogibles por Loki / Vector / journald.
Audit log en logs/audit/audit_YYYY-MM-DD.jsonl (rotación diaria).
Prometheus metrics: montar Metrics.asgi_app() en /metrics.
OpenTelemetry: setear OTEL_EXPORTER_OTLP_ENDPOINT.

12. Si necesitas hacer un cambio¶

Edita el archivo dentro de /Users/mac_mini2/Documents/AI MUSICA/.
Si es código en src/ → corre python scripts/smoke_test.py para validar.
Si es config → reflejarlo en deploy/.env.example y este brief.
Sincroniza al VPS con rsync (no edites directamente en el VPS).
Reinicia los servicios afectados: docker compose restart.

13. Archivos en deploy/ que YA están listos¶

deploy/Dockerfile — imagen Python 3.11 con todas las deps.
deploy/docker-compose.yml — orquesta api + worker + redis + nginx.
deploy/.env.example — plantilla de variables.
deploy/nginx.conf — reverse proxy + WebSocket Gradio + límites.
deploy/supervisord.conf — para hosting que no usa Docker.
deploy/systemd/ — unit files alternativos (no Docker).

14. Contacto del proyecto¶

Ruta local de trabajo: /Users/mac_mini2/Documents/AI MUSICA
Idioma de trabajo: español (LATAM neutro).
Licencia código: Apache-2.0.
Dependencias GPL: pedalboard (sustituible por src/mixing/dsp_pure.py
src/mixing/advanced/ para distribución comercial sin GPL).

Resumen para arrancar en 5 minutos¶

# 1. En el VPS:
git clone <repo> /srv/suno-local
# o rsync desde la máquina local

cd /srv/suno-local
cp deploy/.env.example deploy/.env
$EDITOR deploy/.env                    # poner DOMAIN, SECRET, etc.

# 2. Levantar todo:
docker compose -f deploy/docker-compose.yml up -d --build

# 3. Configurar nginx + SSL (en el host):
sudo cp deploy/nginx.conf /etc/nginx/sites-available/suno-local
sudo ln -s /etc/nginx/sites-available/suno-local /etc/nginx/sites-enabled/
sudo certbot --nginx -d musica.tudominio.com
sudo systemctl reload nginx

# 4. Verificar:
curl https://musica.tudominio.com/health

Listo: el subdominio queda live con la API + UI Gradio. La generación producirá ruido hasta que entrenes pesos o integres el modo demo HuggingFace.