Docker Execution Nightmare: Solving the /usr/bin/supervisord: not found Error

As senior developers working with containerized applications, we often run into frustrating issues when trying to orchestrate complex processes within Docker. The specific error you are encountering—/usr/local/bin/docker-php-entrypoint: exec: line 9: /usr/bin/supervisord: not found—is a classic symptom of path resolution problems or an incorrect execution flow within a custom entrypoint script.

This post will dissect why this error occurs in your setup and provide the definitive solution to ensure your Docker containers execute exactly as intended, allowing you to build robust services, much like the architecture promoted by the Laravel ecosystem on https://laravelcompany.com.

---

Diagnosing the Execution Failure

The core problem lies in a mismatch between what your container environment expects and what is actually present when the ENTRYPOINT command executes.

Let’s look at your setup: you are using a base image (php:7-cli-alpine), installing Supervisor via apk, defining a configuration file, and setting an ENTRYPOINT.

The Root Cause Analysis

1. Layering and Installation: When you run RUN apk add supervisor, the executable is placed in the standard Alpine binary path (e.g., /usr/bin/supervisord).
2. The Entrypoint Conflict: Your ENTRYPOINT is explicitly set to:

   ENTRYPOINT ["/usr/bin/php", "/var/www/html/websocket-service/artisan", "websockets:serve"]
   

   This command tells Docker to execute the PHP binary directly, passing the Artisan command as arguments. It completely bypasses any external process manager (like Supervisor) that might have been intended to manage this service.
3. The Miscommunication: The error message suggests that somewhere in the execution chain—likely within a custom shell script or an entrypoint wrapper you are implicitly using—the system attempts to call /usr/bin/supervisord to manage the process, but it fails because either:
   • The path reference is incorrect.
   • The actual mechanism running the entrypoint does not correctly inherit the environment where apk placed the file into the execution context.

In essence, your application logic (running Artisan) is being executed directly by PHP, while the system configuration (Supervisor) is failing to load because it cannot find the required executable path when invoked indirectly.

The Solution: Aligning Entrypoint with Intent

Since your goal is clearly to run the specific Artisan command (php artisan ...), you should simplify the entrypoint and ensure that if process management is needed, it is explicitly handled by the primary command. If you are running a single long-running PHP process via artisan, you do not necessarily need Supervisor running inside the container unless you intend to manage multiple services concurrently.

Option 1: Running the Command Directly (Recommended for this setup)

If the goal is just to start the WebSocket service, remove any dependency on Supervisor in the entrypoint and let the direct command execute. This eliminates the conflict entirely.

Revised Dockerfile:

FROM php:7-cli-alpine

# Install supervisor if you still need it for other purposes, 
# but we will change the ENTRYPOINT to reflect the actual execution.
RUN apk --update add supervisor

RUN rm /var/cache/apk/* && \
    mkdir -p /var/www

COPY websockets.conf /etc/supervisor/supervisord.conf

# Change ENTRYPOINT to directly execute the desired command
ENTRYPOINT ["/usr/bin/php", "/var/www/html/websocket-service/artisan", "websockets:serve"]

Revised docker-compose.yml (If Supervisor is not needed for this service):

If you are running only one service, remove the reference to it from the service definition entirely, as it is now handled by the entrypoint command itself:

version: '2'

services:
   websockets:
    build:
      context: ./
      dockerfile: websocket.dockerfile
    volumes:
      - ./:/var/www/html
    ports:
      - 6001:6001
    # Remove command or restart policies if running directly via ENTRYPOINT

Option 2: Correctly Using Supervisor (If Process Management is Required)

If you must use Supervisor to manage this service (perhaps because it manages other related processes), your entrypoint must explicitly call the supervisor executable. This requires ensuring that the path where apk installs binaries is correctly referenced, often by using the full path or relying on standard system paths accessible via $PATH.

Revised Dockerfile (If running Supervisor as the main process):

FROM php:7-cli-alpine

RUN apk --update add supervisor

RUN rm /var/cache/apk/* && \
    mkdir -p /var/www

COPY websockets.conf /etc/supervisor/supervisord.conf

# Use supervisor as the main entrypoint, letting it read the config file
ENTRYPOINT ["/usr/bin/supervisord", "-c", "/etc/supervisor/supervisord.conf"]

In this scenario, you would then ensure your websockets.conf defines the program to run (which should point to /usr/bin/php ...), and Supervisor will correctly manage the execution flow without throwing a "not found" error, as it is explicitly invoking the executable it expects within its defined configuration context.

Conclusion

The Docker error you faced was a path collision resulting from an entrypoint that attempted to execute a process manager (supervisord) which was not the primary command being executed by the container. By aligning your ENTRYPOINT with the actual desired execution—either running the PHP Artisan command directly or explicitly calling Supervisor—you resolve the execution conflict. Always remember to carefully define what your container is supposed to do, ensuring that configuration files and execution commands are perfectly synchronized within your Dockerfile and Compose configuration.