Sail Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require laravel/sail --dev
   sail install
   

   This generates a docker-compose.yml (now compose.yaml) and .env file in your project root.

2. First Run:

   sail up -d
   

   Starts all services (PHP, MySQL, Redis, etc.) in detached mode.

3. Access Services:

   • Laravel app: http://localhost
   • MySQL CLI: sail mysql
   • Artisan commands: sail artisan [command]

4. Key Files:

   • docker-compose.yml (or compose.yaml): Defines services and configurations.
   • .env: Environment variables for Sail (e.g., SAIL_8000=true to expose port 8000).

First Use Case: Local Development

Replace php artisan serve with:

sail artisan serve

Sail handles:

• Dockerized PHP-FPM/Nginx.
• Database services (MySQL, PostgreSQL, SQLite).
• Redis, Meilisearch, and other dependencies.

Implementation Patterns

Core Workflows

1. Service Management:

   sail up    # Start all services
   sail down  # Stop and remove containers
   sail ps    # List running containers
   sail logs  # View logs
   

2. Customizing Services: Extend compose.yaml to add services (e.g., RabbitMQ, MongoDB):

   services:
     rabbitmq:
       image: rabbitmq:3.12
       ports:
         - "5672:5672"
   

   Then run:

   sail up -d rabbitmq
   

3. Environment-Specific Configs: Use .env variables to toggle services:

   SAIL_MYSQL_PORT=3306
   SAIL_POSTGRES_PORT=5432
   SAIL_XDEBUG=true
   

4. Artisan & CLI: Run Laravel commands inside containers:

   sail artisan migrate
   sail npm run dev
   

5. Volume Mounts: Bind host directories to containers for live reloading:

   volumes:
     - ./:/var/www/html
   

Integration Tips

• XDebug: Enable with SAIL_XDEBUG=true and configure your IDE (e.g., VSCode) to use sail as the Docker host.
• Mailpit: Add to compose.yaml for email testing:

  mailpit:
    image: axllent/mailpit
    ports:
      - "8025:8025"
  

• Pest/Browser Tests: Use sail test with Pest 4 support (v1.45.0+).
• VSCode Dev Containers: Leverage Sail’s devcontainer.json stub for IDE integration.

Gotchas and Tips

Pitfalls

1. Port Conflicts:

   • Ensure ports in .env (e.g., SAIL_8000=true) don’t clash with host services.
   • Fix: Use sail down and adjust .env or compose.yaml.

2. Volume Permissions:

   • Containers may fail if host directories lack write permissions.
   • Fix: Run chmod -R 775 storage bootstrap/cache on the host.

3. Docker Desktop Quirks:

   • On macOS/Windows, use WSL2 for Linux compatibility.
   • Fix: Enable WSL2 backend in Docker Desktop settings.

4. PHP Extensions:

   • Missing extensions (e.g., pdo_pgsql) require custom Dockerfiles.
   • Fix: Extend the PHP service in compose.yaml:

     php:
       build:
         context: .
         dockerfile: Dockerfile
     

5. Health Checks:

   • Services like PostgreSQL may fail to start if .env variables (e.g., DB_DATABASE) are misconfigured.
   • Fix: Verify .env and restart with sail up -d --build.

Debugging

1. Logs:

   sail logs -f php   # Follow PHP container logs
   sail logs mysql    # Check MySQL issues
   

2. Shell Access:

   sail shell         # Bash into the PHP container
   sail mysql         # MySQL CLI
   

3. Common Errors:

   • "Container not found": Run sail ps to verify containers are up.
   • Port binding failures: Check sail up output for conflicts.
   • XDebug not working: Ensure SAIL_XDEBUG=true and IDE is configured for Docker.

Extension Points

1. Custom Dockerfiles: Override the PHP service in compose.yaml:

   php:
     build:
       context: .
       dockerfile: Dockerfile.custom
   

   Example Dockerfile.custom:

   FROM sail-php82/app AS builder
   RUN apt-get update && apt-get install -y libpq-dev
   

2. Environment Variables: Use .env or pass directly:

   sail up -d --build --env MY_CUSTOM_VAR=value
   

3. Service Dependencies: Add depends_on to compose.yaml:

   redis:
     depends_on:
       - php
   

4. CI/CD: Use sail test in GitHub Actions:

   - name: Run tests
     run: sail test
   

Pro Tips

• Resource Limits: Adjust compose.yaml for memory/CPU:

  deploy:
    resources:
      limits:
        cpus: '1'
        memory: 2G
  

• Multi-Host Networks: Use Docker’s internal networking for services like RabbitMQ.
• Backup Data: Persist volumes (e.g., sail-mysql) to avoid data loss on sail down.
• Podman Support: Use SAIL_DOCKER_BINARY=podman in .env for Podman users.