Sail Laravel Package

Getting Started

Minimal Setup

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 (MySQL, Redis, etc.) in detached mode.

3. Basic Commands:

   sail artisan migrate       # Run migrations inside containers
   sail php artisan tinker    # Access Tinker
   sail npm run dev           # Run npm scripts
   

4. Key Files:

   • docker-compose.yml (or compose.yaml): Defines services (PHP, MySQL, Redis, etc.).
   • .env: Environment variables for containers (e.g., DB_HOST=mysql).
   • sail: Alias script for Docker commands (auto-generated).

First Use Case: Local Development

Replace localhost in .env with service names (e.g., DB_HOST=mysql, REDIS_HOST=redis). Test with:

sail artisan serve

Access your app at http://localhost.

Implementation Patterns

Workflow Integration

1. Artisan Commands: Prefix any artisan command with sail:

   sail artisan queue:work
   sail artisan schedule:run
   

2. Database Management:

   • Reset databases:

     sail artisan migrate:fresh --seed
     

   • Use mysql service directly:

     sail mysql
     

3. Node.js/Yarn:

   sail npm install
   sail npm run dev
   sail yarn test
   

4. Custom Services: Extend compose.yaml to add services (e.g., PostgreSQL, MongoDB):

   services:
     postgres:
       image: 'postgres:18'
       ports:
         - '5432:5432'
       environment:
         POSTGRES_USER: sail
         POSTGRES_PASSWORD: password
         POSTGRES_DB: sail
   

   Then update .env:

   DB_CONNECTION=pgsql
   DB_HOST=postgres
   

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

   volumes:
     - ./:/opt
   

6. Environment Variables: Override defaults via .env or CLI:

   sail --env=testing up
   

Common Patterns

• Shared Storage: Use named volumes for persistent data (e.g., databases).
• Port Forwarding: Expose ports for services like mailpit (SMTP) or laravel-echo (Pusher).
• Custom Dockerfiles: Override PHP versions or extensions by extending the base image in compose.yaml:

  services:
    laravel.test:
      build:
        context: .
        dockerfile: Dockerfile
  

Gotchas and Tips

Pitfalls

1. Port Conflicts:

   • Error: port is already allocated.
   • Fix: Change ports in compose.yaml or stop conflicting services (sail down).

2. Missing Dependencies:

   • Symptom: Commands fail with command not found (e.g., node, composer).
   • Fix: Ensure dependencies are installed in the container (e.g., sail composer install).

3. Permission Issues:

   • Error: Permission denied when writing to volumes.
   • Fix: Add your user to the docker group or use sudo (not recommended).

4. Environment Variables Not Loading:

   • Symptom: .env changes ignored.
   • Fix: Restart containers (sail down && sail up) or use sail restart.

5. Xdebug Not Working:

   • Symptom: Breakpoints ignored.
   • Fix: Ensure XDEBUG_MODE=debug is in .env and IDE is configured for laravel.test host.

6. Windows (WSL2) Quirks:

   • Use sail --mac for macOS-like paths or ensure WSL2 is enabled.
   • Shared drives may cause permission issues; use /mnt/c/ instead of C:\.

Debugging Tips

• Logs:

  sail logs -f laravel.test  # Follow logs for a service
  sail logs mysql             # Check MySQL logs
  

• Exec into Containers:

  sail shell                  # Laravel container
  sail mysql                  # MySQL container
  sail artisan tinker         # Run Tinker inside container
  

• Health Checks:

  sail ps                     # List running containers
  sail up --force-recreate    # Rebuild containers
  

Configuration Quirks

1. Custom PHP Extensions: Extend the Dockerfile or use compose.yaml:

   services:
     laravel.test:
       image: laravel/sail:8.2-apache
       extra_hosts:
         - "host.docker.internal:host-gateway"
   

   For custom extensions, create a Dockerfile:

   FROM laravel/sail:8.2-apache
   RUN docker-php-ext-install swoole
   

2. Node Version: Override Node.js version in compose.yaml:

   services:
     laravel.test:
       environment:
         NODE_VERSION: 20
   

3. AI Agent Variables: Forward host-specific env vars (e.g., for GitHub Copilot):

   GITHUB_COPILOT_ENABLED=true
   

4. Podman Support: Use SAIL_DOCKER_BINARY=podman in .env for Podman compatibility.

Extension Points

1. Custom Services: Add new services to compose.yaml and update .env:

   services:
     typesense:
       image: typesense/typesense:0.27.1
       ports:
         - "8108:8108"
   

   TYPESENSE_HOST=typesense
   

2. Override Defaults: Copy vendor/laravel/sail/stubs/ to your project and customize:

   • docker-compose.yml.stub → docker-compose.yml
   • .env.stub → .env

3. CI/CD Integration: Use sail test or sail artisan test in GitHub Actions:

   jobs:
     test:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v4
         - run: docker-compose up -d
         - run: sail artisan test
   

4. VS Code Dev Containers: Use the devcontainer.json stub to enable full-featured containers in VS Code:

   {
     "name": "Laravel Sail",
     "dockerComposeFile": "docker-compose.yml",
     "service": "laravel.test",
     "workspaceFolder": "/opt"
   }
   

Pro Tips

• Alias Management: Add to your shell config (~/.bashrc or ~/.zshrc):

  alias sail='[ -f sail ] && bash sail || bash vendor/bin/sail'
  

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

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

• Multi-Container Apps: Use sail up service1 service2 to start specific services.
• Backup Data: Commit sail/mysql, sail/postgres, etc., to version control for local backups.