Weave Code
Sail Laravel Package
laravel/sail
Laravel Sail offers a Docker-powered local development environment for Laravel on macOS, Windows (WSL2), and Linux. With a simple CLI and no extra dependencies beyond Docker, it lets you spin up a full dev stack quickly—even without Docker experience.
Docker files for running a basic Laravel application.
Frequently asked questions about Sail
- How do I install Laravel Sail in an existing Laravel project?
- Run `composer require laravel/sail --dev` in your Laravel project directory. Then, copy the `.env.example` file to `.env` and execute `./vendor/bin/sail build --no-cache` to build the Docker containers. Start the environment with `./vendor/bin/sail up`. Sail integrates seamlessly with Laravel’s existing `.env` configuration.
- Which Laravel versions does Sail officially support?
- Laravel Sail is designed to work with the latest Laravel LTS versions (e.g., Laravel 10.x, 11.x) and maintains compatibility with PHP 8.1+. Check the [Laravel Sail documentation](https://laravel.com/docs/sail) for version-specific notes, as Sail updates align with Laravel’s release cycle.
- Can I use Sail for production deployments?
- No, Sail is **not** intended for production. It’s optimized for local development and CI/CD testing. For production, use dedicated hosting (e.g., Forge, Heroku) or container orchestration tools like Kubernetes. Sail’s containers are ephemeral and lack optimizations for high availability or scaling.
- How do I customize Sail’s Docker services (e.g., add MongoDB or Elasticsearch)?
- Extend Sail by modifying the `docker-compose.yml` file in your project’s root. Sail provides stub files (e.g., `docker-compose.override.yml`) for custom services. For example, add a MongoDB service block and rebuild with `./vendor/bin/sail build`. Document your changes to avoid conflicts during updates.
- Why does Sail use specific PHP/MySQL versions? Can I override them?
- Sail defaults to versions aligned with Laravel’s supported stack (e.g., PHP 8.2, MySQL 8.0) for consistency. Override versions by editing the `docker-compose.yml` file or using `.env` variables like `SAIL_MYSQL_VERSION=5.7`. Note: Version mismatches may break Laravel features or dependencies.
- How do I persist database or Redis data between container restarts?
- Sail uses Docker volumes to persist data. For databases, ensure `SAIL_MYSQL_VOLUME` or `SAIL_POSTGRES_VOLUME` is set in `.env` to mount a named volume. Redis data persists by default via its volume configuration. Always back up critical data manually, as container restarts or `sail down` commands may reset volumes.
- Is Sail compatible with Windows without WSL2?
- No, Sail requires **WSL2** on Windows for full compatibility. Without WSL2, Docker Desktop’s Linux containers may not work reliably due to filesystem performance issues. Test thoroughly if using alternative setups, as some Laravel features (e.g., file system permissions) may behave differently.
- How do I debug issues like port conflicts or slow container startup?
- Check for port conflicts by running `./vendor/bin/sail artisan sail:publish`. Slow startups often stem from Docker resource limits—adjust CPU/memory in `docker-compose.yml` or use `sail --scale` to limit concurrent containers. For logs, use `sail logs` or `docker-compose logs` to inspect service-specific errors.
- Can I use Sail with Laravel Forge or other hosting providers?
- Sail is for **local development only** and doesn’t replace Forge or hosting providers. However, you can use Sail to test your Laravel app locally before deploying to Forge. Ensure your production environment matches Sail’s PHP extensions and configurations (e.g., `pdo_pgsql`, `bcmath`) to avoid runtime errors.
- What are the alternatives to Laravel Sail for Docker-based Laravel development?
- Alternatives include **Laradock** (more customizable but complex), **DDEV** (focused on PHP/Node.js polyglot stacks), or **Valet + Docker** for macOS. Sail stands out for its Laravel-specific optimizations, minimal setup, and official Laravel support. Choose Laradock if you need advanced service configurations or DDEV for multi-language projects.
Weaver
How can I help you explore Laravel packages today?