En esta lección aprenderás instrucción USER Dockerfile, una pieza importante para que tus contenedores no ejecuten la aplicación como root salvo que sea estrictamente necesario.
USER cambia el usuario activo para las instrucciones siguientes y para el proceso principal del contenedor, por eso conviene entenderla antes de llevar imágenes a entornos reales.
👉 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.
Instrucción USER Dockerfile
Problema: muchas imágenes ejecutan comandos como root por defecto. Eso puede simplificar el build, pero aumenta el impacto si la aplicación tiene una vulnerabilidad.
Qué aporta Docker: USER permite cambiar a un usuario concreto dentro de la imagen para ejecutar RUN, CMD o ENTRYPOINT con menos privilegios.
| Situación | Recomendación |
|---|---|
| Durante el build | Crea usuario, grupo y permisos antes de cambiar a USER. |
| Aplicación final | Ejecuta el proceso con un usuario no root cuando sea posible. |
| Archivos copiados | Asegura ownership/permisos antes de arrancar la app. |
Sintaxis y alcance de USER
La sintaxis admite un nombre de usuario con grupo opcional o valores numéricos: USER app:app o USER 10001:10001. El cambio afecta a las instrucciones RUN que aparecen después y al usuario predeterminado de CMD y ENTRYPOINT durante la ejecución. No modifica los pasos anteriores ni se hereda automáticamente a otra etapa iniciada con FROM.
| Forma | Qué determina | Cuándo conviene |
|---|---|---|
| USER app:app | Usa el usuario y el grupo nombrados en la imagen. | Cuando la imagen contiene esas cuentas y quieres que el proceso se identifique con ellas. |
| USER 10001:10001 | Define UID y GID numéricos. | Cuando necesitas una identidad estable entre imágenes o sistemas. |
| docker run –user 10001:10001 | Sobrescribe el usuario predeterminado para una ejecución concreta. | Para probar o ejecutar la imagen con una identidad elegida por quien la despliega. |
Si omites el grupo y la cuenta no tiene un grupo principal configurado, Docker puede ejecutar el proceso con el grupo root. Especifica usuario y grupo de forma explícita cuando ese detalle afecte a los permisos.
Ejemplo práctico
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY . .
RUN addgroup -S app && adduser -S app -G app \
&& chown -R app:app /app
USER app
CMD ["node", "server.js"]docker build -t user-demo:1.0 .
docker run --rm user-demo:1.0 idEl ejemplo crea un usuario de aplicación, ajusta permisos sobre /app y cambia a USER app antes del CMD. Así el proceso principal no arranca como root.
Comprobar permisos y reducir riesgos
El comando id del ejemplo permite confirmar el UID y el grupo efectivos; comprueba que el UID no sea 0 cuando la aplicación deba ejecutarse como usuario sin privilegios. Después prueba que puede leer su configuración, escribir únicamente en las rutas necesarias y abrir el puerto previsto. Una imagen puede arrancar con USER correctamente y fallar igualmente si sus directorios tienen propietarios o permisos incompatibles.
Las instrucciones COPY crean archivos como root si no se especifica propietario. En imágenes con archivos de aplicación, COPY –chown permite asignar el usuario y grupo al copiarlos y puede evitar una operación recursiva posterior. Cambia a USER después de completar solo las tareas de construcción que de verdad necesiten privilegios.
USER reduce los privilegios del proceso, pero no convierte por sí solo el contenedor en una caja de seguridad: no vuelve de solo lectura el sistema de archivos ni elimina automáticamente todas las capacidades de Linux. Para endurecer la ejecución, combina el usuario sin root con permisos mínimos, capacidades necesarias y una política de escritura limitada.
Errores comunes
- Cambiar a USER antes de preparar permisos: después pueden fallar COPY, RUN o escrituras necesarias.
- Asumir que USER arregla toda la seguridad: reduce privilegios, pero no sustituye buenas prácticas de imagen, red y secretos.
- Usar nombres de usuario inexistentes: crea el usuario antes o usa UID/GID válidos.
- Dar permisos 777 para salir del paso: suele esconder problemas y abre demasiado acceso.
Advertencia: ejecutar como no root es una defensa importante, pero prueba que la aplicación puede leer, escribir y escuchar donde corresponde. Si necesita privilegios extra, documenta el motivo.
La instrucción USER Dockerfile queda bien aplicada cuando el contenedor arranca con los mínimos privilegios necesarios y los permisos están preparados de forma explícita.
En producción, este cambio debe ir acompañado de pruebas reales de lectura, escritura, puertos y comportamiento de la aplicación.
