Supervisor Guide for PHP Developers

Supervisor is a powerful process control system widely used to manage background processes. As a PHP developer, you often need to handle long-running processes, queue workers, and other background tasks. Supervisor simplifies this by keeping processes running, restarting them if they fail, and providing easy monitoring and management. This post will explain how to set up Supervisor, use it for PHP applications, and configure it with all available options for maximum efficiency. What is Supervisor? Supervisor is a process control system that manages background tasks by: Automatically restarting failed processes. Providing unified logging. Enabling process control via CLI or a web interface. It is especially useful for PHP applications that use: Laravel queues for background tasks. Long-running scripts like WebSocket servers. Cron-like scheduled tasks. Installing Supervisor On Ubuntu/Debian sudo apt update sudo apt install supervisor On CentOS/RedHat sudo yum install epel-release sudo yum install supervisor After installation, start and enable Supervisor: sudo systemctl start supervisord sudo systemctl enable supervisord Supervisor Basics Supervisor uses configuration files, typically located in /etc/supervisor/conf.d/, to manage individual programs. Basic Configuration Example Here’s a simple configuration to manage a PHP worker. Create a file at /etc/supervisor/conf.d/my_php_worker.conf with the following contents: [program:my_php_worker] command=php /path/to/worker.php autostart=true autorestart=true stderr_logfile=/var/log/my_php_worker.err.log stdout_logfile=/var/log/my_php_worker.out.log The --tries=3 option in a command specifies that the process should attempt to execute a task up to 3 times before considering it failed. To apply the configuration: sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start my_php_worker:* General Configuration Options Here’s a comprehensive list of Supervisor options with examples: 1. command: Specifies the command to execute. Example: command=php /path/to/worker.php 2. autostart: Automatically starts the program when Supervisor starts. Values: true (default), false Example: autostart=true 3. autorestart: Determines whether to restart the program automatically. Values: true, false, unexpected Example: autorestart=unexpected 4. startsecs: Time (in seconds) a process must stay running to be considered "started." Default: 1 Example: startsecs=5 5. startretries: Number of restart attempts before marking the process as failed. Default: 3 Example: startretries=5 6. exitcodes: List of acceptable exit codes that do not trigger a restart. Default: 0,2 Example: exitcodes=0,1 7. stopwaitsecs: Time (in seconds) to wait after sending a stop signal before forcefully killing the process. Default: 10 Example: stopwaitsecs=20 8. redirect_stderr: Redirects stderr output to the same file as stdout. Values: true, false (default) Example: redirect_stderr=true 9. stdout_logfile / stderr_logfile: File paths for logging output and errors. Example: stdout_logfile=/var/log/my_program.out.log stderr_logfile=/var/log/my_program.err.log 10. stdout_logfile_maxbytes / stderr_logfile_maxbytes: Maximum size of log files before rotation. Default: 50MB Example: stdout_logfile_maxbytes=10MB stderr_logfile_maxbytes=5MB 11. stdout_logfile_backups / stderr_logfile_backups: Number of rotated log files to keep. Default: 10 Example: stdout_logfile_backups=3 stderr_logfile_backups=3 12. user: System user to run the program as. Example: user=www-data 13. environment: Defines environment variables for the program. Example: environment=APP_ENV="production",DB_HOST="localhost" 14. priority: Controls the order in which programs are started. Lower values start first. Default: 999 Example: priority=100 15. directory: Specifies the working directory for the program. Example: directory=/path/to/your/app 16. stopasgroup: Sends the stop signal to the program and its child processes. Values: true, false (default) Example: stopasgroup=true 17. killasgroup: Sends the kill signal to the program and its child processes if they don’t stop after stopwaitsecs. Values: true, false (default) Example: killasgroup=true Use Cases for PHP Developers 1. Managing Laravel Queues Laravel’s queue:work command processes queued jobs. Supervisor ensures these workers keep running. Configuration Example: [program:laravel_queue_worker] command=php /path/to/artisan queue:work --tries=3 autostart=true autorestart=true user=www-data stderr_logfile=/var/log/laravel_queue_worker.err.log stdout_logfile=/var/log/laravel_queue_worker.out.log 2. Running Scheduled Tasks For scripts that run at intervals, Supervi

Jan 20, 2025 - 05:06

Supervisor is a powerful process control system widely used to manage background processes. As a PHP developer, you often need to handle long-running processes, queue workers, and other background tasks. Supervisor simplifies this by keeping processes running, restarting them if they fail, and providing easy monitoring and management.

This post will explain how to set up Supervisor, use it for PHP applications, and configure it with all available options for maximum efficiency.

What is Supervisor?

Supervisor is a process control system that manages background tasks by:

Automatically restarting failed processes.
Providing unified logging.
Enabling process control via CLI or a web interface.

It is especially useful for PHP applications that use:

Laravel queues for background tasks.
Long-running scripts like WebSocket servers.
Cron-like scheduled tasks.

Installing Supervisor

