Dockerfile Instructions: USER, WORKDIR, and ONBUILD

are strongly encouraged to use `VOLUME` for any combination of mutable or user-serviceable parts of your image. For more information about `VOLUME`, see [Dockerfile reference for the VOLUME instruction](/reference/dockerfile.md#volume). ### USER If a service can run without privileges, use `USER` to change to a non-root user. Start by creating the user and group in the Dockerfile with something like the following example: ```dockerfile RUN groupadd -r postgres && useradd --no-log-init -r -g postgres postgres ``` > [!NOTE] > > Consider an explicit UID/GID. > > Users and groups in an image are assigned a non-deterministic UID/GID in that > the "next" UID/GID is assigned regardless of image rebuilds. So, if it’s > critical, you should assign an explicit UID/GID. > [!NOTE] > > Due to an [unresolved bug](https://github.com/golang/go/issues/13548) in the > Go archive/tar package's handling of sparse files, attempting to create a user > with a significantly large UID inside a Docker container can lead to disk > exhaustion because `/var/log/faillog` in the container layer is filled with > NULL (\0) characters. A workaround is to pass the `--no-log-init` flag to > useradd. The Debian/Ubuntu `adduser` wrapper does not support this flag. Avoid installing or using `sudo` as it has unpredictable TTY and signal-forwarding behavior that can cause problems. If you absolutely need functionality similar to `sudo`, such as initializing the daemon as `root` but running it as non-`root`, consider using [“gosu”](https://github.com/tianon/gosu). Lastly, to reduce layers and complexity, avoid switching `USER` back and forth frequently. For more information about `USER`, see [Dockerfile reference for the USER instruction](/reference/dockerfile.md#user). ### WORKDIR For clarity and reliability, you should always use absolute paths for your `WORKDIR`. Also, you should use `WORKDIR` instead of proliferating instructions like `RUN cd … && do-something`, which are hard to read, troubleshoot, and maintain. For more information about `WORKDIR`, see [Dockerfile reference for the WORKDIR instruction](/reference/dockerfile.md#workdir). ### ONBUILD An `ONBUILD` command executes after the current Dockerfile build completes. `ONBUILD` executes in any child image derived `FROM` the current image. Think of the `ONBUILD` command as an instruction that the parent Dockerfile gives to the child Dockerfile. A Docker build executes `ONBUILD` commands before any command in a child Dockerfile. `ONBUILD` is useful for images that are going to be built `FROM` a given image. For example, you would use `ONBUILD` for a language stack image that builds arbitrary user software written in that language within the Dockerfile, as you can see in [Ruby’s `ONBUILD` variants](https://github.com/docker-library/ruby/blob/c43fef8a60cea31eb9e7d960a076d633cb62ba8d/2.4/jessie/onbuild/Dockerfile). Images built with `ONBUILD` should get a separate tag. For example, `ruby:1.9-onbuild` or `ruby:2.0-onbuild`. Be careful when putting `ADD` or `COPY` in `ONBUILD`. The onbuild image fails catastrophically if the new build's context is missing the resource being added. Adding a separate tag, as recommended above, helps mitigate this by allowing the Dockerfile author to make a choice. For more information about `ONBUILD`, see [Dockerfile reference for the ONBUILD instruction](/reference/dockerfile.md#onbuild).

This section discusses the Dockerfile instructions USER, WORKDIR, and ONBUILD. It covers using USER to switch to a non-root user, the importance of explicit UID/GID assignments, and a workaround for a Go archive/tar package bug that can cause disk exhaustion. It advises against using 'sudo' and suggests using 'gosu' instead. It emphasizes using absolute paths for WORKDIR and avoiding 'RUN cd'. Finally, it explains ONBUILD, which executes commands in child images derived from the current image, useful for language stack images. It advises caution when using ADD or COPY in ONBUILD and recommends separate tags for images built with ONBUILD.