Complete Guide to Overriding Entrypoint with Arguments in Docker Run

Overview of Docker Entrypoint Mechanism

In Docker container technology, entrypoint is a crucial configuration that defines the default command executed when a container starts. Unlike the CMD instruction, the command specified by entrypoint always executes at container runtime, while CMD provides default arguments for the entrypoint. This design makes container images more flexible, allowing them to run directly or change behavior by passing arguments.

Analysis of Common Error Cases

Many developers encounter errors similar to the following when attempting to override entrypoint and pass arguments via the docker run command:

docker: Error response from daemon: 
invalid header field value "oci runtime error: container_linux.go:247: 
starting container process caused \"exec:
\"/usr/local/tomcat/entrypoint.sh -a param1 -b param2\": 
stat /usr/local/tomcat/entrypoint.sh -a param1 -b param2: 
no such file or directory\"\n".

The core issue is that Docker treats the entire quoted content "/usr/local/tomcat/entrypoint.sh -a param1 -b param2" as a single executable file path. Before running the container, Docker checks if this file exists, but since the path contains spaces and arguments, the system cannot find the corresponding file, causing the error.

Correct Argument Passing Method

According to Docker official documentation design, the --entrypoint parameter should only specify the script or command to execute, while all arguments should be passed after the image name. The correct syntax format is:

docker run --entrypoint <entrypoint.sh> <image:tag> <arg1> <arg2> <arg3>

For the specific Tomcat example, the correct command should be:

docker run --entrypoint /usr/local/tomcat/entrypoint.sh tomcat:jre8 -a param1 -b param2

This format ensures Docker correctly identifies the entrypoint script and passes subsequent arguments to it for execution.

Importance of Argument Position

In practical usage, the position of the --entrypoint parameter is crucial. When the docker run command contains multiple parameters, --entrypoint should be placed before all other arguments. For example, if the command includes container name, port mapping, environment variables, and other configurations, the correct order should be:

docker run --entrypoint /bin/bash \
  --rm \
  --name mycontainer \
  -it \
  -v /host/path:/container/path \
  -p 8080:80 \
  -e ENV_VAR=value \
  myimage:tag \
  additional_args

Placing --entrypoint after other arguments may cause Docker to ignore the override and still execute the original entrypoint defined in the Dockerfile.

Comparison with Docker Compose

In docker-compose.yml files, the configuration method for entrypoint differs:

entrypoint: /usr/local/tomcat/entrypoint.sh -a param1 -b param2

This syntax is valid in docker-compose because docker-compose can correctly distinguish between commands and arguments when parsing configuration files. However, in the docker run command line, due to differences in shell parsing and Docker parameter processing, a different syntax structure must be used.

Practical Application Examples

Assuming we have an entrypoint script that processes configuration files and needs to receive two parameters: configuration type and configuration file path. The correct Docker run command should be:

docker run --entrypoint /app/config-processor.sh \
  myapp:latest \
  --type production \
  --config /app/config/prod.yaml

If preprocessing is needed before script execution, a wrapper script can be created:

#!/bin/bash
# wrapper.sh
echo "Starting container with parameters: $@"
exec /app/main-script.sh "$@"

Then use:

docker run --entrypoint /app/wrapper.sh myapp:latest arg1 arg2

Best Practice Recommendations

1. Keep entrypoint scripts concise, decomposing complex logic into multiple scripts or functions.

2. Set correct execution permissions for entrypoint scripts in Dockerfile: RUN chmod +x /path/to/entrypoint.sh.

3. Use the exec form to call the final command, ensuring proper signal handling and process management.

4. Add appropriate error handling and logging to entrypoint scripts.

5. Test different argument combinations in development environments to ensure proper functioning in various scenarios.

Debugging Techniques

When entrypoint configuration issues arise, the following methods can be used for debugging:

1. Use --entrypoint /bin/bash to enter container interactive mode and manually test script execution.

2. Add debug information output at the beginning of entrypoint scripts, such as echo "Parameters received: $@".

3. Check Docker daemon logs for more detailed error information.

4. Use the docker inspect command to view actual container configuration.

Conclusion

Correctly understanding Docker entrypoint mechanisms is crucial for deploying containerized applications. By following the principle that --entrypoint only specifies the executable file and arguments are passed after the image name, common configuration errors can be avoided. Additionally, paying attention to argument position and order ensures proper override of default entrypoints in various complex scenarios. These practices not only improve container flexibility but also enhance application maintainability and portability.