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 sirven tal cual para una ejecución local, y el inicio con Docker Compose no necesita ningún archivo.

Dónde están los ajustes

Un archivo, .env en la carpeta del sitio web, y todos sus valores son opcionales. Los valores NEXT_PUBLIC_* se leen cuando se construye el sitio web y son públicos, así que nunca guardan un secreto; API_INTERNAL_URL lo lee el propio servidor del sitio web. Sin el archivo, el sitio funciona con sus datos de ejemplo integrados. Para usar una API, créalo a partir de .env.example, que apunta a una en http://localhost:8000: cp .env.example .env. Con Docker, pasa los valores NEXT_PUBLIC_* como --build-arg y API_INTERNAL_URL con -e.

Dónde están los ajustes

Un archivo, .env en la carpeta del panel, que se lee cuando se construye el panel y, para PORT, cuando empieza yarn dev o yarn start. Todos sus valores son públicos, así que nunca guarda un secreto: las claves de proveedores y de pago viven en el .env de la API. Sin el archivo, el panel funciona con sus datos de ejemplo integrados. Para usar una API, créalo a partir de .env.example, que apunta a una en http://localhost:8000: cp .env.example .env. Con Docker, pasa los mismos valores como --build-arg.

Dónde están los ajustes

Un archivo, .env en la carpeta de la API, que la API lee con yarn dev, yarn start:prod y yarn seed. 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.

La imagen de Docker define sus propios valores por defecto, así que docker run funciona sin archivo: NODE_ENV=production, SQLite en /data/database.sqlite, archivos subidos en /data/uploads, CORS_ORIGIN para los dos frontends locales, FRONTEND_URL y DASHBOARD_URL definidos como http://localhost:3031, WEBSITE_URL=http://localhost:3030, PUBLIC_API_URL=http://localhost:8000 y PUBLIC_MEDIA_URL=http://localhost:8000/media. Sustituye cualquiera con -e.

Lo esencial de la API

La API comprueba JWT_SECRET y, en producción, CORS_ORIGIN antes de iniciar. Si falta uno o no sirve, se detiene con una línea que empieza por The API cannot start: y dice qué corregir.

Genera tu propio JWT_SECRET con:

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

Cada función opcional de abajo está desactivada mientras sus variables en .env.example sigan vacías.

Pagos

Dos flujos mueven dinero. La página de facturación del panel cambia el plan de suscripción de un espacio de trabajo, y el pago del sitio web vende las licencias. Ambos piden los datos de la tarjeta solo en la página de Stripe o de PayPal (un cambio a un plan superior se cobra a la tarjeta que Stripe ya tiene), así que nunca se escriben en tu sitio, y ambos funcionan sin ninguna cuenta mediante pagos de prueba integrados que no cobran a nadie. Usa primero claves de prueba: no mueven dinero.

STRIPE_SECRET_KEY=sk_test_your_key
STRIPE_WEBHOOK_SECRET=whsec_your_secret
BILLING_PROVIDER=
BILLING_GRACE_DAYS=7
PAYPAL_CLIENT_ID=your-client-id
PAYPAL_CLIENT_SECRET=your-client-secret
PAYPAL_ENV=sandbox

En tu propio equipo Stripe no puede llegar al webhook, así que las páginas de retorno piden la sesión a Stripe por sí mismas y un pago de prueba se completa igualmente. Un plan o una licencia cuenta como pagado solo cuando la API lo ha verificado con el proveedor, nunca por la dirección de retorno sola. Northstack no cobra impuestos por sí mismo, así que configura los impuestos de tu país antes de aceptar pagos reales.

• Facturación de suscripciones
• El pago de licencias

Correo electrónico

Las invitaciones, los restablecimientos de contraseña, los recibos de licencia, los correos de facturación y el resumen semanal se envían por SMTP cuando se define SMTP_HOST, cada uno en el idioma del destinatario (el del espacio de trabajo cuando no ha elegido ninguno). Hasta entonces cada mensaje se escribe en el registro de la API, con sus enlaces, para que una instalación local pueda seguirlos (con Docker: docker compose logs api).

SMTP_HOST=smtp.your-provider.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-smtp-user
SMTP_PASSWORD=your-smtp-secret
SMTP_FROM=Northstack <no-reply@your-domain.com>
CONTACT_INBOX=hello@your-domain.com

