Uso seguro de variables de entorno

Qué cubre este artículo sobre variables de entorno

• Qué son las variables de entorno y para qué sirven.
• Cómo funcionan los archivos .env.
• Reglas de seguridad para proyectos locales de IA.
• Cómo Docker Compose procesa las variables de entorno.
• Errores comunes y alternativas mejores.

Introducción: uso seguro de variables de entorno

Las variables de entorno permiten separar la configuración del código. De este modo, contraseñas, claves de API y URLs de bases de datos no terminan directamente en el código fuente. En proyectos locales de IA, se utilizan frecuentemente para configurar Ollama, Open WebUI, contenedores Docker y agentes. Usarlas correctamente evita muchos problemas de seguridad.

Este artículo está dirigido a principiantes. Muestra cómo trabajar con variables de entorno, explica las trampas típicas e indica cuándo tienen sentido soluciones más robustas como archivos .env cifrados o gestores de secretos.

¿Qué son las variables de entorno?

Una variable de entorno es un valor disponible para el proceso en ejecución. Los programas las leen y las utilizan como configuración. Algunos ejemplos:

• DATABASE_URL
• OPENAI_API_KEY
• OLLAMA_HOST
• PORT
• LOG_LEVEL

Se definen a menudo en archivos .env o directamente en el shell.

¿Por qué usar variables de entorno?

• Separación: La configuración no está en el código.
• Flexibilidad: La misma aplicación funciona con valores diferentes.
• Seguridad: Los secretos no se guardan en el repositorio.
• Simplicidad: Rápidas de establecer y modificar.

Reglas de seguridad fundamentales

• No incluir archivos .env en Git.
• Restringir permisos: Hacer que los archivos sean legibles solo para el propietario.
• No mostrar secretos en logs ni mensajes de error.
• No almacenar variables de entorno en imágenes públicas.
• Dar acceso solo al proceso que las necesita.
• Rotar valores regularmente.

Archivos .env

Un archivo .env contiene una variable por línea:

OLLAMA_HOST=http://localhost:11434
OPEN_WEBUI_PORT=8080
DATABASE_URL=postgresql://user:pass@localhost/db

Muchas herramientas como Python-dotenv, Docker Compose y Node.js cargan estos archivos automáticamente.

Docker y Docker Compose

En Docker Compose, las variables de entorno se pueden establecer de varias formas:

• env_file: Referencia a un archivo .env.
• environment: Valores directos en el archivo Compose.
• Secrets: Docker Secrets en Swarm o Kubernetes.

Ejemplo:

services:
  webui:
    image: open-webui:latest
    env_file:
      - .env
    environment:
      - OLLAMA_BASE_URL=http://ollama:11434

Errores comunes

• .env en el repositorio: Fugas por envíos accidentales.
• Permisos débiles en archivos: Cualquier usuario puede leer los secretos.
• Salida en logs: print(os.environ) por accidente.
• Demasiadas variables: Difícil de gestionar y propenso a errores.
• Valores obsoletos: Siguen activos aunque las contraseñas hayan cambiado.

Alternativas mejores

Para mayor seguridad o equipos más grandes, considera:

• Archivos .env cifrados con dotenvx o SOPS.
• Docker Secrets en Swarm.
• Kubernetes Secrets en K8s.
• Gestores de secretos como Infisical o HashiCorp Vault.

Conceptos importantes

• Variable de shell: Solo válida en el shell actual.
• Variable de entorno: Heredable a procesos secundarios.
• env_file: Archivo que carga variables.
• Secret: Información sensible que requiere protección especial.
• Export: Hacer una variable disponible en el shell.

Ejemplo práctico: Ollama y Open WebUI

# .env
OLLAMA_BASE_URL=http://ollama:11434
OPEN_WEBUI_PORT=8080
OPEN_WEBUI_ENABLE_SIGNUP=false

Este archivo se crea localmente y no se incluye con Docker Compose.

Enlaces e información adicional

• BotServ.de Gestión segura de claves API
• BotServ.de Gestión de secretos
• BotServ.de Fundamentos de Docker
• dotenvx

FAQ: Variables de entorno

¿Son seguras las .env? Solo si no llegan al repositorio y tienen los permisos correctos. Para equipos en producción, las soluciones cifradas son mejores.

¿Cómo protejo mis archivos .env? Usa chmod 600 .env para que solo el propietario pueda leerlos e inclúyelos en .gitignore.

¿Puedo cifrar variables de entorno en Docker Compose? Sí, mediante Docker Secrets, Bind Mounts con archivos cifrados o herramientas externas.

¿Qué pasa si hago commit a Git? Rota los valores, ya que se consideran comprometidos.

¿Debo poner todas las configuraciones en .env? Solo los valores sensibles y configuraciones específicas del entorno. La configuración general debe ir en el código o archivos de configuración.

Fuentes y lecturas adicionales

• OWASP Secrets Management: https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html
• Docker Compose Environment: https://docs.docker.com/compose/environment-variables/
• dotenvx: https://dotenvx.com/

Resumen: uso seguro de variables de entorno

Las variables de entorno y los archivos .env son una forma sencilla de separar la configuración y los secretos del código. Son omnipresentes en proyectos locales de IA. Lo importante es tener permisos de archivo correctos, excluirlos de Git, evitar que aparezcan en logs y rotar los valores regularmente. Para configuraciones más grandes o en producción, considera cambiar a archivos .env cifrados, Docker Secrets o gestores de secretos.