Devops Laravel Package

Getting Started

Minimal Steps

1. Installation Run the package installer:

   composer require moox/devops
   php artisan mooxdevops:install
   

   This publishes migrations, config, and sets up Filament integration.

2. First Use Case

   • Access the Filament admin panel (/admin) to manage Forge servers.
   • Verify the devops config file (config/devops.php) is published and configured.
   • Run migrations if not auto-applied:

     php artisan migrate
     

Where to Look First

• Filament Admin Panel: The primary UI for managing servers.
• Config File: config/devops.php (published via vendor:publish).
• Migrations: Check database/migrations/ for devops_* tables.
• Service Provider: App\Providers\MooxDevopsServiceProvider (if manually registered).

Implementation Patterns

Core Workflows

1. Server Management via Filament

   • Use Filament’s built-in CRUD for Forge servers (e.g., create, update, delete).
   • Example: Extend the Server resource to add custom fields:

     use Moox\Devops\Resources\ServerResource;
     
     class CustomServerResource extends ServerResource {
         public static function form(Form $form): Form {
             return parent::form($form)
                 ->schema([
                     // Add custom fields here
                     TextInput::make('custom_field')->required(),
                 ]);
         }
     }
     

2. API Integration

   • The package likely exposes a facade (Devops) or service container bindings.
   • Example: Fetch servers programmatically:

     $servers = \Moox\Devops\Facades\Devops::servers()->get();
     

3. Event-Driven Extensions

   • Listen to Forge webhook events (if supported) to sync state:

     use Moox\Devops\Events\ServerCreated;
     
     ServerCreated::listen(function (ServerCreated $event) {
         // Sync with external tools (e.g., Slack, monitoring)
     });
     

4. Configuration Overrides

   • Customize Forge API credentials or Filament permissions in config/devops.php:

     'forge' => [
         'api_token' => env('FORGE_API_TOKEN'),
         'permissions' => [
             'create_servers' => true,
         ],
     ],
     

Integration Tips

• Filament Widgets: Add server status dashboards using Filament’s widgets.
• Laravel Queues: Offload long-running tasks (e.g., server backups) to queues.
• Testing: Use Moox\Devops\Tests\CreatesServers trait for server-related tests.

Gotchas and Tips

Pitfalls

1. Filament Dependency

   • Requires Filament v3+. Ensure compatibility:

     composer require filament/filament:"^3.0"
     

   • If Filament isn’t installed, the package may fail silently.

2. Forge API Rate Limits

   • Exceeding Forge API limits may break operations. Implement retries:

     use Illuminate\Support\Facades\Http;
     
     Http::timeout(30)->retry(3, 100);
     

3. Migration Conflicts

   • If manually publishing migrations, check for table name collisions (e.g., servers vs. forge_servers).

4. Caching Issues

   • Clear Filament cache after config changes:

     php artisan filament:cache-clear
     

Debugging

• Log Forge API Calls Enable Laravel’s HTTP logging:

  'forge' => [
      'debug' => env('FORGE_DEBUG', false),
  ],
  

  Check logs in storage/logs/laravel.log.

• Filament Debug Mode Enable for UI issues:

  FILAMENT_DEBUG=true
  

Extension Points

1. Custom Resources Override default Filament resources by binding them in AppServiceProvider:

   public function boot(): void {
       $this->app->bind(
           \Moox\Devops\Resources\ServerResource::class,
           \App\Resources\CustomServerResource::class
       );
   }
   

2. Webhook Handlers Extend the ServerWebhookHandler class to process custom events:

   namespace App\Devops;
   
   use Moox\Devops\Handlers\ServerWebhookHandler as BaseHandler;
   
   class CustomWebhookHandler extends BaseHandler {
       public function handleServerUpdated($payload) {
           // Custom logic
       }
   }
   

3. Service Container Bind custom services to the devops container:

   $this->app->extend('devops', function ($devops) {
       $devops->extend('backup', function () {
           return new CustomBackupService();
       });
   });
   

Config Quirks

• Environment Variables Ensure FORGE_API_TOKEN and FORGE_SITE_URL are set in .env:

  FORGE_API_TOKEN=your_token_here
  FORGE_SITE_URL=https://forge.example.com
  

• Default Permissions The package may ship with restrictive defaults. Adjust in config/devops.php:

  'permissions' => [
      'view_servers' => true,
      'manage_servers' => false, // Disable by default
  ],