seguidorDeLotes/SETUP.md

Guía de Configuración - Seguidor de Lotes

Arquitectura

┌─────────────┐     ┌──────────┐     ┌────────────────┐
│   Traefik   │────▶│ Nuxt App │────▶│   Authentik    │
│ (Reverse    │     │ (Puerto  │     │   (OAuth/OIDC) │
│  Proxy)     │     │  3000)   │     │                │
└─────────────┘     └──────────┘     └────────────────┘
       │                   │
       └───────────────────┘
        Red Docker "principal"

1. Configurar Authentik

1.1 Crear Aplicación OAuth en Authentik

1. Accede a tu panel de Authentik: https://auth.tudominio.com
2. Ve a Applications → Applications → Create
3. Configura:
   • Name: Seguidor de Lotes
   • Slug: seguidor-lotes
   • Provider: (Crear nuevo provider OAuth2/OIDC)

1.2 Crear Provider OAuth2/OIDC

1. Applications → Providers → Create

2. Selecciona OAuth2/OpenID Provider

3. Configura:

   • Name: Seguidor de Lotes OAuth
   • Authorization flow: default-authentication-flow
   • Client type: Confidential
   • Client ID: (se genera automáticamente, guárdalo)
   • Client Secret: (se genera automáticamente, guárdalo)
   • Redirect URIs: https://app.tudominio.com/api/auth/authentik
   • Scopes: openid, profile, email
   • Subject mode: Based on the User's UUID
   • Include claims in id_token: ✅ Activado

4. Guarda el provider y asócialo a la aplicación creada anteriormente

1.3 Configurar Grupos (Opcional)

Si quieres usar permisos basados en grupos:

1. Directory → Groups → Create
2. Crea grupos como: admin, users, etc.
3. En el Provider OAuth, asegúrate de incluir el scope groups

2. Configurar Variables de Entorno

2.1 Copiar archivo de ejemplo

cp .env.example .env

2.2 Editar variables en .env

# Dominio de tu aplicación
APP_DOMAIN=app.tudominio.com

# Datos de Authentik OAuth (desde el paso 1.2)
NUXT_OAUTH_AUTHENTIK_CLIENT_ID=tu-client-id-aqui
NUXT_OAUTH_AUTHENTIK_CLIENT_SECRET=tu-client-secret-aqui
NUXT_OAUTH_AUTHENTIK_SERVER_URL=https://auth.tudominio.com
NUXT_OAUTH_AUTHENTIK_REDIRECT_URL=https://app.tudominio.com/api/auth/authentik
NUXT_OAUTH_AUTHENTIK_SERVER_URL_INTERNAL=http://nombre-servicio-authentik:9000

# URL pública de la app
NUXT_PUBLIC_APP_URL=https://app.tudominio.com

# Secret para sesiones (generar con: openssl rand -base64 32)
NUXT_SESSION_PASSWORD=$(openssl rand -base64 32)

2.3 Generar Session Secret

openssl rand -base64 32

Copia el resultado y pégalo en NUXT_SESSION_PASSWORD

3. Configurar Red Docker

Asegúrate de que la red principal exista:

# Verificar si existe
docker network ls | grep principal

# Si no existe, crearla
docker network create principal

4. Verificar Traefik

Tu configuración de Traefik debe tener:

# traefik.yml o docker-compose.yml de Traefik
providers:
  docker:
    network: principal
    exposedByDefault: false

5. Crear Iconos PWA

Crea los iconos en nuxt4-app/public/:

# Necesitas un icono base de 512x512 llamado icon.png
# Puedes generarlos con imagemagick:

cd nuxt4-app/public

# Si tienes un SVG o PNG grande
convert icon.png -resize 192x192 pwa-192x192.png
convert icon.png -resize 512x512 pwa-512x512.png

# O usa una herramienta online: https://realfavicongenerator.net/

6. Desplegar

6.1 Build y Start

# Build y levantar el contenedor
docker-compose up -d --build

6.2 Ver logs

docker-compose logs -f seguidor-lotes

6.3 Verificar estado

docker-compose ps

7. Verificar Funcionamiento

7.1 Acceso Web

