Analysis and Solutions for RUN mkdir Failure in Dockerfile

Problem Phenomenon and Error Analysis

During Docker image construction, developers frequently encounter situations where the RUN mkdir command fails to execute. A typical error message appears as follows:

Step 18 : RUN mkdir /var/www/app && chown luqo33:www-data /var/www/app
---> Running in 7b5854406120
mkdir: cannot create directory '/var/www/app': No such file or directory

This error message appears contradictory—since the goal is to create a directory, it naturally shouldn't exist. However, the essence of the problem lies in the default behavior characteristics of the mkdir command.

Root Cause Analysis

The mkdir command in Unix/Linux systems defaults to non-recursive creation mode. This means that when creating multi-level directory paths, it is essential to ensure that parent directories already exist. In the provided example, although the target is to create /var/www/app, the /var/www directory itself does not exist in the base Ubuntu image, thus directly creating the subdirectory app will inevitably fail.

This design stems from security considerations in filesystem operations. The non-recursive mode prevents accidental creation of numerous unnecessary directory structures while ensuring developers are explicitly aware of each directory's creation intent.

Solution Implementation

The most direct method to resolve this issue is to use the -p parameter with the mkdir command, which enables recursive creation functionality:

RUN mkdir -p /var/www/app && chown luqo33:www-data /var/www/app

The function of the -p parameter is: if any parent directories in the directory path do not exist, the system will automatically create these missing parent directories. This approach ensures the completeness and reliability of directory creation.

Another solution involves installing necessary software packages in the early stages of the Dockerfile, which may automatically create the required directory structures. For instance, installing web server packages typically creates standard directories under the /var/www path.

Collaborative Work of Related Instructions

In the case provided by the reference article, the execution of the WORKDIR /usr/app instruction also encountered similar issues. When the directory specified by WORKDIR does not exist, Docker automatically creates this directory during the build process. However, if subsequent operations attempt file operations while this directory is non-existent, errors may still occur.

The correct approach is to ensure the directory structure is established when needed:

FROM ubuntu:14.04
RUN groupadd -r luqo33 && useradd -r -g luqo33 luqo33

# Install necessary software packages
RUN apt-get update && apt-get install -y nginx php-fpm

# Create directories using recursive method
RUN mkdir -p /var/www/app && chown luqo33:www-data /var/www/app
VOLUME /var/www/app
WORKDIR /var/www/app

Best Practice Recommendations

During Dockerfile writing, it is recommended to follow these best practices:

Always use mkdir -p to create directory paths, unless you are certain that all parent directories already exist. This approach provides better compatibility and reliability.

Establish complete directory structures in the early stages of the Dockerfile to avoid build failures caused by missing directories in subsequent steps.

When combining with the WORKDIR instruction, ensure that the specified working directory either exists or can be correctly created.

By understanding the working principles of the mkdir command and the characteristics of the Docker build process, developers can effectively avoid such common build errors and improve development efficiency.