Trivy/docs/INSTALLATION.md

# Guía de Instalación - Trivy

## Requisitos Previos

### Software Requerido

| Software | Versión Mínima | Notas |
|----------|----------------|-------|
| Python | 3.11+ | Con pip |
| Node.js | 18+ | Con npm |
| PostgreSQL | 15+ | O Docker |
| Redis | 7+ | O Docker |
| Git | 2.0+ | Para clonar |

### API Keys

- **Anthropic Claude API** - Obtener en https://console.anthropic.com

## Opción 1: Instalación con Docker (Recomendado)

### 1. Clonar repositorio

```bash
git clone https://gitea.local/frank/Trivy.git
cd Trivy
```

### 2. Configurar variables de entorno

```bash
# Backend
cp backend/.env.example backend/.env

# Editar backend/.env:
DATABASE_URL=postgresql+asyncpg://trivy:trivy@db:5432/trivy
REDIS_URL=redis://redis:6379
ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE

# Frontend
cp frontend/.env.example frontend/.env

# Editar frontend/.env:
VITE_API_URL=http://localhost:8000
VITE_WS_URL=http://localhost:8000
```

### 3. Iniciar con Docker Compose

```bash
docker-compose up -d
```

Esto iniciará:
- PostgreSQL en puerto 5432
- Redis en puerto 6379
- Backend en puerto 8000
- Frontend en puerto 3000

### 4. Ejecutar migraciones

```bash
docker-compose exec backend alembic upgrade head
```

### 5. Crear datos iniciales

```bash
docker-compose exec backend python scripts/seed_data.py
```

### 6. Acceder

- Frontend: http://localhost:3000
- Admin: http://localhost:3000/admin (admin/admin123)
- API: http://localhost:8000/docs

---

## Opción 2: Instalación Manual

### 1. Clonar repositorio

```bash
git clone https://gitea.local/frank/Trivy.git
cd Trivy
```

### 2. Configurar PostgreSQL

```bash
# Crear usuario y base de datos
sudo -u postgres psql

CREATE USER trivy WITH PASSWORD 'trivy';
CREATE DATABASE trivy OWNER trivy;
GRANT ALL PRIVILEGES ON DATABASE trivy TO trivy;
\q
```

### 3. Configurar Redis

```bash
# Ubuntu/Debian
sudo apt install redis-server
sudo systemctl start redis
sudo systemctl enable redis

# Verificar
redis-cli ping
# Respuesta: PONG
```

### 4. Configurar Backend

```bash
cd backend

# Crear entorno virtual
python3 -m venv venv
source venv/bin/activate

# Instalar dependencias
pip install -r requirements.txt

# Configurar variables de entorno
cp .env.example .env
```

Editar `backend/.env`:

```env
# Base de datos
DATABASE_URL=postgresql+asyncpg://trivy:trivy@localhost:5432/trivy

# Redis
REDIS_URL=redis://localhost:6379

# Anthropic API
ANTHROPIC_API_KEY=sk-ant-api03-YOUR_KEY_HERE

# Configuración del juego
STEAL_PENALTY_MULTIPLIER=0.5
STEAL_TIME_MULTIPLIER=0.5
ROOM_TTL_HOURS=3

# CORS (separar con comas)
CORS_ORIGINS=http://localhost:3000,http://localhost:5173
```

### 5. Ejecutar migraciones

```bash
cd backend
source venv/bin/activate
alembic upgrade head
```

### 6. Crear usuario admin

```bash
python -c "
import asyncio
from app.models.base import get_async_session
from app.models.admin import Admin

async def create_admin():
    AsyncSession = get_async_session()
    async with AsyncSession() as db:
        admin = Admin(username='admin')
        admin.set_password('admin123')
        db.add(admin)
        await db.commit()
        print('Admin creado: admin/admin123')

asyncio.run(create_admin())
"
```

### 7. Crear categorías

```bash
python -c "
import asyncio
from app.models.base import get_async_session
from app.models.category import Category

categories = [
    ('Nintendo', '🍄', '#E60012'),
    ('Xbox', '🎮', '#107C10'),
    ('PlayStation', '🎯', '#003791'),
    ('Anime', '⛩️', '#FF6B9D'),
    ('Música', '🎵', '#1DB954'),
    ('Películas', '🎬', '#F5C518'),
    ('Libros', '📚', '#8B4513'),
    ('Historia', '🏛️', '#6B5B95'),
]

async def create_categories():
    AsyncSession = get_async_session()
    async with AsyncSession() as db:
        for name, icon, color in categories:
            cat = Category(name=name, icon=icon, color=color)
            db.add(cat)
        await db.commit()
        print(f'{len(categories)} categorías creadas')

asyncio.run(create_categories())
"
```

### 8. Crear preguntas (ejecutar script completo)

