Nginx Unit Laravel Package

Getting Started

Minimal Steps

1. Installation Run composer require baks-dev/nginx-unit in your Laravel project. Ensure your project uses PHP 8.4+ and Laravel 10.x+ (verify via php -v and laravel --version).

2. Publish Config & Assets Execute:

   php artisan vendor:publish --provider="BaksDev\NginxUnit\NginxUnitServiceProvider" --tag="config"
   php artisan vendor:publish --provider="BaksDev\NginxUnit\NginxUnitServiceProvider" --tag="assets"
   

   This generates:

   • config/nginx-unit.php (configuration)
   • Assets (e.g., Unit controller templates, config files) in public/nginx-unit/.

3. First Use Case: Local Development

   • Configure config/nginx-unit.php with your local Unit server details (e.g., unit_socket).
   • Start Nginx Unit locally (if not using Docker).
   • Run:

     php artisan nginx-unit:deploy
     

   This deploys a default configuration to your Unit server.

Where to Look First

• Configuration: config/nginx-unit.php (adjust unit_socket, server_name, and upstream settings).
• Commands: php artisan list → Filter for nginx-unit: commands (e.g., deploy, reload, status).
• Logs: Check storage/logs/nginx-unit.log for deployment/reload errors.
• Unit API Docs: Official Nginx Unit API (for advanced use cases like dynamic config updates).

Implementation Patterns

Workflows

1. Local Development

   • Use php artisan nginx-unit:deploy to sync config to Unit.
   • Test API routes (e.g., /api/health) via curl http://localhost:8080/health.
   • Reload Unit without restarting:

     php artisan nginx-unit:reload
     

2. CI/CD Integration

   • Add to your deployment pipeline:

     php artisan nginx-unit:deploy --env=production
     

   • Use --force to overwrite existing configs if needed.

3. Dynamic Configuration

   • Extend the package by binding custom config templates:

     // app/Providers/NginxUnitServiceProvider.php
     public function boot()
     {
         $this->app->bind('nginx-unit.template', function () {
             return new CustomTemplateRenderer();
         });
     }
     

   • Override default templates in resources/views/vendor/nginx-unit/.

4. Health Checks

   • Register a route to ping Unit:

     Route::get('/nginx-unit/health', function () {
         return response()->json(['status' => NginxUnit::status()]);
     });
     

Integration Tips

• Laravel Queues: Use Unit to process background jobs via nginx-unit:queue command.
• Docker: Mount storage/nginx-unit/config to your Unit container’s config directory.
• Monitoring: Integrate with Laravel Horizon or Prometheus via Unit’s metrics API.

Gotchas and Tips

Pitfalls

1. Socket Permissions

   • Ensure the Laravel app user (e.g., www-data) has read/write access to the unit_socket path.
   • Fix: chmod 777 /var/run/nginx-unit.sock (temporary; adjust permissions in production).

2. Config Validation

   • Unit rejects malformed configs silently. Validate with:

     php artisan nginx-unit:validate
     

3. Certbot Integration

   • The README mentions Certbot, but the package doesn’t automate it. Manually run:

     certbot certonly --webroot -w public/ -d yourdomain.com
     

   • Then update nginx-unit.php to point to the cert paths.

4. PHP-FPM vs. Unit

   • Avoid mixing PHP-FPM and Unit for the same app. Unit handles requests directly; disable PHP-FPM in your web server (e.g., Nginx/Apache).

Debugging

• Logs: Tail Unit logs with:

  journalctl -u nginx-unit -f  # Systemd
  # OR
  cat /var/log/nginx/unit.log
  

• Dry Runs: Use --dry-run with nginx-unit:deploy to preview changes:

  php artisan nginx-unit:deploy --dry-run
  

Extension Points

1. Custom Config Templates

   • Override vendor/baks-dev/nginx-unit/src/ConfigTemplates/ in your project.
   • Example: Add a custom.conf template for API-specific routes.

2. Event Listeners

   • Listen to nginx-unit.deployed events:

     public function handle(NginxUnitDeployed $event)
     {
         Log::info('Unit config deployed to ' . $event->serverName);
     }
     

3. Unit API Extensions

   • Use the package’s NginxUnit facade to interact with Unit’s API:

     $status = NginxUnit::status(); // Returns server status
     $config = NginxUnit::getConfig('api'); // Fetch a specific config
     

Config Quirks

• Environment Variables: Prefix Unit settings with NGINX_UNIT_ (e.g., NGINX_UNIT_SERVER_NAME=api.local).
• Default Ports: Unit defaults to 8080 for HTTP. Change in config/nginx-unit.php:

  'ports' => [
      'http' => 8080,
      'https' => 8443,
  ],
  

• SSL: If using HTTPS, ensure ssl_certificate and ssl_certificate_key paths are correct and files are readable.