Variables de entorno

Dónde están los ajustes

Crea el archivo de cada aplicación a partir del .env.example que tiene al lado, que documenta cada variable: cp .env.example .env. Los ejemplos funcionan tal cual para una ejecución local, salvo las dos direcciones de la API del panel, que rellenas para dejar los datos de ejemplo.

Dónde están los ajustes

Un archivo, .env en la carpeta del panel, que se lee cuando se construye el panel. Todos sus valores son públicos, así que nunca contiene un secreto. Omítelo para usar los datos de ejemplo; créalo a partir de .env.example cuando conectes una API: cp .env.example .env.

Dónde están los ajustes

Un archivo, .env en la carpeta de la API, que lee la API con yarn dev, y un contenedor cuando se lo pasas con --env-file .env. Contiene secretos: nunca lo subas al repositorio. Créalo a partir de .env.example, que documenta cada variable y funciona tal cual para una ejecución local: cp .env.example .env.

Lo esencial de la API

La API comprueba JWT_SECRET y, en producción, CORS_ORIGIN antes de iniciar. Si falta uno o no se puede usar, se detiene con una línea que dice qué corregir. Las variables ya definidas en el entorno tienen prioridad sobre el archivo.

Genera tu propio JWT_SECRET con:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

Cualquier credencial de almacenamiento o de IA de abajo que aún tenga exactamente su valor de .env.example cuenta como no configurada, así que la función a la que pertenece indica que está desactivada en lugar de fallar en su primera llamada.

Usa MySQL en lugar de SQLite

Crea una base de datos vacía y luego configura el controlador y la conexión en back-end/.env:

DB_TYPE=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USERNAME=your-mysql-username
DB_PASSWORD=your-mysql-password
DB_DATABASE=your-database-name

Después ejecuta yarn seed para los datos de demostración, o yarn db:sync para las tablas sin datos. La API en marcha solo crea y actualiza las tablas por sí misma cuando NODE_ENV=development, así que con NODE_ENV=production uno de esos comandos se ejecuta antes del primer inicio (yarn db:sync:prod o yarn seed:prod después de yarn build), y yarn db:sync:prod de nuevo después de una actualización que cambie el esquema. Conserva tus datos.

La plantilla incluye su migración solo para SQLite. back-end/src/database/migrations/mysql/README.md tiene el único comando que genera la de MySQL, si también quieres las migraciones de arranque de la API en MySQL.

Panel

Cada valor NEXT_PUBLIC_* se compila en el JavaScript que carga el navegador, y cualquiera que abra la página puede leerlo. Nunca pongas un secreto en este archivo, y reinicia o vuelve a construir después de cambiar uno.

Aquí no va ninguna clave de proveedor de IA. Las claves solo van en el .env de la API.

Opciones de Docker Compose

No hay que configurar nada para una ejecución local. Para cambiar algo, ponlo en un archivo .env junto a docker-compose.yml y vuelve a ejecutar docker compose up --build: el panel compila estos valores.

El contenedor de la API también lee back-end/.env cuando existe, así que las claves de almacenamiento, IA y MCP se configuran en un solo sitio tanto para yarn dev como para Docker. El archivo compose tiene prioridad en los valores que cambian dentro de un contenedor: NODE_ENV=production, el puerto, SQLite en /data/database.sqlite, DEMO_MODE=false, CORS_ORIGIN y FRONTEND_URL. Sin un JWT_SECRET propio, la API genera uno y lo guarda en el volumen de datos. Los datos están en el volumen kinora-data.

La imagen Docker de la API

La imagen arranca en producción con SQLite en /data/database.sqlite, puerto 8000, con DEMO_MODE=false y SEED_DEMO_DATA=false, y permite llamadas del navegador desde http://localhost:3030 (CORS_ORIGIN y FRONTEND_URL). Cambia cualquiera con -e en docker run, o pasa tu archivo con --env-file .env.

• En un volumen nuevo, el contenedor crea las tablas, y solo añade los datos de demostración con SEED_DEMO_DATA=true. Una base de datos existente no se toca.
• Sin un JWT_SECRET, o con el del ejemplo, genera un secreto y lo guarda en /data/.jwt-secret, así que los inicios de sesión sobreviven a un reinicio.
• Con DB_TYPE=mysql no crea nada: ejecuta tú mismo una vez node dist/database/sync-schema.js o node dist/database/seeder.js en el contenedor.

Almacenamiento multimedia

Las fotos de perfil, las fotos de progreso, las portadas de grupos y los adjuntos de mensajes se suben a un bucket de Cloudflare R2, o a cualquiera compatible con S3. Configura las cinco variables en back-end/.env y dale al panel el host público del bucket mediante NEXT_PUBLIC_MEDIA_HOSTNAME (con Docker Compose, MEDIA_HOSTNAME).

R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME=your-bucket-name
R2_PUBLIC_URL=https://your-public-url.r2.dev

Sin un bucket, todo lo que escribe la carga de datos es una ruta /assets/images/… que el panel sirve desde su propia carpeta public/assets, así que cada pantalla se muestra sin haber subido nada. Solo deja de funcionar la subida de archivos nuevos: una subida responde 400 hasta que el bucket esté configurado. Mantén public/assets en el panel mientras alguna fila siga apuntando a ella.

Un archivo ocupa como máximo 150 MB. El cargador del panel envía los archivos grandes en partes de hasta 16 MB mediante POST /api/helpers/upload-chunk, por sí solo.

Correo electrónico

La plantilla no incluye transporte de correo, así que nunca se envía ningún mensaje por correo. El "resend verification email" de la pantalla de miembros responde sin enviar nada, y las páginas de contraseña olvidada y de restablecer contraseña son solo las pantallas: no se envía ningún restablecimiento y la API no tiene ninguna ruta detrás de ellas. Conecta tu propio proveedor de correo, y añade las rutas de restablecimiento, antes de publicar si tus miembros necesitan alguna de las dos cosas.

• "Forgot password" no envía nada

Asistente de IA

Servidor MCP

Modo demostración

Pasar a producción

Antes de desplegar en cualquier sitio público:

1. Configura NODE_ENV=production y un JWT_SECRET largo y aleatorio propio en back-end/.env.
2. Configura CORS_ORIGIN con la dirección de tu panel, y FRONTEND_URL con la misma dirección.
3. Mantén DEMO_MODE=false en la API y NEXT_PUBLIC_DEMO_MODE=false en el panel.
4. En una base de datos vacía, ejecuta yarn build, después yarn db:sync:prod una vez (o yarn seed:prod para los datos de demostración) y luego yarn start:prod.
5. Apunta la comprobación de salud de tu hosting a GET /api/health. No necesita token y no tiene límite de peticiones.
6. Construye el panel con NEXT_PUBLIC_API_BASE_URL y NEXT_PUBLIC_WEBSOCKET_BASE_URL apuntando a tu API desplegada.
7. Cambia las contraseñas de los datos de demostración, o empieza con tablas vacías.

Para quitar por completo el código de demostración, ejecuta yarn remove:demo en las dos aplicaciones, con el árbol de trabajo limpio: no se puede deshacer sin control de versiones. yarn remove:mock en el panel borra los datos de ejemplo.