Sail Laravel Package

## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require laravel/sail --dev
   sail build --no-cache
   sail up

• The sail command is a CLI wrapper for Docker Compose, automatically generated in your project root after installation.

2. First Use Case:

   • Run migrations and start the Laravel server:

     sail artisan migrate
     sail artisan serve
     

   • Access your app at http://localhost (default port: 80).

3. Key Files:

   • docker-compose.yml (or compose.yaml): Defines services (PHP, MySQL, Redis, etc.).
   • .env: Environment variables for Sail (e.g., SAIL_MYSQL_ROOT_PASSWORD).
   • sail: The CLI script (auto-generated; edit .env to customize).

Implementation Patterns

Daily Workflows

1. Development Loop:

   # Start containers (detached mode)
   sail up -d
   
   # Run Laravel commands inside containers
   sail artisan queue:work
   sail artisan test
   
   # Access a shell
   sail shell  # (as Laravel user)
   sail root-shell  # (as root)
   

2. Service Management:

   • Start/stop specific services:

     sail up mysql redis
     sail down mysql
     

   • Customize services via .env (e.g., SAIL_MYSQL_PORT=3307).

3. Artisan Command Aliases:

   • Sail aliases common Artisan commands:

     sail migrate  # Equivalent to `sail artisan migrate`
     sail tinker   # Equivalent to `sail artisan tinker`
     

4. Database Management:

   • Reset databases:

     sail mysql:reset
     sail postgres:reset
     

   • Dump/import databases:

     sail mysql:dump > backup.sql
     sail mysql:import < backup.sql
     

5. Testing:

   • Run tests with browser (Pest/Laravel):

     sail test --browser
     sail pest --browser
     

   • Use sail artisan test for PHPUnit.

6. Custom Commands:

   • Extend the sail script by adding aliases to ~/.bashrc or .env:

     SAIL_EXTRA_COMMANDS="alias sail:queue='sail artisan queue:work --daemon'"
     

Integration Tips

1. IDE Integration:

   • Use Laravel DevContainer for VSCode to auto-attach to Sail containers.
   • Configure Xdebug in .env:

     SAIL_XDEBUG_ENABLED=true
     SAIL_XDEBUG_PORT=9003
     

2. CI/CD:

   • Use Sail in GitHub Actions:

     services:
       mysql:
         image: mysql:8.4
         env:
           MYSQL_ROOT_PASSWORD: secret
           MYSQL_DATABASE: laravel
         ports:
           - 3306:3306
       sail:
         image: ghcr.io/laravel/sail:8.11
         ports:
           - 80:80
     

3. Custom Dockerfiles:

   • Override the PHP Dockerfile by creating docker/php/Dockerfile in your project root.
   • Example: Add custom PHP extensions:

     RUN docker-php-ext-install gd avif
     

4. Environment Variables:

   • Pass host environment variables to containers:

     SAIL_ENVIRONMENT=local
     SAIL_APP_ENV=local
     

   • Use sail artisan config:clear to reload .env in containers.

5. Volume Mounts:

   • Customize volume mounts in docker-compose.yml:

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

6. Service Extensions:

   • Add new services (e.g., MongoDB, Typesense) by extending docker-compose.yml:

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

Gotchas and Tips

Common Pitfalls

1. Port Conflicts:

   • Issue: Port 80 or 3306 already in use.
   • Fix: Change ports in .env:

     SAIL_HTTP_PORT=8080
     SAIL_MYSQL_PORT=3307
     

   • Debug: Run sail ps to check running containers.

2. Permission Denied:

   • Issue: Files created in containers have wrong permissions.
   • Fix: Ensure your host user is in the docker group or use sail root-shell to fix permissions:

     sail root-shell
     chown -R laravel:laravel /var/www/html/storage
     

3. Xdebug Not Working:

   • Issue: Xdebug not triggering breakpoints.
   • Fix: Verify .env settings:

     SAIL_XDEBUG_ENABLED=true
     SAIL_XDEBUG_PORT=9003
     XDEBUG_CONFIG="client_host=host.docker.internal"
     

   • Debug: Check Xdebug logs in the container:

     sail tail -f /var/www/html/storage/logs/laravel.log
     

4. MySQL Connection Errors:

   • Issue: SQLSTATE[HY000] [2002] No such file or directory.
   • Fix: Ensure SAIL_MYSQL_PORT matches your .env DB_PORT and container is running:

     sail mysql:status
     

5. Node/Yarn Issues:

   • Issue: Yarn/npm commands fail.
   • Fix: Reinstall dependencies in the container:

     sail npm install
     sail yarn install
     

   • Tip: Use Corepack (enabled by default in Sail v1.53+):

     sail corepack enable
     

6. Volume Corruption:

   • Issue: Storage volumes become corrupted.
   • Fix: Reset volumes:

     sail rm -vf  # Removes all containers and volumes
     sail up -d
     

7. PHP Version Mismatch:

   • Issue: Wrong PHP version in containers.
   • Fix: Specify PHP version in .env:

     SAIL_PHP_VERSION=8.2
     

   • Tip: List available versions with sail --help.

8. RabbitMQ/Redis Health Checks:

   • Issue: Services fail to start due to health checks.
   • Fix: Wait for services to initialize:

     sail up -d redis rabbitmq
     sleep 5  # Wait for services to be ready
     

Debugging Tips

1. Logs:

   • View logs for a specific service:

     sail logs mysql
     sail logs -f  # Follow logs in real-time
     

2. Container Inspection:

   • List running containers:

     sail ps
     

   • Inspect a container:

     sail exec mysql mysql -u root -p
     

3. Networking:

   • Access services from host:

     sail mysql:status  # Check if MySQL is reachable
     

   • Use host.docker.internal to access host services from containers.

4. Custom Scripts:

   • Add custom scripts to docker-compose.yml:

     services:
       app:
         volumes:
           - ./scripts:/var/www/html/scripts
     

   • Run scripts via:

     sail php scripts/deploy.php
     

Configuration Quirks

1. .env Overrides:

   • Sail merges .env with docker-compose.yml. Ensure consistency:

     # .env
     DB_HOST=mysql
     SAIL_MYSQL_PORT=3306
     

2. Service Aliases:

   • Use service names (not hostnames) in .env:

     # Correct:
     DB_HOST=mysql
     REDIS_HOST=redis
     

3. Podman Support:

   • Use SAIL_DOCKER_BINARY=podman in .env for Podman:

     SAIL_DOCKER_BINARY=podman
     

4. ARM/M1 Support:

   • Sail auto-detects ARM64. For issues, force AMD emulation:

     SAIL_ARCH=amd64
     

5. Custom Docker Binaries:

   • Override Docker binary path: