Resumen de la configuración

Vision lee config.yaml desde su directorio de trabajo y luego superpone las variables de entorno. Las variables de entorno siempre tienen prioridad sobre los valores del archivo, de modo que los secretos pueden quedar fuera del archivo de configuración.

Cuando se instala con vision install, el directorio de trabajo es /etc/vision/ y el servicio carga:

• /etc/vision/config.yaml — parámetros no secretos
• /etc/vision/vision.env — secretos, cargados como variables de entorno por systemd

Un config.yaml ausente no es un problema — el servidor recurre a los valores predeterminados integrados (modo de desarrollo, puerto 3303, base de datos en ./data/vision.db).

La configuración se valida al iniciar. Los valores no válidos — tiempos de espera no positivos, concurrencias en cero, TTL fuera de rango — abortan el inicio con un error config: validate: en el journal del servicio que nombra la clave problemática.

Comprueba una edición de la configuración antes de reiniciar con vision config validate, o imprime la configuración combinada efectiva (con los secretos ocultos) con vision config print — consulta la Referencia de la CLI. vision config print --reference imprime cada clave, su valor predeterminado y una descripción, sin necesidad de una configuración instalada.

sudo vision config validate
sudo vision restart

Selección del entorno

El valor env (development, staging o production) cambia el rigor de la validación:

Comportamiento	development	production
CORS allowed_origins	se permite comodín / vacío	orígenes concretos obligatorios
jwt_secret	opcional (efímero)	obligatorio
Clave de cifrado	opcional (stub)	obligatoria
Encabezados de seguridad / CSP estricta	relajados	aplicados

staging sigue la columna de production para las validaciones estrictas: allí también se requieren orígenes CORS concretos, jwt_secret y la clave de cifrado.

Obligatorio en producción

Un despliegue de producción necesita estos secretos y los valores iniciales del administrador. El instalador los genera automáticamente:

/etc/vision/vision.env

VISION_ENCRYPTION_KEY=<base64 32 bytes>     # openssl rand -base64 32
VISION_AUTH_JWT_SECRET=<base64 32 bytes>    # openssl rand -base64 32
ADMIN_EMAIL=admin@localhost
ADMIN_PASSWORD=<password>

El secreto JWT y la clave de cifrado deben ser dos valores distintos — el inicio falla si son idénticos.

También necesita orígenes CORS concretos en config.yaml:

env: production
http:
  allowed_origins:
    - "https://vms.example.com"

Detrás de un proxy inverso

Cuando Vision está detrás de un proxy que termina TLS (nginx, Caddy, Traefik), establece http.secure_cookies: true (el instalador escribe false) y asegúrate de que el proxy reenvíe el Host original y los encabezados de actualización de WebSocket/SSE. HSTS se habilita automáticamente cuando env: production; http.tls_enabled ya no es una opción de configuración.

Mantén http.secure_cookies: false solo mientras los usuarios abran Vision directamente por HTTP sin cifrar. La URL que el servidor Alta usa para llegar a Vision para la autorización WHEP se establece explícitamente para cada servidor (su callback base URL) cuando lo agregas — consulta Conectar un servidor Alta.

Base de datos y migraciones

La base de datos es SQLite (modo WAL). Las migraciones de esquema se ejecutan automáticamente en cada inicio — no hay un paso de migración separado, y las migraciones son solo hacia adelante: no existe una ruta de regreso a una versión anterior. Usa sudo vision backup antes de una actualización, de modo que una copia de seguridad sea tu plan de reversión — consulta Copia de seguridad y restauración.

Consulta la referencia completa para ver cada opción y su variable de entorno.