Deep Analysis and Solutions for docker-entrypoint.sh Permission Issues in Docker Compose

Problem Background and Error Analysis

When deploying applications with Docker Compose, developers often encounter container startup failures, with one common error being "exec: \"./docker-entrypoint.sh\": permission denied". This error indicates that the Docker container encountered a permission issue while attempting to execute the entrypoint script. From the provided error log, it's clear that the container process failed to start specifically because permission was denied when executing ./docker-entrypoint.sh.

Root Cause Investigation

The permission denied error typically stems from two core issues: insufficient file execution permissions and improper entrypoint configuration. In Unix-like systems, script files must have execution permissions (x permission) to be directly executed. When a Docker container attempts to run docker-entrypoint.sh, if the file lacks execution permissions, it triggers the permission denied error.

Another critical issue is the configuration location of the entrypoint. While specifying entrypoint: ./docker-entrypoint.sh directly in docker-compose.yml is possible, this actually overrides the default entrypoint defined in the Dockerfile. According to Docker's official documentation, entrypoint in docker-compose.yml is an override setting, and best practice is to define the default entrypoint in the Dockerfile.

Solution Implementation

Based on the best answer guidance, the correct solution requires modifying both the Dockerfile and docker-compose.yml files. First, add the following content to the end of the Dockerfile:

COPY ./docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh
ENTRYPOINT ["/docker-entrypoint.sh"]

This code accomplishes three key operations: copying docker-entrypoint.sh to the root directory inside the container, using the chmod +x command to grant execution permissions, and finally setting it as the container's default entrypoint via the ENTRYPOINT instruction.

Simultaneously, the entrypoint: ./docker-entrypoint.sh line needs to be removed from docker-compose.yml to avoid configuration conflicts. The modified docker-compose.yml should appear as follows:

version: '3'

services:
  db:
    image: postgres
    ports:
      - "5432:5432"
  web:
    build: .
    env_file: .env
    volumes:
      - .:/code
    ports:
      - "8000:8000"
    depends_on:
      - db

Additional Considerations

Other answers provide valuable supplementary information. In certain cases, particularly when using lightweight base images like Alpine Linux, shell environment differences may arise. If docker-entrypoint.sh uses #!/bin/bash as its shebang but the base image doesn't include bash, execution will fail. In such situations, the shebang should be changed to #!/bin/sh, as sh is available in most Unix-like systems.

File paths are another detail requiring attention. If the Dockerfile, docker-compose.yml, and entrypoint script aren't in the same directory, relative paths must be correctly specified in the COPY instruction. For example, if all files are in a docker directory with the build context in the parent directory, a path configuration like COPY docker/entrypoint.sh /entrypoint.sh can be used.

Best Practices Summary

To avoid similar permission issues, it's recommended to follow these best practices: always set entrypoints and execution permissions in the Dockerfile; use absolute paths rather than relative paths when specifying entrypoint scripts; ensure scripts have appropriate shebang lines; avoid unnecessary entrypoint overrides in docker-compose.yml; and verify script file permissions before building.

By systematically analyzing problem roots and implementing correct solutions, developers can avoid common Docker permission issues, ensuring smooth deployment and operation of containerized applications. This approach not only resolves current problems but also establishes a solid foundation for more complex Docker configurations.