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

devoption / beacon

Maintainers

Package info

Statistics

Security