Laravel Starter Kit Laravel Package

Getting Started

This starter kit is a batteries-included Laravel application (Laravolt auth, RBAC, menus, and CRUD scaffolding) plus a Docker-first workflow. Start here:

1. Clone the repo and copy the environment file:

   cp .env.example .env
   

2. Bring up the dev stack:

   docker compose up -d
   docker compose exec app composer install
   docker compose exec app php artisan key:generate
   docker compose exec app php artisan migrate --seed
   

3. Run the asset pipeline (npm install && npm run dev) and open the app; default seeded credentials are documented in the README.
4. First place to look: docker/ (Dockerfile + entrypoint hooks), config/laravolt.php, and the application/module directories where generated CRUD lives.

First use case: scaffold a CRUD module for an existing table, then wire it into the menu and gate it behind a role. That exercises the auth, RBAC, menu, and generator layers in one pass.

v1.7.2 note: the production image now builds on laravoltdev/image:php8.5-prod (which ships bcmath/exif), and laravolt:link runs at build time rather than via the entrypoint hook. If you are starting fresh, use the shipped Dockerfiles as-is before customizing.

Implementation Patterns

Use the generator, then edit. Scaffold CRUD, then move business logic into form requests, actions, and policies. Generated controllers are a starting point, not a home for domain logic.

Keep Docker and Compose in sync. Dev and prod use separate Dockerfiles and compose files. When you add a PHP extension locally, mirror it in both images — and prefer the laravoltdev/image base images over generic composer:2/php images so bcmath, exif, and other Laravolt requirements are present.

Treat autorun flags as configuration, not magic. The entrypoint honors AUTORUN_LARAVOLT_* env vars. Anything that mutates the filesystem (symlinks, migrations, caching) should either be idempotent or explicitly disabled per environment. As of v1.7.2, prod sets AUTORUN_LARAVOLT_LINK: "false" in both compose and the Dockerfile because the link is created during build.

Seed roles and permissions declaratively. Define permissions in code/seeder, assign them to roles, and reference permission names in routes/menus. This keeps environments reproducible and avoids clicking through the UI on every deploy.

Menus as data. Register menu entries via seeders or config rather than hardcoding them in Blade. It keeps navigation consistent between local, staging, and prod.

Layer gates at the route and policy level. Use middleware for coarse access (role/permission) and policies for record-level rules. Don't rely on hiding UI elements as authorization.

Local iteration loop. docker compose exec app php artisan make:laravolt ... (or the package's generator command), then npm run dev for HMR. Rebuild the image only when dependencies or extensions change; otherwise the bind mount handles code changes.

Gotchas and Tips

• laravolt:link on an existing symlink fails. The entrypoint hook is not idempotent; v1.7.2 moved the link to build time and set AUTORUN_LARAVOLT_LINK=false. If you see symlink errors on container start, check that flag in both docker-compose.yml and the Dockerfile — a mismatch between the two is the usual culprit.
• composer:2 is not a runtime image. It lacks bcmath/exif, so Laravolt code fails at runtime even though the build succeeds. Use laravoltdev/image:php8.5-prod (or add the extensions explicitly) for any vendor/runtime stage.
• Prod compose and Dockerfile drift. v1.7.2 aligned AUTORUN_LARAVOLT_LINK across both files. When changing env defaults, update every place they appear; the Dockerfile ENV wins inside the image, compose overrides at runtime.
• Stale caches after config/route changes. Run php artisan optimize:clear inside the container. If a config change "doesn't apply," you're usually looking at a cached config from a previous build.
• Rebuild after dependency changes. composer install in a running container doesn't update the image; CI/prod will behave differently. Rebuild the vendor stage when composer.lock changes.
• PHP 8.5 base image. The prod image targets 8.5. Verify third-party packages declare compatibility before deploying; pin versions if you hit deprecations.
• Extension points: add app-specific entrypoint logic in a separate script rather than editing the packaged entrypoint, and prefer service providers/observers over patching generated CRUD controllers so future kit upgrades stay painless.