```bash
python scripts/seed_questions.py
```

### 9. Configurar Frontend

```bash
cd frontend

# Instalar dependencias
npm install

# Configurar variables de entorno
cp .env.example .env
```

Editar `frontend/.env`:

```env
VITE_API_URL=http://localhost:8000
VITE_WS_URL=http://localhost:8000
```

### 10. Iniciar servicios

**Terminal 1 - Backend:**
```bash
cd backend
source venv/bin/activate
uvicorn app.main:socket_app --host 0.0.0.0 --port 8000 --reload
```

**Terminal 2 - Frontend:**
```bash
cd frontend
npm run dev -- --host
```

### 11. Acceder

- Frontend: http://localhost:3000
- Admin: http://localhost:3000/admin
- API Docs: http://localhost:8000/docs

---

## Configuración para Red Local

Para permitir acceso desde otros dispositivos en la red:

### 1. Obtener IP local

```bash
ip addr show | grep "inet " | grep -v 127.0.0.1
# Ejemplo: 192.168.1.100
```

### 2. Actualizar configuración

**backend/.env:**
```env
CORS_ORIGINS=http://localhost:3000,http://192.168.1.100:3000
```

**frontend/.env:**
```env
VITE_API_URL=http://192.168.1.100:8000
VITE_WS_URL=http://192.168.1.100:8000
```

### 3. Iniciar con host 0.0.0.0

```bash
# Backend
uvicorn app.main:socket_app --host 0.0.0.0 --port 8000

# Frontend
npm run dev -- --host
```

### 4. Acceder desde otros dispositivos

- http://192.168.1.100:3000

---

## Producción

### Backend con Gunicorn

```bash
pip install gunicorn

gunicorn app.main:socket_app \
  -w 4 \
  -k uvicorn.workers.UvicornWorker \
  -b 0.0.0.0:8000 \
  --access-logfile - \
  --error-logfile -
```

### Frontend Build

```bash
cd frontend
npm run build

# Servir con cualquier servidor estático
# Ejemplo con serve:
npm install -g serve
serve -s dist -l 3000
```

### Nginx como Reverse Proxy

```nginx
# /etc/nginx/sites-available/trivy
server {
    listen 80;
    server_name trivy.example.com;

    # Frontend
    location / {
        root /var/www/trivy/frontend/dist;
        try_files $uri $uri/ /index.html;
    }

    # API
    location /api {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # WebSocket
    location /socket.io {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
    }
}
```

### Systemd Service

```ini
# /etc/systemd/system/trivy-backend.service
[Unit]
Description=Trivy Backend
After=network.target postgresql.service redis.service

[Service]
Type=simple
User=www-data
WorkingDirectory=/var/www/trivy/backend
Environment=PATH=/var/www/trivy/backend/venv/bin
ExecStart=/var/www/trivy/backend/venv/bin/gunicorn app.main:socket_app -w 4 -k uvicorn.workers.UvicornWorker -b 127.0.0.1:8000
Restart=always

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable trivy-backend
sudo systemctl start trivy-backend
```

---

## Solución de Problemas

### Error: "Could not connect to Redis"

```bash
# Verificar Redis
redis-cli ping

# Si no responde, iniciar Redis
sudo systemctl start redis
```

### Error: "Database connection failed"

```bash
# Verificar PostgreSQL
sudo systemctl status postgresql

# Verificar credenciales
psql -U trivy -d trivy -h localhost
```

### Error: "CORS blocked"

Verificar que la URL del frontend esté en `CORS_ORIGINS` del backend.

### WebSocket no conecta

1. Verificar que `VITE_WS_URL` use `http://` (no `ws://`)
2. Verificar que el backend use `socket_app` (no `app`)
3. Verificar firewall/puertos

### Preguntas no cargan

```bash
# Verificar preguntas en BD
cd backend
source venv/bin/activate
python -c "
import asyncio
from sqlalchemy import select
from app.models.base import get_async_session
from app.models.question import Question
from datetime import date

async def check():
    AsyncSession = get_async_session()
    async with AsyncSession() as db:
        result = await db.execute(
            select(Question).where(Question.date_active == date.today())
        )
        qs = result.scalars().all()
        print(f'Preguntas para hoy: {len(qs)}')

asyncio.run(check())
"
```

### Sonidos no funcionan

Los sonidos requieren archivos MP3 en `/public/sounds/{tema}/`. Si no existen, el sistema usa fallbacks generados por Web Audio API (tonos simples).

---

## Actualizaciones

```bash
cd Trivy
git pull origin main

# Backend
cd backend
source venv/bin/activate
pip install -r requirements.txt
alembic upgrade head

# Frontend
cd frontend
npm install
npm run build

# Reiniciar servicios
sudo systemctl restart trivy-backend
```