Weave Code
Sail Laravel Package
laravel/sail
Docker-based local dev environment for Laravel on macOS, Windows (WSL2), and Linux. Sail provides ready-to-use containers and a simple CLI so you can start developing without installing extra tools beyond Docker, even with no Docker experience.
Laravel Sail provides a Docker-powered local development environment for Laravel on macOS, Windows (WSL2), and Linux. With only Docker required, Sail’s streamlined CLI helps you spin up a full dev stack quickly—no deep Docker knowledge needed.
Built with inspiration from Vessel, Sail makes it easy to start developing Laravel apps with consistent, reproducible containers.
- One-command workflow to start/stop your local stack
- Works across macOS / WSL2 / Linux with the same setup
- Minimal prerequisites: Docker is the only requirement
- Simple CLI designed for everyday Laravel development
- Officially supported and documented in the Laravel docs
Frequently asked questions about Sail
- How do I install Laravel Sail in an existing Laravel project?
- Run `composer require laravel/sail --dev` in your project directory, then execute `sail build --no-cache` to generate Docker containers. Update your `.env` file to match Sail’s defaults (e.g., `DB_HOST=sail-mysql`) and replace `php artisan` with `sail artisan` in scripts. Test locally before deploying.
- Does Laravel Sail support Windows without WSL2?
- No, Laravel Sail officially requires WSL2 on Windows for full compatibility. Without WSL2, you’ll encounter performance issues or missing features like filesystem synchronization. Docker Desktop for Windows (with WSL2 integration) is the recommended setup.
- Can I use custom PHP versions or extensions in Sail?
- Sail supports multiple PHP versions via `sail --php=8.2` or by overriding Dockerfiles. For custom extensions (e.g., `pdo_pgsql`), add them to your `Dockerfile` or `docker-compose.override.yml`. Check Sail’s [documentation](https://laravel.com/docs/sail#customizing-the-docker-images) for extension-specific instructions.
- How do I migrate an existing database dump into Sail’s containers?
- Use `sail artisan db:import` or manually import SQL files via `sail exec mysql -u [user] -p [database] < dump.sql`. Ensure your dump matches Sail’s default database version (e.g., MySQL 8.0). For large dumps, consider compressing the file first to avoid timeouts.
- Will Sail slow down my development due to Docker overhead?
- Sail is optimized for performance with resource limits and caching. On modern hardware (8GB+ RAM), overhead is minimal. For CI/CD pipelines, use Docker-in-Docker (DinD) or pre-built images to reduce build times. Monitor resource usage with `sail top` or Docker Desktop’s resource panel.
- How do I add custom services like Elasticsearch to Sail?
- Extend Sail by adding services to `docker-compose.override.yml`. For Elasticsearch, define a service block with ports, volumes, and dependencies. Example: `elasticsearch: image: docker.elastic.co/elasticsearch/elasticsearch:8.4.0`. Then run `sail up -d` to start the new service.
- Does Sail work with Laravel Valet or Laravel Homestead?
- No, Sail replaces Homestead and Valet for local development. It’s designed as a standalone Docker solution. If you’re migrating from Homestead, run `sail install` and update your `.env` and scripts to use `sail artisan` instead of `valet link` or Homestead commands.
- How do I debug issues with Sail’s Redis or queue workers?
- Check service health with `sail ps` and logs with `sail logs redis`. For queue workers, use `sail queue:work` and monitor jobs with `sail artisan queue:failed`. Ensure your `.env` has correct queue connections (e.g., `QUEUE_CONNECTION=redis`).
- Can I use Sail in production or is it only for local development?
- Sail is **not** recommended for production. It’s optimized for local development with dynamic container management. For production, use traditional server setups (e.g., Nginx, MySQL, PHP-FPM) or managed hosting. Sail’s ephemeral containers and lack of persistent storage make it unsuitable for live environments.
- What’s the best way to test Laravel Sail in CI/CD pipelines?
- Use Docker-in-Docker (DinD) or pre-built Sail images in your CI (e.g., GitHub Actions with `services: docker`). Run `sail test` or `sail artisan test` after building containers. Cache Docker layers to speed up builds. Example: `services: docker: image: docker:dind`.
Weaver
How can I help you explore Laravel packages today?