1. Accede a https://app.tudominio.com
2. Deberías ver la página de inicio
3. Click en "Iniciar Sesión"
4. Serás redirigido a Authentik
5. Tras autenticar, vuelves a la app con sesión iniciada

7.2 Verificar APIs

# API Protegida (requiere auth - debería retornar 401 sin sesión)
curl https://app.tudominio.com/api/protected

7.3 Verificar PWA

1. Abre Chrome DevTools (F12)
2. Ve a la pestaña Application → Service Workers
3. Deberías ver el service worker registrado
4. Prueba el modo offline:
   • Activa "Offline" en la pestaña Network
   • Navega por la aplicación
   • Las páginas cacheadas funcionarán sin conexión

8. Rutas y Endpoints

Páginas

• / - Página de inicio (pública)
• /login - Página de login
• /dashboard - Dashboard (requiere autenticación)
• /profile - Perfil (requiere autenticación)

API Endpoints

• GET /api/protected - Endpoint protegido (requiere autenticación)

Auth Endpoints

• GET /api/auth/authentik - Inicia OAuth flow con Authentik y maneja callback
• GET /api/auth/logout - Cierra sesión

9. Desarrollo Local

Si quieres desarrollar localmente sin Docker:

cd nuxt4-app

# Copiar variables de entorno
cp .env.example .env

# Editar .env con tus valores locales
# Usar http://localhost:3000 en lugar de https

# Instalar dependencias
npm install

# Ejecutar en modo desarrollo
npm run dev

Nota: Para desarrollo local, necesitas:

• Configurar Authentik con redirect URI: http://localhost:3000/api/auth/authentik
• O usar túnel como ngrok para https
• Usar la URL pública de Authentik para NUXT_OAUTH_AUTHENTIK_SERVER_URL
• No necesitas NUXT_OAUTH_AUTHENTIK_SERVER_URL_INTERNAL en desarrollo local

10. Troubleshooting

Error: "Invalid redirect_uri"

• Verifica que la URI en Authentik coincida exactamente con NUXT_OAUTH_AUTHENTIK_REDIRECT_URL
• El protocolo debe ser https:// en producción

Error: "Invalid client_id or client_secret"

• Verifica los valores copiados de Authentik
• Asegúrate de que el Provider esté activado

PWA no se registra

• Verifica que estés usando HTTPS (obligatorio para service workers)
• Abre DevTools → Application → Service Workers
• Verifica errores en la consola

Sesión no persiste

• Verifica que NUXT_SESSION_PASSWORD tenga al menos 32 caracteres
• Verifica las cookies en DevTools → Application → Cookies

Container no inicia

# Ver logs detallados
docker-compose logs seguidor-lotes

# Ver todas las variables de entorno
docker-compose exec seguidor-lotes env | grep NUXT

11. Seguridad

Recomendaciones

1. HTTPS Obligatorio: Nunca uses HTTP en producción
2. Secrets Seguros: Usa openssl rand -base64 32 para generar secrets
3. Variables de Entorno: Nunca commits el archivo .env
4. Rate Limiting: Considera añadir rate limiting en Traefik
5. CORS: Configura CORS apropiadamente si usas subdominios

Headers de Seguridad (Traefik)

Añade a los labels de Docker Compose:

- "traefik.http.middlewares.security-headers.headers.stsSeconds=31536000"
- "traefik.http.middlewares.security-headers.headers.stsIncludeSubdomains=true"
- "traefik.http.middlewares.security-headers.headers.stsPreload=true"
- "traefik.http.middlewares.security-headers.headers.contentTypeNosniff=true"
- "traefik.http.middlewares.security-headers.headers.browserXssFilter=true"
- "traefik.http.routers.seguidor-lotes.middlewares=security-headers"

12. Personalización

Cambiar nombre de la app

1. Edita nuxt4-app/nuxt.config.ts → sección pwa.manifest
2. Cambia name y short_name

Añadir más rutas protegidas

Crea una nueva página con:

<script setup>
definePageMeta({
  middleware: 'auth'
})
</script>

Añadir más endpoints protegidos

Crea un archivo en server/api/ con:

export default defineEventHandler(async (event) => {
  const session = await requireUserSession(event)
  // Tu lógica aquí
})

Soporte

Para más información:

• Nuxt Auth Utils
• Vite PWA
• Authentik Docs