README

Production-ready Docker and Helm support for Laravel applications, with guided installation, Octane integration, and streamlined build and deploy workflows.

What Beacon does

Beacon installs into an existing Laravel application and scaffolds the first layer of production deployment assets.

Current MVP features:

• interactive php artisan beacon:install command built with Laravel Prompts
• optional Laravel Octane installation when the Octane runtime is selected
• Dockerfile generation for php-fpm or octane
• Helm chart scaffolding under charts/<application-slug>
• named Helm environment overlays for local, staging, and production
• managed Composer scripts for beacon:build and beacon:deploy
• Pest coverage, Laravel compatibility CI, and automated semantic releases for the package itself

Out of scope for this MVP:

• cloud-specific deployment logic
• full platform provisioning
• environment-specific infrastructure assumptions

Requirements

• PHP ^8.3
• Laravel ^11.0 | ^12.0 | ^13.0

Install

Recommended as a development dependency in the Laravel application you want to prepare:

composer require devoption/beacon --dev

Then run the installer:

php artisan beacon:install

Install flow

Beacon currently prompts for:

• application name
• runtime: php-fpm or octane
• deployment scaffolding: docker, helm, or docker-and-helm
• ingress provider: disabled, Ingress NGINX, or Traefik
• secret handling: Beacon-managed Helm secret or an existing Kubernetes secret
• whether Beacon should update Composer scripts

When the Octane runtime is selected, Beacon checks the target application's composer.json and installs laravel/octane if it is not already present.

Generated files

Depending on the options you choose, Beacon generates:

• Dockerfile
• charts/<application-slug>/Chart.yaml
• charts/<application-slug>/values.yaml
• charts/<application-slug>/values.local.yaml
• charts/<application-slug>/values.local.secrets.example.yaml
• charts/<application-slug>/values.staging.yaml
• charts/<application-slug>/values.staging.secrets.example.yaml
• charts/<application-slug>/values.production.yaml
• charts/<application-slug>/values.production.secrets.example.yaml
• charts/<application-slug>/templates/_helpers.tpl
• charts/<application-slug>/templates/deployment.yaml
• charts/<application-slug>/templates/secret.yaml
• charts/<application-slug>/templates/service.yaml
• charts/<application-slug>/templates/ingress.yaml

If Composer script updates are enabled, Beacon also manages:

• beacon:build
• beacon:deploy

Example managed scripts:

{
  "scripts": {
    "beacon:build": "docker build --file Dockerfile --tag my-app:latest .",
    "beacon:deploy": "@php artisan beacon:deploy"
  }
}

Beacon generates values.yaml as the shared chart values file and also creates environment-specific overlays for local, staging, and production. The selected ingress strategy is persisted there so the generated chart knows whether ingress is disabled and which class name Beacon should prepare for. The deploy command always applies values.yaml first, then layers the selected environment values file on top when it runs Helm.

Sensitive application values are kept out of the committed environment overlays. Beacon now:

• keeps non-sensitive settings in the regular values*.yaml files
• generates values.<environment>.secrets.example.yaml templates to show the expected secret structure
• adds /charts/*/values.*.secrets.yaml to the Laravel app .gitignore
• automatically includes values.<environment>.secrets.yaml during beacon:deploy when that ignored file exists

This keeps secret values out of Git-tracked files, but it does not keep them out of Helm release metadata. When values.<environment>.secrets.yaml is passed to Helm, those values are stored in the Helm release Secret or ConfigMap and can remain in release history.

If you choose the existing Kubernetes secret mode during installation, Beacon configures the chart to reference that external secret instead of creating its own Secret manifest. Use that mode, or another workflow that injects secrets outside Helm values files, if you need to avoid persisting secret values in Helm release metadata or history.

Rerunning the installer

Beacon is designed to be rerunnable.

• generated Beacon-managed files are rewritten with current stub output
• unchanged generated files remain unchanged on repeat runs
• Beacon-managed Composer script entries are updated without replacing unrelated user scripts

Development

Run the test suite with:

composer test

Repository automation also includes:

• Laravel compatibility CI in .github/workflows/ci.yml
• publish-readiness validation in .github/workflows/publish-readiness.yml
• automated semantic releases in .github/workflows/release.yml

For contributor workflow details, see CONTRIBUTING.md.

For maintainer release and Packagist setup notes, see docs/RELEASING.md.

License

MIT