Deep Analysis and Solutions for Docker Entrypoint Script Permission Issues

Problem Background and Error Analysis

When containerizing Node.js applications with Docker, developers frequently encounter issues with Entrypoint script execution. The typical error message shows docker: Error response from daemon: oci runtime error: exec: "/usr/src/app/docker-entrypoint.sh": permission denied.. This error indicates that the Docker runtime cannot execute the specified Entrypoint script, with the core issue being improper filesystem permission configuration.

Root Causes of Permission Issues

When Docker attempts to execute an Entrypoint script, the operating system checks the file's execution permissions. From the problem description, the script file permissions are -rw-r--r-- 1 root root, indicating that neither the file owner, group users, nor other users have execution permissions. In Unix-like systems, files must have execution permissions to be directly executed.

Permission issues primarily stem from two sources: first, the original script file on the host machine may lack execution permissions; second, during the Docker build process, if using the ADD instruction instead of COPY, or if permissions are not explicitly set, permission information may be lost.

Comparative Analysis of Solutions

Internal Permission Setting in Dockerfile

The most reliable solution is to explicitly set execution permissions during the Dockerfile build stage:

FROM ubuntu:14.04
# ... other installation instructions ...
ADD docker-entrypoint.sh /usr/src/app/
RUN chmod +x /usr/src/app/docker-entrypoint.sh
EXPOSE 8080
ENTRYPOINT ["/usr/src/app/docker-entrypoint.sh"]

This approach ensures that regardless of the file permissions on the host machine, execution permissions are correctly set during image construction. Using the exec form RUN ["chmod", "+x", "/usr/src/app/docker-entrypoint.sh"] avoids dependency on shell interpreters.

Permission Retention特性 of COPY Instruction

Modern Docker versions support the --chmod parameter for the COPY instruction, providing a more elegant solution:

COPY --chmod=755 docker-entrypoint.sh /usr/src/app/

This method sets permissions directly during file copying, avoiding additional RUN instructions and improving build efficiency. Note that this feature requires Docker BuildKit support, which is enabled by default in newer Docker versions.

Host Machine Permission Preprocessing

Another approach is to ensure the script file has execution permissions on the host machine before building the image:

chmod +x docker-entrypoint.sh

Then use the COPY instruction (rather than ADD) to retain permission information. This method relies on correct host environment configuration and may not be reliable in team collaboration or CI/CD environments.

Shebang Syntax Validation

While permission issues are the primary cause, shebang syntax correctness also requires verification. Entrypoint scripts should begin with the correct shebang:

#!/usr/bin/env bash

or

#!/bin/bash

Correct shebang ensures the script can be executed by the proper interpreter. If execution errors persist after resolving permission issues, verify that the interpreter pointed to by shebang is available in the container.

Alternative Approaches for Multi-command Entrypoints

For scenarios requiring multiple commands in Entrypoint, besides using shell scripts, consider the following alternatives:

Direct Use of Shell Commands

ENTRYPOINT ["sh", "-c", "git clone git@<repo>.git && git add remote upstream git@<upstream_repo>.git && /usr/bin/node server.js"]

This approach avoids using external script files but may reduce maintainability, especially when commands become complex.

Layered Build Strategy

For build-time operations like git clone, a better approach is to complete them during the Dockerfile build stage:

RUN git clone git@<repo>.git /usr/src/app
WORKDIR /usr/src/app
RUN git add remote upstream git@<upstream_repo>.git

This separates build-time operations from runtime operations, allowing Entrypoint to focus on application startup.

Impact of Docker BuildKit

Modern Docker versions default to using BuildKit as the build engine, which has significant implications for permission handling. BuildKit provides better caching mechanisms and more precise permission control. If permission settings don't take effect, check the Docker version and ensure BuildKit is enabled:

export DOCKER_BUILDKIT=1
docker build .

Best Practices Summary

Based on problem analysis and solution comparison, the following best practices are recommended:

1. Use COPY --chmod=755 in Dockerfile to directly set script permissions
2. Ensure Entrypoint scripts contain correct shebang statements
3. Place build-time operations (like git clone) in Dockerfile RUN instructions
4. Use exec form ENTRYPOINT to avoid shell interpreter issues
5. Standardize Docker versions and build configurations in team environments

By following these practices, Entrypoint script permission issues can be effectively avoided, ensuring reliable Docker container startup and operation.