Manual

Apariencia

Variables de entorno ​

Referencia exhaustiva de cada variable que debe estar definida en producción, dividida en backend (Laravel) y frontend (Next.js).

Nunca commitear

.env, .env.production, .env.local — todos están en .gitignore. Si un secret se filtra al repo, rota la key inmediatamente y borra el commit del historial (git filter-repo).

Backend ​

Ubicación: humae_backend/.env en el servidor de producción.

Copia humae_backend/.env.example como punto de partida y reemplaza valores.

Aplicación ​

VariableValor prodDescripción
APP_NAMEHUMAENombre de la app (aparece en correos)
APP_ENVproductionHabilita optimizaciones de Laravel
APP_KEYbase64:...Generar con php artisan key:generate
APP_DEBUGfalseCrítico: true en prod expone stacktraces
APP_URLhttps://api.humae.com.mxURL base del backend
APP_TIMEZONEAmerica/Mexico_CityPara timestamps server-side
APP_LOCALEes_MXMensajes de validación en español

Frontend coupling (CORS + Sanctum) ​

VariableValor prod
FRONTEND_URLhttps://humae.com.mx
SANCTUM_STATEFUL_DOMAINShumae.com.mx,www.humae.com.mx
SESSION_DOMAIN.humae.com.mx
SESSION_SECURE_COOKIEtrue
SESSION_SAME_SITElax

CORS

El backend solo acepta requests desde FRONTEND_URL. Si agregas un dominio adicional (preview, staging), debes ampliar la lista en config/cors.php y SANCTUM_STATEFUL_DOMAINS.

Base de datos ​

VariableValor prod
DB_CONNECTIONmysql
DB_HOSTIP o hostname del servidor MySQL
DB_PORT3306
DB_DATABASEhumae_production
DB_USERNAMEusuario con acceso solo a esa DB
DB_PASSWORDpassword fuerte (≥24 chars)
DB_SOCKET(vacío salvo uso de socket)

Redis (cache + queue + sesiones) ​

VariableValor prod
REDIS_HOSTIP o hostname
REDIS_PORT6379
REDIS_PASSWORDpassword (obligatorio en prod)
REDIS_CLIENTpredis
REDIS_DB0
REDIS_CACHE_DB1

Drivers de servicios internos ​

VariableValor prodNota
QUEUE_CONNECTIONredisEncola notifications + jobs
CACHE_STOREredisCache de config + query cache
SESSION_DRIVERredisSesiones Sanctum SPA
BROADCAST_CONNECTIONlog(Fase 2: cambiar a pusher si se agrega realtime)
FILESYSTEM_DISKpublicUploads van al disco local (storage/app/public); documentos privados al disco local

Logging ​

VariableValor prod
LOG_CHANNELdaily
LOG_DAILY_DAYS14
LOG_LEVELwarning
LOG_DEPRECATIONS_CHANNELnull

Stripe (pagos) ​

VariableValor prodCómo obtenerla
STRIPE_KEYpk_live_...Stripe Dashboard → Developers → API keys
STRIPE_SECRETsk_live_...Ídem. No exponer al frontend.
STRIPE_WEBHOOK_SECRETwhsec_...Stripe Dashboard → Webhooks → endpoint → Signing secret
STRIPE_CURRENCYmxnCódigo ISO 4217
STRIPE_PRICE_CANDIDATE_6M(opcional)price_... si se pre-crea el precio

Almacenamiento local (archivos) ​

VariableValor prodNota
FILESYSTEM_DISKpublicDisco default; documentos sensibles van explícitos al local

No hay credenciales — todo es filesystem del propio servidor.

Antes de exponer al tráfico

Ejecutar una vez php artisan storage:link y confirmar que storage/ pertenece al usuario de PHP-FPM (chown -R www-data:www-data storage && chmod -R 775 storage). Sin symlink, las URLs /storage/... devuelven 404.

Ver: Storage local →.

SMTP local (correos) ​

