Entorno

Gestiona las variables de entorno, en local o en un servidor. Todo lo que difiere entre entornos es una variable de entorno, tanto para la aplicación como para PocketBase: en local viven en .env en la raíz del proyecto; en un servidor viven bajo /etc/vela, legibles solo por root, y nunca viajan dentro de una release.

Sintaxis

$ vela env <command>

• list - Mostrar qué variables existen y dónde
• get - Imprimir una variable pública
• set - Definir una variable, pidiendo el valor
• unset - Eliminar una variable
• import - Fusionar un archivo dotenv con el entorno

Ámbitos

En un servidor, el entorno de un objetivo son tres capas, de la más baja a la más alta. Una variable en una capa superior gana:

$ vela env set VELASTACK_API_KEY -t all        # todos los objetivos, en todos los servidores donde se despliega la aplicación
$ vela env set WHATSAPP_MODE -t preview        # todas las previsualizaciones
$ vela env set STRIPE_SECRET_KEY -t production # un objetivo

-t all y -t preview escriben en todos los servidores a los que están vinculados los objetivos del proyecto, y reinician en cada uno todas las instancias a las que llega la capa. Una rama de previsualización hereda ambas capas compartidas, así que nunca está vacía en su primer despliegue; -t preview:<branch> se dirige a una sola previsualización. -t local es el .env de esta máquina.

Para env, un -t preview a secas significa la capa que comparten todas las previsualizaciones; para vela deploy significa la rama que tienes abierta. Una clave de API para previsualizaciones se define una vez; una rama se despliega muchas veces.

No hay valor por defecto. Sin -t, set, unset e import preguntan por el entorno en una terminal y se niegan en CI; list muestra todos los ámbitos a la vez.

Secreto salvo que se diga lo contrario

Un valor en un servidor es secreto por defecto: se escribe, nunca se lee de vuelta, y se muestra como ••••. Pasa --public para uno que deba poder leerse — vela env get lo imprime y vela env list lo muestra. Las claves PUBLIC_* son públicas sin pedirlo, ya que están pensadas para el navegador. Definir una clave de nuevo con o sin --public la mueve; unset la elimina del lado en que estuviera.

Los valores siempre se piden, nunca se toman como argumento, así que ninguno acaba en el historial del shell. Un secreto se escribe sin eco; un valor público, con eco, de modo que el propio aviso dice qué tipo estás definiendo.

La aplicación lee lo que declara src/env.ts

SvelteKit expone solo las variables declaradas en src/env.ts. Una del servidor se importa por nombre de $app/env/private, y una declarada con public: true, de $app/env/public; una variable que no está declarada no se expone en absoluto, la definas como la definas. Las plantillas declaran las variables que leen, y un comando enable que añade código que lee una también la declara. Una variable propia necesita una entrada en la llamada a defineEnvVars del archivo para que la aplicación la vea:

MY_API_KEY: {
	schema: (value) => value ?? '',
	description: 'Clave de la API de ejemplo.'
},

Las declaraciones de Vela convierten un valor ausente en '', así que la aplicación compila y arranca con un .env vacío.

PocketBase lee el mismo entorno

Con backend, PocketBase toma sus propios ajustes de las mismas variables y los muestra bloqueados en el panel de administración: APP_NAME (entregado desde src/lib/site.ts), APP_URL (el origen del despliegue salvo que indiques otro), PB_SMTP_HOST, PB_SMTP_PORT, PB_SMTP_USERNAME, PB_SMTP_PASSWORD, PB_SMTP_TLS, PB_SENDER_NAME, PB_SENDER_ADDRESS, PB_S3_*, PB_BACKUPS_S3_*, y las WHATSAPP_* / VELASTACK_* del plugin de WhatsApp. Definir PB_SMTP_HOST activa SMTP; definir PB_S3_ENDPOINT lleva las subidas a ese bucket. Los nombres de correo y almacenamiento llevan prefijo a propósito: el SMTP_HOST o S3_BUCKET propio de una aplicación no debe activar el correo ni el almacenamiento de PocketBase.

Opciones

Todos los subcomandos aceptan las mismas opciones de objetivo y conexión:

• -t, --target <target> - Qué entorno: local, all, preview, preview:<branch>, production, o cualquier objetivo vinculado como staging
• --public - En set e import: legible de vuelta
• --server <ssh> - Servidor en el que se ejecuta un objetivo, registrado en el primer uso; all y preview no lo aceptan, van a los servidores vinculados
• -i, --identity <file> - Clave privada SSH con la que autenticarse
• --ssh-port <port> - Puerto SSH
• --accept-host-keys - Confiar en una clave de host desconocida en la primera conexión (CI)

Los despliegues nunca las escriben

vela deploy no sube ni sobrescribe el entorno de un servidor. Sí lo lee: la compilación se ejecuta con el entorno resuelto del objetivo en lugar de tu .env, de modo que una página prerenderizada ve lo mismo que verá la aplicación en ejecución. Una clave definida solo en .env se deja en blanco para la compilación, y una importación de $env/static de una de ellas hace fallar el despliegue antes de subir nada. Una clave que la aplicación importa de $env/static queda fijada al compilar, así que set dice «vuelve a desplegar para aplicarla» en lugar de reiniciar.

En el primer despliegue de una instancia, se listan las claves que .env.example documenta y el objetivo no tiene y, en una terminal, se ofrece definirlas. Nada es obligatorio; el archivo documenta, no bloquea.