Referencia completa de .env

Esta referencia separa variables de instalación, seguridad, base de datos, demo, integraciones y QA. Se basa en .env.example, .env.demo.example, los compose del proyecto y las variables localizadas en el código.

Regla general:

• Si una variable contiene token, contraseña, secreto, clave API o credencial, trátala como secreto.
• No subas .env a Git.
• No pegues .env completo en tickets, chats públicos ni capturas.

Variables principales

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
COMPOSE_PROJECT_NAME	plexsub	No	No	Nombre del proyecto Docker Compose.
PORT	5000	No	No	Puerto publicado hacia el host.
APP_IMAGE_REF	Imagen GHCR fijada por digest en .env.example	Sí en producción	Media	Imagen de PlexSub a ejecutar. Conviene fijarla por digest.
PLEXSUB_POSTGRES_IMAGE_REF	postgres:18.4-alpine fijado por digest	Sí en producción	Media	Imagen de PostgreSQL. No cambies major sin migración controlada.
APP_BASE_URL	https://plexsub.example.com	Sí en producción	Alta	URL pública real de PlexSub. Afecta enlaces, cookies y publicación.
APP_TIMEZONE	Europe/Madrid	No	No	Zona horaria de la aplicación.
NODE_ENV	production en compose	Sí en producción	Media	Modo de ejecución.
PLEXSUB_VERSION	No definido en .env.example	No	No	Versión informativa del runtime cuando se inyecta.

Base de datos

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
POSTGRES_DB	plexsub	Sí	No	Nombre de la base de datos.
POSTGRES_USER	plexsub_app_replace_me	Sí	Media	Usuario de PostgreSQL. Cámbialo.
POSTGRES_PASSWORD	Vacío en .env.example	Sí	Alta	Contraseña de PostgreSQL. Debe ser fuerte y privada.
DATABASE_URL	Generada por docker-compose.example.yml	Sí para la app	Alta	Cadena de conexión usada por PlexSub.
DB_CONNECT_RETRIES	15	No	No	Reintentos de conexión a base de datos.
DB_CONNECT_RETRY_DELAY_MS	4000	No	No	Pausa entre reintentos en milisegundos.
DRIZZLE_BASELINE_ADOPT	No documentado	No	Media	Uso interno de migraciones. No lo actives salvo guía técnica concreta.

Seguridad de aplicación

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
APP_SETTINGS_ENCRYPTION_KEY	replace_with_generated_service_settings_key	Sí	Alta	Clave para cifrar credenciales de servicios en base de datos. No debe perderse.
SESSION_SIGNING_SECRET	Vacío en .env.example	Sí	Alta	Firma de sesiones. Debe ser secreto fuerte.
PLEXSUB_SETUP_TOKEN	Vacío en .env.example	Recomendado	Alta	Token de arranque/setup si se usa.
TRUST_PROXY_LEVEL	0	No	Media	Número de proxies de confianza. Usa 1 solo detrás de proxy controlado.
FORCE_SECURE_COOKIES	1	Sí en HTTPS	Alta	Fuerza cookies seguras. Mantener activo en publicación HTTPS.
PLEXSUB_ALLOW_PRIVATE_TARGETS	0	No	Alta	Permite destinos privados/locales para integraciones. Mantener 0 salvo necesidad controlada.
SESSION_TIMEOUT_HOURS	24 en código	No	Media	Duración de sesión.
LOGIN_MAX_FAILED_ATTEMPTS	5 en código	No	Media	Intentos fallidos antes de bloqueo.
LOGIN_LOCKOUT_MINUTES	15 en código	No	Media	Duración del bloqueo.
RATE_LIMIT_LOGIN_WINDOW_MS	300000 en código	No	Media	Ventana de rate limit de login.
RATE_LIMIT_LOGIN_MAX	10 en código	No	Media	Intentos máximos por ventana de login.
RATE_LIMIT_OWNER_BOOTSTRAP_WINDOW_MS	No documentado	No	Media	Límite del arranque de owner.
RATE_LIMIT_OWNER_BOOTSTRAP_MAX	No documentado	No	Media	Máximo del arranque de owner.
RATE_LIMIT_PASSWORD_RESET_WINDOW_MS	No documentado	No	Media	Ventana para reset de contraseña.
RATE_LIMIT_PASSWORD_RESET_MAX	No documentado	No	Media	Máximo de resets por ventana.
API_LOG_MAX_CHARS	220 en código	No	Media	Longitud máxima de línea de log API.

