CAPÍTULO 1 · Un equipo, una base común
Lo que cambia entre máquinas no tiene que cambiar el código
Separar los archivos de configuración hizo visible qué pertenece a cada entorno, pero no resolvió por sí solo cómo entregar una contraseña o un hostname. Podríamos escribirlos en production.py, aunque entonces compartir el código implicaría compartir información que no todos necesitan conocer. También obligaría a modificar archivos cada vez que cambie el destino.
Establecemos un contrato de variables: qué nombre lee el proyecto, qué significa y cuándo es obligatorio. En el PC podemos usar un .env con carga explícita; en el servidor los valores llegarán al proceso desde su configuración. Los textos deben convertirse al tipo esperado. Una cadena que dice False no puede tratarse descuidadamente como si ya fuera un booleano.
La ausencia de un valor requerido debe descubrirse de forma clara, sin imprimir el secreto para diagnosticarla. Ya tenemos una aplicación que puede cambiar de entorno conservando su código. Antes de darle datos y funciones, necesitamos entender qué sucede cuando una petición entra: ahí se apoyarán tanto el comportamiento normal como las protecciones que vamos a compartir.
Leer esta parte dentro del relato completo →DEL RELATO A LA PRÁCTICA
Vamos a desarrollar esta decisión con su mapa, explicación, código y ejercicio.
LABORATORIO DE CONFIGURACIÓN
Prepara tu estación de despliegue
Cambia el entorno, el servidor y la identidad para comparar sus responsabilidades.
Simulación didáctica. Los valores son ejemplos: no crea recursos, no inicia sesión ni publica archivos. Sin JavaScript, consulta la tabla y los pasos de la lección.
MIRA · CONECTA · COMPRENDE
El panel de configuración
Las flechas resumen el recorrido conceptual. Los controles y dependencias se detallan debajo.
Selecciona una pieza para destacar su responsabilidad.
Leer la explicación del mapa
- Archivo local. Define valores de práctica
- Cargador. Lee antes de importar base
- Tipos. Convierte y valida entradas
- Django. Usa configuración efectiva
01 / EL PROBLEMA
¿Para qué sirve?
Un .env guardado junto al código no cambia os.environ por sí solo. También es fácil interpretar la cadena False como un booleano verdadero.
02 / COMPRENDER
El concepto, explicado
El proceso recibe variables del sistema o de su lanzador. python-dotenv es un cargador opcional para desarrollo; se instala en el entorno y se ejecuta explícitamente. En este ejemplo development.py carga .env antes de importar base.py.
load_dotenv con override=False respeta las variables ya definidas en la terminal. Así puedes probar una configuración sin editar el archivo. Usa comillas según la sintaxis del cargador cuando haya espacios o #; no existe una regla general de prohibir comillas.
El código común lee nombres estables: SECRET_KEY, DB_HOST, DB_NAME, DB_USER, DB_PASSWORD y DB_PORT. Los valores cambian por entorno. .env.example documenta el contrato con valores ficticios. .env, dumps y tokens quedan fuera de Git y del paquete.
Los ejemplos de SensorHub enseñan una aplicación empresarial. La academia distribuida sigue arrancando con SQLite y sus dependencias actuales; añadir este cargador al proyecto de práctica requiere instalar python-dotenv.
03 / CONSTRUIR
Implementación paso a paso
- Instala python-dotenv en el proyecto de práctica y registra la dependencia revisada.
- Crea .env.example con valores ficticios y añade .env a .gitignore.
- Carga .env desde development.py antes de importar base.
- Convierte números, listas y booleanos explícitamente.
- Comprueba el entorno efectivo sin imprimir claves.
04 / APLICAR
Ejemplo en SensorHub
# config/settings/development.py (proyecto de práctica)
from pathlib import Path
from dotenv import load_dotenv
load_dotenv(Path(__file__).resolve().parents[2] / ".env", override=False)
from .base import *
DEBUG = True
ALLOWED_HOSTS = ["localhost", "127.0.0.1"]
# Fragmento de base.py: variables de ejemplo
import os
DB_PORT = int(os.getenv("DB_PORT", "5432"))
USE_EASYAUTH = os.getenv("USE_EASYAUTH", "false").strip().lower() == "true"
# .env.example (archivo independiente)
# SECRET_KEY="reemplazar-solo-en-tu-env-local"
# DB_HOST=127.0.0.1
# DB_PORT=5432
# USE_EASYAUTH=false
# .gitignore: archivo independiente
# .env
# .venv/
# venv/
# *.dump
# db.sqlite3Cómo leer el ejemplo
- parents[2] apunta a la raíz para config/settings/development.py.
- bool("False") devuelve True; comparar el texto normalizado evita ese error.
- USE_EASYAUTH es una convención de nuestra aplicación, no una opción que configure Azure automáticamente.
Error habitual
Cambiar .env después de iniciar el proceso no garantiza recarga. Reinicia y no registres os.environ completo en los logs.
05 / PRACTICAR
Tu turno
Define DB_PORT en .env y un valor distinto en PowerShell. ¿Cuál gana?
Ver solución orientativa
Con override=False gana la variable ya exportada por la terminal. Elimina esa variable de la sesión para volver al valor del archivo.
06 / VERIFICAR
Cómo sabes que funciona
- El cargador precede a la lectura de valores.
- False se interpreta como falso y falta de SECRET_KEY en PROD detiene el arranque.
Para profundizar
Documentación oficial para comprobar configuración, permisos y condiciones vigentes. Revisión del tema: 11 de octubre de 2026.
CONTINUAR LA EXPERIENCIA
El siguiente paso del recorrido:
Sesión, CSRF y middleware →Continuar en modo relato