Filament One Laravel Package

Getting Started

1. Read the Docker section of the README first. The 1.5.0 release makes containerized development the fastest path to a working environment; the quick-start commands there are the canonical bootstrap.
2. Prepare environment files.

   cp .env.example .env
   # adjust Docker-specific values (DB_HOST=mysql, REDIS_HOST=redis, etc.)
   

3. Build and start the stack.

   docker compose build
   docker compose up -d
   

   This brings up PHP 8.3-FPM, Nginx, MySQL 8.0, Redis, and a queue worker.
4. Install dependencies and initialize the app inside the app container.

   docker compose exec app composer install
   docker compose exec app php artisan key:generate
   docker compose exec app php artisan migrate
   

5. First use case: open the Nginx-exposed URL, confirm the app boots, run the test suite with docker compose exec app php artisan test, and enqueue a test job to verify the queue worker and Redis are wired correctly.

Where to look first:

• docker-compose.yml for service names and networking.
• Dockerfile for PHP extensions and Composer setup.
• .env.example for Docker-specific variables.
• README Docker guide for service URLs, ports, and troubleshooting.

Implementation Patterns

Use the container as the execution boundary for all tooling. Run Composer, Artisan, PHPUnit, and npm through docker compose exec app … (or docker compose run --rm app … for one-off commands). This keeps PHP versions, extensions, and dependency state consistent across the team.

Reference services by Compose service name. Inside containers, use DB_HOST=mysql and REDIS_HOST=redis, not 127.0.0.1. This is the most common integration point when moving an existing .env into the Docker workflow.

Leverage Redis for cache, session, and queues. The release includes Redis and a queue worker. Configure CACHE_STORE=redis, SESSION_DRIVER=redis, and QUEUE_CONNECTION=redis in Docker-specific env values, then run jobs through the dedicated worker service rather than artisan queue:work in the app container.

Use bind mounts for day-to-day iteration. Mount application source into the app and Nginx containers so code changes are reflected without rebuilding. Rebuild only when the Dockerfile or PHP extension set changes.

Wrap common commands in a Makefile or shell script. For example:

up: ; docker compose up -d
sh: ; docker compose exec app sh
test: ; docker compose exec app php artisan test
migrate: ; docker compose exec app php artisan migrate

This reduces friction and documents the expected workflow for new contributors.

Reuse the same stack in CI. Because the release ships a complete Compose setup, CI can run the same services and execute tests against MySQL and Redis instead of SQLite fakes. This narrows the gap between local and pipeline behavior.

Production path: use the Dockerfile as a multi-stage build reference, but avoid shipping the development Compose file. Build a production image with optimized autoloading and cached config, and run the queue worker as a separate process or service.

Gotchas and Tips

• DB_HOST=localhost will fail inside containers. Always use the Compose service name (mysql) and confirm the MySQL healthcheck passes before running migrations.
• File permission mismatches on bind mounts. If Laravel cannot write to storage/ or bootstrap/cache/, align the container UID/GID with the host user or run chown inside the container. This is the most frequent first-run issue with PHP-FPM bind mounts.
• Environment variables are not copied automatically. Ensure .env exists and that Docker-specific values (hosts, ports, Redis, queue) are set before starting services. Missing APP_KEY produces misleading encryption errors.
• The queue worker does not reload code automatically. After changing job classes, restart the worker (docker compose restart queue) or run it with a process monitor. Stale workers silently execute old code.
• Config and route caching inside containers can surprise you. If changes are not reflected, run php artisan config:clear and route:clear inside the app container, and check whether a cached config volume is masking your .env.
• Do not let vendor/ and node_modules/ drift between host and container. Either install dependencies only inside the container or use named volumes for these directories; mixing host and container installs causes extension and platform mismatches.
• Nginx must reach PHP-FPM by service name. If you see 502 responses, verify fastcgi_pass app:9000 (or the configured service/port) and that the app container is healthy.
• Use docker-compose.override.yml for local customization. Ports, Xdebug, and mount paths belong there rather than in the committed base Compose file.
• Rebuild after Dockerfile changes. docker compose up -d alone will not pick up new PHP extensions or Composer changes; use docker compose build --no-cache when debugging image-level issues.
• Debugging order for a failed stack: docker compose ps → docker compose logs app nginx mysql redis queue → exec into app and run php artisan about → verify service DNS resolution with getent hosts mysql redis.