VariableValor prodNota
MAIL_MAILERsmtp—
MAIL_HOST127.0.0.1Postfix corre en el mismo host
MAIL_PORT25—
MAIL_USERNAME(vacío)Postfix local sin auth cuando escucha en loopback
MAIL_PASSWORD(vacío)—
MAIL_ENCRYPTIONnullEncripta sólo el hop Postfix → MTA destino (via smtp_tls_security_level)
MAIL_FROM_ADDRESSno-reply@humae.com.mx—
MAIL_FROM_NAMEHUMAE—
MAIL_REPLY_TOsoporte@humae.com.mxDirección monitoreada

Ver: SMTP local →.

Observabilidad opcional ​

VariableValorCuándo activar
SENTRY_LARAVEL_DSNhttps://...@sentry.io/...Si usas Sentry para error tracking
SENTRY_TRACES_SAMPLE_RATE0.1Porcentaje de traces a muestrear
TELESCOPE_ENABLEDfalseSiempre false en prod (Telescope es dev-only)

Frontend ​

Ubicación: humae_frontend/.env.production o variables en Vercel/Netlify/Cloudflare Pages dashboard.

VariableValor prodNota
NEXT_PUBLIC_API_URLhttps://api.humae.com.mx/api/v1URL base del backend
NEXT_PUBLIC_SITE_URLhttps://humae.com.mxURL pública del frontend
NEXT_PUBLIC_SENTRY_DSNhttps://...@sentry.io/...Opcional: error tracking client-side
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEYpk_live_...Solo si usas Elements embebidos; para Checkout hosted no es necesario

NEXT_PUBLIC prefix

Cualquier variable expuesta al cliente debe llevar NEXT_PUBLIC_. Las variables sin ese prefijo son solo accesibles en server components. Nunca pongas STRIPE_SECRET ni credenciales del servidor de correo en el frontend.

Docs (opcional) ​

Si despliegas humae_docs/ a Cloudflare Pages o similar, no requiere variables en el MVP (es un sitio estático puro).

Verificación rápida ​

Después de setear las variables, corre estos checks antes de exponer al público:

Backend ​

bash
# Dentro del servidor backend
cd /path/to/humae_backend

# Verificar que APP_KEY exista
php artisan tinker --execute="echo config('app.key');"

# Verificar conexión a DB
php artisan tinker --execute="\DB::connection()->getPdo();"

# Verificar Redis
php artisan tinker --execute="\Illuminate\Support\Facades\Cache::put('check', 'ok', 60); echo \Cache::get('check');"

# Verificar Stripe (crea una Checkout session de prueba)
php artisan tinker --execute="app(\App\Helpers\StripeClient::class)->createCheckoutSession([/*...*/]);"

# Verificar disco local (debe devolver 'ok')
php artisan tinker --execute="Storage::disk('public')->put('check.txt','ok'); echo Storage::disk('public')->get('check.txt');"

# Verificar SMTP local (revisar /var/log/mail.log que el mensaje saliera)
php artisan tinker --execute="Mail::raw('humae smoke test', fn(\$m) => \$m->to('admin@humae.com.mx')->subject('smoke'));"

# Verificar que el scheduler esté activo
php artisan schedule:list

Frontend ​

bash
# Verificar build
cd /path/to/humae_frontend
npm run build

# Verificar que se conecta al API
curl $NEXT_PUBLIC_API_URL/health
# → { "success": true, "data": { "app": "ok", ... } }

Rotación de secrets ​

Cada 90 días o ante sospecha de compromiso:

  1. Generar nuevo secret en el provider (Stripe) o rotar DKIM en OpenDKIM.
  2. Actualizar .env en producción.
  3. No reiniciar hasta cambiar también cualquier referencia hardcoded (no debería haber).
  4. Reiniciar workers: supervisorctl restart humae-queue:*.
  5. Revocar el secret viejo en el provider / retirar el selector DKIM antiguo del DNS tras 24 h de solapamiento.

Para APP_KEY: rotarlo invalida todas las sesiones activas y tokens cifrados. Coordinar mantenimiento.

Para STRIPE_WEBHOOK_SECRET: rotarlo invalida webhooks en curso. Pausar brevemente el endpoint durante la rotación.

Siguiente ​

Setup paso-a-paso de cada provider externo: Servicios externos →

Manual de usuario HUMAE · Uso interno

© HUMAE