SMTP_SECURE=true es para un servidor que habla TLS desde el primer byte, normalmente en el puerto 465. CONTACT_INBOX es adonde se reenvían los mensajes del formulario de contacto del sitio web; vacío los guarda solo en la base de datos.

Usa MySQL en lugar de SQLite

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

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USERNAME=root
DB_PASSWORD=your-database-secret
DB_DATABASE=northstack

Luego ejecuta yarn seed, que crea las tablas y los datos de ejemplo. La API en marcha solo crea y actualiza las tablas por sí sola cuando NODE_ENV=development, así que con NODE_ENV=production ejecuta yarn admin:create:prod una vez tras yarn build para las tablas y tu primer administrador de la plataforma (yarn seed:prod para una instalación de ejemplo), y yarn schema:prod tras cada actualización. La imagen de Docker crea la base de datos por sí sola solo en SQLite: en MySQL, ejecuta tú mismo node dist/database/create-admin.js (o node dist/database/seeder.js) una vez en el contenedor.

Archivos subidos y multimedia

La API sirve por sí misma los archivos de marca del kit en /media. Los archivos e imágenes de proyectos subidos desde el panel, de hasta 10 MB cada uno, se guardan en el disco de la API bajo MEDIA_UPLOAD_DIR y se sirven en /media/uploads/…, salvo que se defina un bucket.

PUBLIC_MEDIA_URL=http://localhost:8000/media
MEDIA_UPLOAD_DIR=./public/media/uploads

PUBLIC_MEDIA_URL es la dirección a la que un navegador llega a /media. En un servidor, apunta MEDIA_UPLOAD_DIR a un almacenamiento persistente; con Docker está en el volumen de datos, y el contenedor mueve allí por sí solo una carpeta relativa. La API envía todos los archivos con nosniff, y un archivo que no sea una imagen, un PDF, texto plano, audio o vídeo como descarga.

Para enviar los archivos subidos a un bucket de Cloudflare R2, define las cinco variables. Con menos de cinco, los archivos siguen en el disco. El registro de la API indica el almacenamiento que usa al iniciar: Media storage: R2 bucket seguido del nombre del bucket, o Media storage: local folder seguido de la carpeta.

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

Sitio web y 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 uno, y vuelve a construir (o reinicia yarn dev) tras cambiar uno. Con Docker, pásalos como --build-arg.

NEXT_PUBLIC_API_BASE_URL decide de dónde vienen los datos de cada frontend. Vacío, o sin ningún .env, la aplicación funciona con sus datos de ejemplo integrados y no llama a ninguna API. Definido con la dirección de la API incluido /api (http://localhost:8000/api en .env.example y en las imágenes de Docker), usa esa API, y recurre a los datos de ejemplo solo en el navegador mientras esa API no responde.

• Los datos de ejemplo

Los ajustes del sitio web

El puerto del sitio web es 3030, escrito en los scripts de su package.json. Para otro, ejecuta yarn next dev -p 3040 (o yarn next start -p 3040 tras yarn build).

Los ajustes del panel

Aquí no va ninguna clave de proveedor de IA ni de pago: un valor NEXT_PUBLIC_* es visible para cualquiera que abra la página. Un proveedor para el que la API no tiene clave aún se puede usar con una clave que quien lee añade en el propio asistente.

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: los frontends incorporan estos valores al construirse.

Cambia un puerto cuando otro programa ya lo usa, como ADMIN_PORT=3041. El CORS_ORIGIN, FRONTEND_URL, DASHBOARD_URL, WEBSITE_URL, PUBLIC_API_URL y PUBLIC_MEDIA_URL de la API, y las direcciones de API, sitio web y panel de los frontends, se construyen todos a partir de los puertos y las tres direcciones, así que los siguen por sí solos.

• Un puerto ya está en uso

El contenedor de la API también lee back-end/.env cuando existe, así que las claves opcionales (Stripe, PayPal, correo, R2, IA, MCP) se definen en un solo lugar para yarn dev y para Docker. docker-compose.yml prevalece en los valores que difieren dentro de un contenedor: NODE_ENV=production, el puerto, la ruta de la base de datos, la carpeta de archivos subidos y las direcciones de arriba. Sin un JWT_SECRET propio, o con el de ejemplo, la API genera uno y lo guarda en el volumen de datos. La base de datos y los archivos subidos viven en el volumen northstack-data.

Claves del asistente de IA

El servidor MCP

Modo demostración