How to Configure Supervisor in Docker Correctly
Many developers attempt to run Laravel Horizon inside a container by mounting the project code and invoking php artisan horizon via Supervisord. The goal is sound: you want the queue worker to start automatically when the container launches and restart if it crashes. However, the provided configuration fails because of two critical misunderstandings regarding how Docker manages processes and file systems.
The first issue lies in the Dockerfile. You explicitly copy the Supervisor configuration twice: once before adding your application code and again after. While this redundancy doesn't break things, it creates unnecessary confusion. More importantly, you define the final command as CMD ["php-fpm"], which immediately terminates the Supervisord process before it can initialize its internal state or create the socket files required for communication.
In Docker, a container is considered "running" as long as one process holds the PID 1 slot. If that process exits, the container stops. By switching to php-fpm in the CMD instruction without keeping Supervisord alive, you are effectively telling the system to drop the supervisor state management layer the moment the container starts.
To fix this, your entrypoint must explicitly invoke Supervisord. Update your Dockerfile's final command to:
CMD ["/usr/bin/supervisord", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
This ensures that when the container starts, Supervisord is the primary process managing your worker daemons.
The second, and more insidious, issue involves file permissions and volume mounts. In your docker-compose.yml, you mount the local supervisord.conf into the container at /etc/supervisor/conf.d/supervisord.conf. While this allows you to edit the config on the host without rebuilding the image, it introduces a race condition regarding user ownership.
Your Dockerfile creates a www group and user with UID 1000. Your application files are copied with these permissions (COPY --chown=www:www). However, the Supervisor socket file (/var/run/supervisor.sock) and logs must be writable by the process running Supervisord. If the host's supervisord.conf is owned by root or a different user, and your application volume is owned by www, the supervisor daemon might fail to write logs or manage processes correctly depending on how it was invoked initially.
A more robust approach for development environments is to bake the Supervisor configuration directly into the image rather than relying on host file mounts that might have conflicting ownership. You can simplify the Dockerfile by removing the second COPY instruction and ensuring the initial copy sets the correct permissions immediately:
# Install supervisor and other tools during build
RUN apt-get update && apt-get install -y supervisor ...
# Copy Supervisor config directly into the image context
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
# Ensure the directory is owned by www so logs can be written correctly
RUN chown -R www:www /var/log/supervisor /var/run/supervisor
# ... (rest of build steps)
CMD ["/usr/bin/supervisord", "-n", "-c", "/etc/supervisor/conf.d/supervisord.conf"]
Using the -n flag runs Supervisord in the foreground, which is crucial for Docker. Without this flag, or if Supervisord exits immediately, Docker reports that the container exited unexpectedly.
Regarding the error unix:///var/run/supervisord.sock no such file: this typically occurs when Supervisord cannot start its internal IPC server because it lacks permission to create the socket directory in /var/run. Ensure that your Supervisor configuration includes a [unix_http_server] section, as shown in your snippet, but verify that the directory /var/run/supervisor exists and is owned by the www user. You can force this during the build phase:
RUN mkdir -p /var/run/supervisor && chown www:www /var/run/supervisor
Finally, ensure your Supervisor configuration explicitly defines the worker process with the correct working directory. In your [program:ohwo-worker] section, make sure directory=/var/www is set if cwd is not inherited correctly, ensuring Horizon looks for its configuration files in the right place.
By aligning the entrypoint to keep Supervisord alive as PID 1 and hardening file ownership within the image context, your queue worker will start reliably alongside your web server and database services.