Demo pública

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
DEMO_PORT	5001	No	No	Puerto local de la demo.
PLEXSUB_DEMO_MODE	1 en compose demo	Sí para demo	Media	Activa modo demo.
PLEXSUB_DEMO_PUBLIC	1 en compose demo	Sí para demo pública	Alta	Marca demo pública. Debe ir con perfil completo seguro.
PLEXSUB_DEMO_FAKE_DATA	1 en compose demo	Sí para demo pública	Media	Usa datos falsos.
PLEXSUB_DEMO_SIMULATED_SERVICES	1 en compose demo	Sí para demo pública	Media	Simula servicios externos.
PLEXSUB_DEMO_RESET	1 en compose demo	Sí para demo pública	Media	Permite reset de datos demo.
PLEXSUB_DEMO_ALLOW_REMOTE	No documentado	No	Alta	No actives acceso remoto demo sin guía específica.
ADMIN_EMAIL	[email protected] en demo	Solo demo	Media	Usuario demo público por diseño.
ADMIN_PASSWORD	demo123 en demo	Solo demo	Alta	Contraseña demo pública. No usar en producción.

Integraciones de servidor multimedia

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
PLEX_SERVER_URL	No definido	Solo si usas Plex	Media	URL del servidor Plex.
PLEX_TOKEN	No definido	Solo si usas Plex	Alta	Token Plex.
PLEX_ALLOWED_LIBRARIES	No definido	No	Media	Restricción de bibliotecas Plex.
JELLYFIN_URL	No definido	Solo si usas Jellyfin	Media	URL Jellyfin.
JELLYFIN_API_KEY	No definido	Solo si usas Jellyfin	Alta	API key Jellyfin.
JELLYFIN_TOKEN	No definido	Solo si usas Jellyfin	Alta	Token Jellyfin si aplica.
EMBY_URL	No definido	Solo si usas Emby	Media	URL Emby.
EMBY_API_KEY	No definido	Solo si usas Emby	Alta	API key Emby.
EMBY_TOKEN	No definido	Solo si usas Emby	Alta	Token Emby si aplica.

Peticiones, metadatos y servicios Arr

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
OVERSEERR_URL	No definido	Solo si usas Seerr	Media	URL de Overseerr/Jellyseerr.
OVERSEERR_API_KEY	No definido	Solo si usas Seerr	Alta	API key Seerr.
OVERSEERR_WEBHOOK_SECRET	No definido	No	Alta	Secreto de webhook Seerr.
OVERSEERR_AUTO_CREATE_USERS	No definido	No	Media	Comportamiento de creación automática.
OVERSEERR_DEFAULT_PERMISSIONS	No definido	No	Media	Permisos por defecto en Seerr.
RADARR_URL	No definido	Solo si usas Radarr	Media	URL Radarr.
SONARR_URL	No definido	Solo si usas Sonarr	Media	URL Sonarr.
LIDARR_URL	No definido	Solo si usas Lidarr	Media	URL Lidarr.
READARR_URL	No definido	Solo si usas Readarr	Media	URL Readarr.
PLEXSUB_TMDB_API_KEY	No definido	Según proveedor	Alta	API key TMDB para metadatos.
TMDB_API_KEY	No definido	Según proveedor	Alta	Alias/variable TMDB usada por código.
PLEXSUB_LASTFM_API_KEY	No definido	Según proveedor	Alta	API key Last.fm para música si se usa.
LASTFM_API_KEY	No definido	Según proveedor	Alta	Alias/variable Last.fm.
PLEXSUB_REQUESTS_METADATA_PROVIDER	No definido	No	Media	Proveedor global de metadatos de peticiones.
PLEXSUB_REQUESTS_TV_METADATA_PROVIDER	No definido	No	Media	Proveedor TV.
PLEXSUB_REQUESTS_MUSIC_METADATA_PROVIDER	No definido	No	Media	Proveedor música.
REQUEST_USAGE_RESET_TIMEZONE	No definido	No	No	Zona horaria para reset de uso.

