La instrucción ENV de Dockerfile define variables de entorno que quedan configuradas en la imagen y están disponibles para los procesos de los contenedores que se creen a partir de ella. Sirve para establecer valores predeterminados, como el modo de ejecución o un puerto, y permite que la aplicación los lea sin fijarlos directamente en el código.
👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.
🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.
Qué hace ENV en un Dockerfile
Al declarar una variable con ENV, Docker la incorpora a la configuración de la imagen. Los procesos iniciados en un contenedor reciben ese valor, salvo que se sobrescriba al ejecutar el contenedor. Además, las instrucciones posteriores del Dockerfile pueden utilizar variables que ya se hayan definido.
Por ejemplo, una aplicación puede consultar APP_ENV para saber si debe arrancar en producción o en pruebas, o leer PORT para conocer el puerto configurado. La instrucción no modifica por sí sola el comportamiento del programa: la aplicación debe estar preparada para leer esas variables.
Sintaxis de ENV en Dockerfile
La forma recomendada es escribir cada asignación como ENV nombre=valor. Puedes definir varias variables en una instrucción separándolas por espacios, aunque mantenerlas en líneas separadas suele facilitar los cambios y la revisión del Dockerfile.
FROM python:3.12-slim
ENV PYTHONDONTWRITEBYTECODE=1 \
PYTHONUNBUFFERED=1 \
APP_ENV=production \
PORT=8000
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "app.py"]En este ejemplo, las variables de Python configuran el comportamiento del intérprete y APP_ENV y PORT representan valores que podría consultar la aplicación. El puerto debe coincidir con el que realmente escucha el proceso; declarar la variable o usar EXPOSE no publica el puerto en el host.
Cuándo está disponible una variable ENV
Una variable queda disponible en las instrucciones que se procesan después de su declaración y en los contenedores derivados de la imagen. Por eso, el orden importa si una instrucción posterior usa una variable para definir una ruta u otro valor.
| Uso | Qué ocurre |
|---|---|
| Instrucciones posteriores del Dockerfile | Pueden expandir las variables ya declaradas cuando la instrucción admite esa expansión. |
| Contenedor creado desde la imagen | El proceso recibe las variables como parte de su entorno inicial. |
| Valor definido al arrancar | Una opción de ejecución, como -e, puede reemplazar el valor predeterminado de la imagen. |
| Secreto o contraseña | No lo guardes con ENV: el valor puede quedar expuesto en la configuración de la imagen o del contenedor. |
Cambiar el valor al iniciar el contenedor
El valor establecido en la imagen es un valor predeterminado, no una obligación. Puedes proporcionar otro valor al crear el contenedor. Así, la misma imagen puede ejecutarse en distintos entornos sin reconstruirla:
docker run --rm -e APP_ENV=staging -e PORT=9000 mi-aplicacionLa opción -e indica una variable para ese contenedor. En este caso, la aplicación recibirá APP_ENV con el valor staging y PORT con el valor 9000, siempre que su configuración lea esas variables.
ENV y ARG: para qué sirve cada una
ARG proporciona una variable durante la construcción de la imagen; no queda disponible automáticamente como variable de entorno al ejecutar el contenedor. ENV establece un valor que sí forma parte de la configuración de la imagen y llega al entorno del contenedor. Si conviertes un ARG en ENV, el valor resultante queda incorporado a la imagen.
No uses ninguna de las dos instrucciones para incluir contraseñas, tokens o claves privadas en una imagen. Para valores sensibles durante una construcción, utiliza los mecanismos de secretos de BuildKit. Para secretos de ejecución, usa un sistema de gestión de secretos apropiado para el entorno donde despliegas la aplicación.
Errores habituales al utilizar ENV
- Esperar que RUN export persista: un export ejecutado dentro de una instrucción RUN solo afecta a ese proceso y a sus procesos hijos; no sustituye a ENV para definir el entorno de la imagen.
- Confundir ENV con la publicación de puertos: definir PORT no publica un puerto. La publicación se configura al ejecutar el contenedor o en la herramienta de orquestación.
- Guardar datos secretos: ENV no es un almacén seguro; evita incluir credenciales en el Dockerfile o en la imagen.
- Suponer que la aplicación lee cualquier variable: el nombre debe coincidir con el que espera el programa y este debe consultar su entorno.
