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_maxbytesandstdout_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.
Source link
lol