Descargas, subtítulos, indexadores y analítica

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
QBITTORRENT_URL	No definido	Solo si usas qBittorrent	Media	URL qBittorrent.
QBITTORRENT_USERNAME	No definido	Solo si usas qBittorrent	Alta	Usuario qBittorrent.
QBITTORRENT_PASSWORD	No definido	Solo si usas qBittorrent	Alta	Contraseña qBittorrent.
BAZARR_URL	No definido	Solo si usas Bazarr	Media	URL Bazarr.
BAZARR_API_KEY	No definido	Solo si usas Bazarr	Alta	API key Bazarr.
TAUTULLI_URL	No definido	Solo si usas Tautulli	Media	URL Tautulli.
TAUTULLI_API_KEY	No definido	Solo si usas Tautulli	Alta	API key Tautulli.
MAINTAINERR_URL	No definido	Solo si usas Maintainerr	Media	URL Maintainerr.
TRACEARR_URL	No definido	Solo si usas Tracearr	Media	URL Tracearr.
TRACEARR_API_KEY	No definido	Solo si usas Tracearr	Alta	API key Tracearr.
TRACEARR_SCAN_PAGE_SIZE	No documentado	No	No	Tamaño de página en escaneos.
TRACEARR_SCAN_MAX_PAGES	No documentado	No	No	Máximo de páginas.
TRACEARR_HISTORY_SCAN_MAX_PAGES	No documentado	No	No	Máximo de páginas de historial.
JELLYSTAT_URL	No definido	Solo si usas Jellystat	Media	URL Jellystat.
JELLYSTAT_API_KEY	No definido	Solo si usas Jellystat	Alta	API key Jellystat.
JELLYSTAT_TOKEN	No definido	Solo si usas Jellystat	Alta	Token Jellystat.
PROWLARR_URL	No definido	Solo si usas Prowlarr	Media	URL Prowlarr.
PROWLARR_API_KEY	No definido	Solo si usas Prowlarr	Alta	API key Prowlarr.
JACKETT_URL	No definido	Solo si usas Jackett	Media	URL Jackett.
JACKETT_API_KEY	No definido	Solo si usas Jackett	Alta	API key Jackett.
TRANSMISSION_URL	No definido	Solo si usas Transmission	Media	URL Transmission.
TRANSMISSION_USERNAME	No definido	Solo si usas Transmission	Alta	Usuario Transmission.
TRANSMISSION_PASSWORD	No definido	Solo si usas Transmission	Alta	Contraseña Transmission.
DELUGE_URL	No definido	Solo si usas Deluge	Media	URL Deluge.
DELUGE_USERNAME	No definido	Solo si usas Deluge	Alta	Usuario Deluge.
DELUGE_PASSWORD	No definido	Solo si usas Deluge	Alta	Contraseña Deluge.

Pagos, correo y notificaciones

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
KOFI_WEBHOOK_VERIFICATION_TOKEN	No definido	Solo si usas Ko-fi	Alta	Verificación de webhook Ko-fi.
SMTP_HOST	No definido	Solo si usas correo	Media	Host SMTP.
SMTP_PORT	No definido	Solo si usas correo	Media	Puerto SMTP.
SMTP_SECURE	No definido	No	Media	Uso de TLS/SSL SMTP.
SMTP_USER	No definido	Según proveedor	Alta	Usuario SMTP.
SMTP_PASS	No definido	Según proveedor	Alta	Contraseña SMTP.
SMTP_FROM	No definido	Recomendado	Media	Remitente.
SMTP_REPLY_TO	No definido	No	Media	Dirección de respuesta.
WEB_PUSH_VAPID_PUBLIC_KEY	No definido	Solo Web Push	Media	Clave pública VAPID.
WEB_PUSH_VAPID_PRIVATE_KEY	No definido	Solo Web Push	Alta	Clave privada VAPID.
WEB_PUSH_VAPID_SUBJECT	No definido	Solo Web Push	Media	Contacto VAPID.

Pausas de módulos

Variable	Valor por defecto documentado	Obligatoria	Seguridad	Uso
PLEXSUB_NATIVE_REQUESTS_MODULE_PAUSED	No definido	No	Media	Pausa Peticiones nativas.
PLEXSUB_NATIVE_INVITATIONS_MODULE_PAUSED	No definido	No	Media	Pausa Invitaciones nativas.
PLEXSUB_WIZARR_MODULE_PAUSED	No definido	No	Media	Pausa Wizarr.
PLEXSUB_SMTP_MODULE_PAUSED	No definido	No	Media	Pausa SMTP.
PLEXSUB_KNOWLEDGE_BASE_MODULE_PAUSED	No definido	No	Media	Pausa Base de conocimiento.

Variables de QA, desarrollo o pruebas

Estas variables aparecen en el código o scripts, pero no forman parte de la configuración normal de usuario:

QA_BASE_URL, QA_DEBUG, QA_JELLYFIN_CONFIGURED, QA_SERVICE, QA_STANDALONE, QA_VIEWPORT, ESLINT_MAX_WARNINGS, MOCK_JELLY_HOST, MOCK_JELLYFIN_PORT, MOCK_JELLYFIN_TOKEN, MOCK_JELLYSTAT_PORT, MOCK_JELLYSTAT_TOKEN, CONFIRM_DROP_TEMPORARY_PASSWORD, ALLOW_LEGACY_POSTGRES_PASSWORD_SETTINGS_KEY, CUSTOMER_INCIDENT_ATTACHMENT_MAX_TOTAL_BYTES, RATE_LIMIT_BRANDING_MEDIA_IMAGE_MAX, RATE_LIMIT_BRANDING_MEDIA_IMAGE_WINDOW_MS, PLEXSUB_MEDIA_IMAGE_CACHE_DIR, PLEXSUB_LOCALE.

No las uses en producción salvo que una guía técnica concreta lo indique.