Container fails to start: docker-entrypoint.sh not found in $PATH (alpine images)

[FALLCWB]

Description

When building and running the NATS Docker image (notably the 2.12.x/alpine3.22 variant), the container may fail to start with the following error:

exec: "docker-entrypoint.sh": executable file not found in $PATH

This happens during docker run, even though docker-entrypoint.sh is present in the image.

Root cause

The Dockerfile relies on resolving docker-entrypoint.sh via $PATH, but this is fragile and can break depending on:

• the base image variant (e.g. alpine / minimal images),
• whether /usr/local/bin exists as a directory at build time,
• how the file is copied (directory vs full path),
• or missing executable permissions.

For example, using:

COPY docker-entrypoint.sh /usr/local/bin
ENTRYPOINT ["docker-entrypoint.sh"]

can result in the script not being found at runtime if the PATH does not resolve it, or if the file is not installed at the expected location.

Proposed solution

Install the entrypoint script at a predictable absolute path, ensure it is executable, and reference it explicitly:

COPY --chmod=755 docker-entrypoint.sh /usr/local/bin/docker-entrypoint.sh
ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]

This avoids PATH-dependent behavior and ensures consistent container startup across base image variants.

Why this matters

This change improves robustness and prevents runtime failures that are otherwise hard to diagnose, especially for users building custom images or rebasing on newer Alpine or minimal base images. It also helps avoid confusion for users with limited Docker experience and reduces the likelihood of unnecessary issues being opened.