Vector Server Pkg Laravel Package

Getting Started

• Require the release and publish its config: composer require rconfig/... then php artisan vendor:publish --tag=vector-hub-config. The single most useful file to read first is config/vector-hub.php — it holds the wrapper path, the vector-hub group name, cert source directory, and the allowed install hosts/paths.
• Run the mandatory one-time bootstrap before restarting workers or deploying new code: sudo php artisan rconfig:vector-hub-install-helper. It installs the root-owned VectorHubCtl wrapper, writes the sudoers rule, and adds the web user to the vector-hub group.
• Verify the two things that will otherwise bite you later: sudo -l -U www-data (should show the VectorHubCtl entry) and sudo -u www-data groups (should include vector-hub).
• First use case: dispatch InstallVectorHubJob with an explicit action, e.g. InstallVectorHubJob::dispatch('install'), from a tinker session or a test, and watch it complete on the queue. From there, wire the same job into your provisioning controller or command.

Implementation Patterns

• Explicit job actions. InstallVectorHubJob now takes 'install' or 'uninstall' — treat it as a required constructor argument or dispatch($action) parameter, and give callers a small enum or constants class rather than raw strings so the two paths stay greppable.
• Two distinct privilege contexts. Install/uninstall/service operations go through VectorHubCtl (root via sudoers); SyncHubCertsJob runs as the web user and reads certs through the vector-hub group. Keep that separation in mind when choosing queue workers and when debugging — a cert sync failure is a group/permission problem, not a sudo problem.
• Deployment ordering. Add the helper run as an idempotent deploy step (release hook / provisioning recipe) that executes before queue:restart and before the app code that dispatches InstallVectorHubJob ships. Because it is root-only, it cannot live inside a normal migrate step.
• API integration. The install endpoint now validates URLs, hosts and file paths strictly. Have clients read the accepted hosts/paths from config and validate client-side, and surface 422 validation messages verbatim rather than swallowing them — the messages are your best signal for what the stricter rules rejected.
• Scheduling. Drive SyncHubCertsJob from the scheduler (->hourly()->withoutOverlapping()) so cert rotation is hands-off; keep it on a worker that runs as the web user.
• Testing. Queue::fake() + assertPushed(InstallVectorHubJob::class, fn ($job) => $job->action === 'install') covers dispatch logic; use Process::fake() to assert the wrapper invocation shape without needing root or a real VectorHubCtl on the test box. Never let tests shell out to sudo.

Gotchas and Tips

• The upgrade is operationally breaking despite the patch version. Deploying v2.0.2 code before running rconfig:vector-hub-install-helper leaves jobs calling a wrapper that does not exist — expect failed jobs with permission/command not found errors. Sequence the helper first, and gate the rollout on it.
• Group membership is not retroactive. Adding the web user to vector-hub does not affect already-running PHP-FPM/queue worker processes. Restart FPM and queue:restart after the helper runs, otherwise SyncHubCertsJob still gets EACCES on cert files.
• insecure_download is now rejected. Any stored automation, seeders, Terraform/Ansible payloads or saved form data still sending it will start failing at the API. Search your codebase and fixtures for the flag and migrate to https URLs.
• Stricter host/path validation. Bare IPs, non-HTTPS schemes, non-allowlisted hosts, and paths with .. or unusual encodings that previously squeaked through are now refused. If a legitimate internal host is rejected, extend the allowlist in config — do not loosen the validator.
• Debugging checklist, in order: sudo -l -U <webuser> → groups <webuser> → wrapper location vs config('vector-hub.wrapper') → recent wrapper/sudo entries in syslog → failed_jobs payload. Most incidents land in the first two steps.
• Sudoers is path- and user-specific. Renaming the wrapper, moving the install prefix, or changing the web user silently breaks the rule. Treat the wrapper path and web user as config that must be updated in lockstep.
• Extension points. Override the wrapper path and group name in config rather than patching the job; bind your own implementation of whatever service wraps VectorHubCtl if you need audit logging around privileged calls; listen for job events (JobProcessed/JobFailed) to alert on repeated install/uninstall churn.