Supervisor Bundle Laravel Package

Getting Started

Minimal Setup

1. Install the Bundle Add the package via Composer:

   composer require aboutcoders/supervisor-bundle
   

   Enable the bundle in config/bundles.php (Symfony) or AppKernel.php (legacy):

   Aboutcoders\SupervisorBundle\AbcSupervisorBundle::class => ['all' => true],
   

2. Configure Supervisor Publish the default config and adjust config/packages/aboutcoders_supervisor.yaml:

   php bin/console aboutcoders:supervisor:install
   

   Update supervisord.conf (typically in /etc/supervisor/conf.d/) to include your Laravel processes.

3. First Use Case: Start a Process Define a process in config/packages/aboutcoders_supervisor.yaml:

   processes:
       app.worker:
           command: 'php bin/console your:worker-command'
           numprocs: 1
           autostart: true
   

   Reload Supervisor:

   php bin/console aboutcoders:supervisor:reload
   

Implementation Patterns

Console Workflows

• Process Lifecycle Management Use these commands for day-to-day operations:

  # Start/stop/restart all processes
  php bin/console aboutcoders:supervisor:start
  php bin/console aboutcoders:supervisor:stop
  php bin/console aboutcoders:supervisor:restart
  
  # Target specific processes (e.g., 'app.worker')
  php bin/console aboutcoders:supervisor:start app.worker
  

• Monitoring Stream logs for a process:

  php bin/console aboutcoders:supervisor:tail app.worker
  

  List all processes:

  php bin/console aboutcoders:supervisor:status
  

REST-API Integration

• Expose Supervisor Actions via API The bundle provides a REST endpoint at /api/supervisor (configurable). Use it to:

  • Start/stop processes programmatically (e.g., from frontend or CI).
  • Example cURL request:

    curl -X POST http://your-app/api/supervisor/start -d '{"processes": ["app.worker"]}'
    

• Authentication Secure the API with Symfony’s security system (e.g., API tokens or OAuth). Example config:

  # config/packages/aboutcoders_supervisor.yaml
  api:
      enabled: true
      path: /api/supervisor
      security: true  # Enforces Symfony's security layer
  

Configuration Patterns

• Environment-Specific Processes Use Symfony’s environment variables or %kernel.environment% to define processes per environment:

  processes:
      app.worker.%env(DEFAULT=dev)%:
          command: 'php bin/console your:worker-command --env=%env(DEFAULT=dev)%'
  

• Dynamic Process Counts Scale processes based on environment variables:

  processes:
      app.worker:
          numprocs: '%env(int:WORKER_COUNT, 1)%'
  

Gotchas and Tips

Common Pitfalls

1. Supervisor Not Running

   • Ensure supervisord is installed and running (systemctl status supervisor).
   • Verify the config file path in aboutcoders_supervisor.yaml matches your Supervisor’s include directive (default: /etc/supervisor/conf.d/abc_supervisor.conf).

2. Permission Issues

   • The Symfony process (e.g., php bin/console) must have permissions to read/write Supervisor’s config and logs.
   • Fix with:

     sudo chown -R www-data:www-data /etc/supervisor/
     sudo chmod -R 755 /etc/supervisor/
     

3. Processes Not Starting

   • Check Supervisor logs:

     tail -f /var/log/supervisor/supervisord.log
     

   • Validate the command in supervisord.conf matches the exact CLI command (e.g., full path to PHP).

4. API CORS Issues

   • If using the REST-API, configure CORS in Symfony’s security:

     # config/packages/nelmio_cors.yaml
     paths:
         '^/api/supervisor':
             allow_origin: ['*']
             allow_methods: ['POST']
     

Debugging Tips

• Dry Run Config Use Supervisor’s built-in config validation:

  supervisorctl reread
  supervisorctl update
  supervisorctl status
  

• Log Levels Increase Supervisor’s log verbosity temporarily:

  ; In /etc/supervisor/supervisord.conf
  [supervisord]
  loglevel=debug
  

Extension Points

1. Custom Commands Extend the bundle by creating custom console commands that interact with Supervisor’s XML-RPC API. Example:

   use Aboutcoders\SupervisorBundle\Command\SupervisorCommand;
   use Symfony\Component\Console\Input\InputArgument;
   
   class CustomSupervisorCommand extends SupervisorCommand {
       protected function configure() {
           $this->setName('aboutcoders:supervisor:custom-action')
                ->addArgument('process', InputArgument::REQUIRED);
       }
   
       protected function execute(InputInterface $input, OutputInterface $output) {
           $process = $input->getArgument('process');
           $this->getSupervisorClient()->customAction($process); // Hypothetical method
       }
   }
   

2. Event Listeners Hook into Supervisor events (e.g., process start/stop) using Symfony’s event dispatcher. Example:

   use Aboutcoders\SupervisorBundle\Event\SupervisorEvent;
   
   class SupervisorListener {
       public function onProcessStart(SupervisorEvent $event) {
           if ($event->getProcessName() === 'app.worker') {
               // Log or trigger side effects
           }
       }
   }
   

   Register in services.yaml:

   services:
       App\EventListener\SupervisorListener:
           tags:
               - { name: kernel.event_listener, event: supervisor.process.start, method: onProcessStart }
   

3. HTTP Client Adapters While not yet implemented, you can monkey-patch the bundle’s SupervisorClient to support Guzzle 6 or other adapters. Override the service:

   services:
       Aboutcoders\SupervisorBundle\Client\SupervisorClient:
           arguments:
               $client: '@http_client' # Your custom client (e.g., Guzzle 6)