SkinbaseNova/docs/enhance.md

Skinbase Enhance

Operational notes for the Enhance v1/v1.1 module.

For full setup, enablement, worker configuration, verification, and production rollout guidance, see docs/enhance-setup.md.

Configuration

• ENHANCE_ENGINE=stub keeps Enhance in preview mode for local and workflow testing.
• ENHANCE_ENGINE=external_worker uses the prepared external worker adapter boundary.
• ENHANCE_QUEUE=default is the current safe default.
• ENHANCE_QUEUE=enhance is supported when you want a dedicated queue later.
• If you switch to ENHANCE_QUEUE=enhance, Horizon or any worker process must explicitly consume the enhance queue in production.

Helpful commands

php artisan enhance:health
php artisan enhance:health --json
php artisan enhance:cleanup --dry-run
php artisan enhance:cleanup --force
php artisan queue:work --queue=enhance,default

Cleanup behavior

• Enhance cleanup only removes files under the configured Enhance prefixes:
  • enhance/sources
  • enhance/outputs
  • enhance/previews
• Cleanup never deletes artwork originals, thumbnails, avatars, or other non-Enhance paths.
• Completed jobs can expire automatically via ENHANCE_COMPLETED_EXPIRES_AFTER_DAYS.
• Failed jobs can have stale files pruned via ENHANCE_FAILED_EXPIRES_AFTER_DAYS.
• Soft-deleted jobs respect ENHANCE_DELETED_FILE_GRACE_DAYS before file cleanup.

Scheduler

• The app schedules php artisan enhance:cleanup --force daily from routes/console.php.
• If you disable Laravel's scheduler in an environment, run cleanup manually or through external cron.

Queue and Horizon reminder

• Stub mode still dispatches queued Enhance jobs and exercises the same lifecycle.
• If workers only consume default and you later move Enhance to a dedicated queue, completed jobs will stall in queued until enhance is added to the worker queue list.

External Worker v1

• Set ENHANCE_ENGINE=external_worker to switch Laravel from the stub processor to the HTTP worker integration.
• Recommended local Laravel env:

ENHANCE_ENGINE=external_worker
ENHANCE_WORKER_URL=http://127.0.0.1:8095
ENHANCE_WORKER_TIMEOUT=600
ENHANCE_WORKER_TOKEN=change-this-token
ENHANCE_WORKER_MAX_DOWNLOAD_MB=60
ENHANCE_QUEUE=enhance

• Keep the worker bound to 127.0.0.1 or a private container network. Do not expose it publicly.
• Laravel sends the worker a short-lived source URL. If the storage disk cannot issue temporary URLs, Laravel falls back to a temporary signed internal route that serves only the copied Enhance source file.
• Laravel remains the source of truth: the worker only returns a temporary result, Laravel downloads it, validates it, stores it on the Enhance disk, and then asks the worker to delete the temporary file.
• Useful commands after enabling the worker:

php artisan config:clear
php artisan enhance:health
php artisan queue:work --queue=enhance,default
php artisan test --filter=EnhanceExternalWorker

Real-ESRGAN Runtime

• Laravel still uses ENHANCE_ENGINE=external_worker. It does not need to know whether the worker uses Pillow or Real-ESRGAN internally.
• Use WORKER_ENGINE=pillow for local development, CI, and fallback operation.
• Use WORKER_ENGINE=realesrgan-ncnn for the real ncnn-vulkan runtime path.
• If worker health reports status: degraded, keep Laravel on the stub processor or a Pillow worker until the Real-ESRGAN runtime is verified.
• Do not expose the worker port publicly.
• Move to the enhance Horizon queue only after the worker is healthy and verified in your environment.
• Real-ESRGAN runtime files are not committed. Install them locally or in deployment with the worker scripts:

cd services/enhance-worker
bash scripts/download-realesrgan-ncnn.sh
bash scripts/verify-realesrgan.sh

• Recommended Laravel env when using the real worker:

ENHANCE_ENGINE=external_worker
ENHANCE_QUEUE=enhance
ENHANCE_WORKER_URL=http://127.0.0.1:8095
ENHANCE_WORKER_TIMEOUT=900
ENHANCE_WORKER_TOKEN=change-this-token
ENHANCE_WORKER_MAX_DOWNLOAD_MB=60