On Ubuntu/Debian

sudo apt update
sudo apt install supervisor

On CentOS/RedHat

sudo yum install epel-release
sudo yum install supervisor

After installation, start and enable Supervisor:

sudo systemctl start supervisord
sudo systemctl enable supervisord

Supervisor Basics

Supervisor uses configuration files, typically located in /etc/supervisor/conf.d/, to manage individual programs.

Basic Configuration Example

Here’s a simple configuration to manage a PHP worker. Create a file at /etc/supervisor/conf.d/my_php_worker.conf with the following contents:

[program:my_php_worker]
command=php /path/to/worker.php
autostart=true
autorestart=true
stderr_logfile=/var/log/my_php_worker.err.log
stdout_logfile=/var/log/my_php_worker.out.log

The --tries=3 option in a command specifies that the process should attempt to execute a task up to 3 times before considering it failed.

To apply the configuration:

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start my_php_worker:*

General Configuration Options

Here’s a comprehensive list of Supervisor options with examples:

1. command: Specifies the command to execute.
Example:

command=php /path/to/worker.php

2. autostart: Automatically starts the program when Supervisor starts.
Values: true (default), false
Example:

autostart=true

3. autorestart: Determines whether to restart the program automatically.
Values: true, false, unexpected
Example:

autorestart=unexpected

4. startsecs: Time (in seconds) a process must stay running to be considered "started."
Default: 1
Example:

startsecs=5

5. startretries: Number of restart attempts before marking the process as failed.
Default: 3
Example:

startretries=5

6. exitcodes: List of acceptable exit codes that do not trigger a restart.
Default: 0,2
Example:

exitcodes=0,1

7. stopwaitsecs: Time (in seconds) to wait after sending a stop signal before forcefully killing the process.
Default: 10
Example:

stopwaitsecs=20

8. redirect_stderr: Redirects stderr output to the same file as stdout.
Values: true, false (default)
Example:

redirect_stderr=true

9. stdout_logfile / stderr_logfile: File paths for logging output and errors.
Example:

stdout_logfile=/var/log/my_program.out.log
stderr_logfile=/var/log/my_program.err.log

10. stdout_logfile_maxbytes / stderr_logfile_maxbytes: Maximum size of log files before rotation.
Default: 50MB
Example:

stdout_logfile_maxbytes=10MB
stderr_logfile_maxbytes=5MB

11. stdout_logfile_backups / stderr_logfile_backups: Number of rotated log files to keep.
Default: 10
Example:

stdout_logfile_backups=3
stderr_logfile_backups=3

12. user: System user to run the program as.
Example:

user=www-data

13. environment: Defines environment variables for the program.
Example:

environment=APP_ENV="production",DB_HOST="localhost"

14. priority: Controls the order in which programs are started. Lower values start first.
Default: 999
Example:

priority=100

15. directory: Specifies the working directory for the program.
Example:

directory=/path/to/your/app

16. stopasgroup: Sends the stop signal to the program and its child processes.
Values: true, false (default)
Example:

stopasgroup=true

17. killasgroup: Sends the kill signal to the program and its child processes if they don’t stop after stopwaitsecs.
Values: true, false (default)
Example:

killasgroup=true

Use Cases for PHP Developers

1. Managing Laravel Queues

Laravel’s queue:work command processes queued jobs. Supervisor ensures these workers keep running.

Configuration Example:

[program:laravel_queue_worker]
command=php /path/to/artisan queue:work --tries=3
autostart=true
autorestart=true
user=www-data
stderr_logfile=/var/log/laravel_queue_worker.err.log
stdout_logfile=/var/log/laravel_queue_worker.out.log

2. Running Scheduled Tasks

For scripts that run at intervals, Supervisor is more reliable than cron.

Configuration Example:

[program:send_reminders]
command=php /path/to/send_reminders.php
autostart=true
autorestart=true
stderr_logfile=/var/log/send_reminders.err.log
stdout_logfile=/var/log/send_reminders.out.log

3. Long-Running Scripts

Use Supervisor to manage WebSocket servers or other persistent scripts.

Configuration Example:

[program:websocket_server]
command=php /path/to/websocket_server.php
autostart=true
autorestart=true
stderr_logfile=/var/log/websocket_server.err.log
stdout_logfile=/var/log/websocket_server.out.log

Enable Supervisor to Start on System Boot

To ensure that Supervisor automatically starts when the system boots, follow these steps:

1. Enable the Supervisor service to start on boot:

sudo systemctl enable supervisord

2. Start the Supervisor service (if not already running):

sudo systemctl start supervisord

Best Practices

Use descriptive program names.
Set up log rotation with stdout_logfile_maxbytes and stdout_logfile_backups.
Use environment to pass variables.

Conclusion

Supervisor is a must-have for PHP developers managing background tasks. This guide covers installation, configuration, and practical use cases to get started. Whether you're running Laravel queue workers, scheduled tasks, or long-running processes, Supervisor ensures reliability and simplicity.