Supervisord Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require acassan/supervisord-bundle
   

   Enable the bundle in config/bundles.php:

   return [
       // ...
       Acassan\SupervisordBundle\SupervisordBundle::class => ['all' => true],
   ];
   

2. Configuration Publish the default config:

   php artisan vendor:publish --tag=supervisord-bundle-config
   

   Edit config/supervisord.php to define:

   • supervisord_path: Path to your supervisord executable (e.g., /usr/bin/supervisord).
   • config_path: Path to your supervisord config file (e.g., config/supervisor.conf).
   • log_path: Directory for supervisord logs (e.g., var/log/supervisord).

3. First Use Case: Start/Stop Supervisord Run supervisord via Artisan:

   php artisan supervisord:start
   php artisan supervisord:stop
   php artisan supervisord:restart
   

Implementation Patterns

Workflows

1. Dynamic Process Management Use the supervisord:add command to dynamically add processes to supervisord:

   php artisan supervisord:add "my_worker:app" --command="php artisan queue:work" --user="www-data"
   

   • Flags: --command: The command to run. --user: User to run the process as. --autostart: Auto-start on supervisord launch. --autorestart: Auto-restart on failure.

2. Process Monitoring Check process statuses:

   php artisan supervisord:status
   

   Outputs a table of running/stopped processes with PIDs.

3. Configuration-Driven Deployment Store supervisord configs in config/supervisor.conf (or a custom path) and reference them in your Laravel deployment scripts:

   # In deploy.php (Deployer)
   run('php artisan supervisord:update');
   run('php artisan supervisord:restart');
   

4. Event-Driven Integration Listen for supervisord events (e.g., process failures) by extending the bundle or using Laravel’s event system. Example:

   // In EventServiceProvider
   protected $listen = [
       'supervisord.process.failed' => [SupervisorFailureHandler::class, 'handle'],
   ];
   

Integration Tips

• Docker/Containerized Environments: Mount the supervisord config volume and use supervisord:start in your entrypoint.sh:

  CMD ["php", "artisan", "supervisord:start"]
  

• CI/CD Pipelines: Add supervisord commands to your pipeline to ensure background workers start after deployment:

  # GitHub Actions
  - name: Restart Supervisord
    run: php artisan supervisord:restart
  

• Custom Commands: Extend the bundle by creating custom Artisan commands that interact with supervisord:

  // app/Console/Commands/ScaleWorkers.php
  public function handle() {
      $this->call('supervisord:scale', [
          'process' => 'my_worker',
          'count' => 3,
      ]);
  }
  

Gotchas and Tips

Pitfalls

1. Permissions Issues

   • Supervisord may fail to start if the config file or log directory lacks write permissions.
   • Fix: Ensure the Laravel storage/log directories are writable by the supervisord user:

     chown -R www-data:www-data var/log
     

2. Config File Overrides

   • The bundle assumes a default config path. If you customize config_path, ensure the file exists and is valid YAML/INI.
   • Fix: Validate the config file manually before running commands:

     supervisord -c /path/to/your/config.conf -d
     

3. Process Naming Conflicts

   • Duplicate process names in supervisord will cause errors.
   • Fix: Use unique names (e.g., app_worker_1, app_worker_2) or prefix with a namespace.

4. Signal Handling

   • Supervisord may not respond to supervisord:stop if processes are stuck. Use supervisord:kill as a fallback:

     php artisan supervisord:kill
     

Debugging

• Check Supervisord Logs:

  tail -f var/log/supervisord.log
  

• Dry Run: Use --dry-run with commands to preview changes:

  php artisan supervisord:add --dry-run "test_process"
  

• Supervisord Direct CLI: Fall back to the native supervisord CLI for complex debugging:

  supervisord -c config/supervisor.conf -i
  

Extension Points

1. Custom Process Templates Override the default process template in config/supervisord.php:

   'process_template' => '[program:{name}]
   command={command}
   autostart={autostart}
   autorestart={autorestart}
   user={user}
   stderr_logfile=/var/log/supervisord/{name}-err.log
   stdout_logfile=/var/log/supervisord/{name}-out.log
   ',
   

2. Event Listeners Extend the bundle to trigger Laravel events on supervisord actions. Example:

   // In SupervisordBundle
   public function addProcess($name, $command) {
       // ... existing logic ...
       event(new ProcessAdded($name, $command));
   }
   

3. Database-Backed Config Store supervisord processes in a database table (e.g., supervisord_processes) and sync them dynamically:

   // In a custom command
   $processes = DB::table('supervisord_processes')->get();
   foreach ($processes as $process) {
       $this->call('supervisord:add', [
           'name' => $process->name,
           'command' => $process->command,
           '--user' => $process->user,
       ]);
   }
   

4. Environment Awareness Use Laravel’s environment files to conditionally enable/disable supervisord:

   // In config/supervisord.php
   'enabled' => env('SUPERVISORD_ENABLED', false),
   

   Then guard commands in AppServiceProvider:

   if (!config('supervisord.enabled')) {
       Artisan::disableCommands(['supervisord:*']);
   }