Documentation
Getting Started
Authentication
Livewire
Dashboard & Widgets
Applications
UI Components
Data Visualization
E-commerce
Job Board
Cryptocurrency
Advanced

Laravel Sail

Laravel Sail

Overview

Laravel Sail is a lightweight command-line interface for interacting with Laravel's default Docker development environment. It provides a simple way to run Laravel applications using Docker without requiring local PHP, Composer, or Node.js installations.

Why Use Laravel Sail?

✅ Advantages of Sail

  1. No Local Dependencies - No need to install PHP, Composer, or Node.js locally
  2. Consistent Environment - Same environment across all machines and team members
  3. Easy Setup - One command to get everything running
  4. Isolated Dependencies - No conflicts with other projects or system packages
  5. Production Parity - Environment matches production more closely
  6. Easy Cleanup - Remove containers to clean up completely

⚠️ When to Use Direct PHP Instead

  • You already have PHP 8.2+ installed locally
  • You prefer faster startup times
  • You're comfortable managing local dependencies
  • You need to debug with local tools

Quick Start

1. Run the Setup Script

UltraViolet includes an automated setup script that handles everything:

./setup.sh

This script will:

  • ✅ Check system requirements (Docker, Docker Compose)
  • ✅ Install Composer dependencies
  • ✅ Install NPM dependencies
  • ✅ Set up environment files
  • ✅ Generate application key
  • ✅ Set up database
  • ✅ Build frontend assets
  • ✅ Create storage links
  • ✅ Set proper permissions

2. Start with Sail

After setup, use the Sail run script:

./run-sail.sh

This will start all Docker containers and provide you with:

3. Start Vite for Assets

In a separate terminal, start Vite for CSS/JS compilation:

# Option A: Using pm2 (recommended)
pm2 start "./vendor/bin/sail npm run dev" --name huementlocal

# Option B: Direct command
./vendor/bin/sail npm run dev

# Option C: If you have bashrc aliases set up
snpm run dev

Sail Commands

Basic Commands

# Start containers
./vendor/bin/sail up -d

# Stop containers
./vendor/bin/sail down

# View container status
./vendor/bin/sail ps

# View logs
./vendor/bin/sail logs

# Access shell
./vendor/bin/sail shell

Artisan Commands

# Run any artisan command
./vendor/bin/sail artisan migrate
./vendor/bin/sail artisan make:controller UserController
./vendor/bin/sail artisan queue:work

# Or use the alias (if configured)
sartisan migrate
sartisan make:controller UserController
sartisan queue:work

Composer Commands

# Install packages
./vendor/bin/sail composer require package/name

# Update dependencies
./vendor/bin/sail composer update

# Or use the alias (if configured)
scomposer require package/name
scomposer update

NPM Commands

# Install packages
./vendor/bin/sail npm install package-name

# Run scripts
./vendor/bin/sail npm run dev
./vendor/bin/sail npm run build

# Or use the alias (if configured)
snpm install package-name
snpm run dev
snpm run build

Docker Services

Available Services

Sail includes several pre-configured services:

1. Laravel App (laravel.test)

  • Port: 80
  • PHP Version: 8.2
  • Extensions: BCMath, Ctype, cURL, DOM, Fileinfo, JSON, Mbstring, OpenSSL, PCRE, PDO, Tokenizer, XML, GD, MySQL, Redis

2. MySQL (mysql)

  • Port: 3306
  • Version: 8.0
  • Database: laravel
  • Username: sail
  • Password: password

3. Redis (redis)

  • Port: 6379
  • Purpose: Caching and sessions

4. Mailpit (mailpit)

  • Port: 1025 (SMTP), 8025 (Web UI)
  • Purpose: Email testing and debugging

5. Selenium (selenium)

  • Port: 4444
  • Purpose: Browser testing

Service Configuration

docker-compose.yml:

services:
    laravel.test:
        build:
            context: ./vendor/laravel/sail/runtimes/8.2
            dockerfile: Dockerfile
            args:
                WWWGROUP: '${WWWGROUP}'
        image: sail-8.2/app
        ports:
            - '${APP_PORT:-80}:80'
        environment:
            WWWUSER: '${WWWUSER}'
            LARAVEL_SAIL: 1
        volumes:
            - '.:/var/www/html'
        networks:
            - sail
        depends_on:
            - mysql
            - redis

    mysql:
        image: 'mysql/mysql-server:8.0'
        ports:
            - '${FORWARD_DB_PORT:-3306}:3306'
        environment:
            MYSQL_ROOT_PASSWORD: '${DB_PASSWORD}'
            MYSQL_ROOT_HOST: '%'
            MYSQL_DATABASE: '${DB_DATABASE}'
            MYSQL_USER: '${DB_USERNAME}'
            MYSQL_PASSWORD: '${DB_PASSWORD}'
        volumes:
            - 'sail-mysql:/var/lib/mysql'
        networks:
            - sail

Environment Configuration

.env File

Sail uses environment variables to configure services:

# Application
APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:your-app-key
APP_DEBUG=true
APP_URL=http://localhost

# Database
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=sail
DB_PASSWORD=password

# Cache & Sessions
CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

# Mail
MAIL_MAILER=smtp
MAIL_HOST=mailpit
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

Port Configuration

Customize ports in your .env file:

# Custom ports
APP_PORT=8080
FORWARD_DB_PORT=3307
FORWARD_REDIS_PORT=6380
FORWARD_MAILPIT_PORT=8026

Development Workflow

1. Daily Development

# Start your day
./vendor/bin/sail up -d

# Start Vite for assets (in separate terminal)
./vendor/bin/sail npm run dev

# Work on your code
# Files are automatically synced

# Run tests
./vendor/bin/sail test

# End your day
./vendor/bin/sail down

2. Using UltraViolet Setup Scripts

UltraViolet includes convenient setup scripts:

# One-time setup (choose your environment)
./setup.sh

# Start with Sail (recommended)
./run-sail.sh

# Start with local PHP
./run.sh

Setup Script Features:

  • ✅ Automatic environment detection
  • ✅ Docker/Sail vs Local PHP choice
  • ✅ Dependency installation
  • ✅ Database setup
  • ✅ Asset compilation
  • ✅ Permission management

3. Adding Dependencies

# Add PHP package
./vendor/bin/sail composer require spatie/laravel-permission

# Add NPM package
./vendor/bin/sail npm install chart.js

# Rebuild containers if needed
./vendor/bin/sail build --no-cache

4. Database Management

# Run migrations
./vendor/bin/sail artisan migrate

# Seed database with sample data
./vendor/bin/sail artisan db:seed

# Fresh migration + seeding (recommended for development)
./vendor/bin/sail artisan migrate:fresh --seed

# Access database directly
./vendor/bin/sail mysql

# Or use a GUI tool
# Host: localhost
# Port: 3306
# Database: laravel
# Username: sail
# Password: password

Database Reset Commands

# Complete reset (useful for development)
./vendor/bin/sail artisan migrate:fresh --seed

# Rollback last migration
./vendor/bin/sail artisan migrate:rollback

# Reset all migrations
./vendor/bin/sail artisan migrate:reset

Available Seeders

  • DatabaseSeeder - Main seeder that runs all others
  • ChirpSeeder - Sample social media posts for testing
  • UserSeeder - Test users for authentication
  • DemoDataSeeder - Component demo data

Performance Optimization

1. Volume Optimization

For better performance on macOS/Windows, use delegated volumes:

# docker-compose.yml
volumes:
    - '.:/var/www/html:delegated'

2. Xdebug Configuration

Enable Xdebug for debugging:

# Install Xdebug
./vendor/bin/sail artisan sail:install

# Or manually in Dockerfile
RUN pecl install xdebug && docker-php-ext-enable xdebug

3. Memory Limits

Increase PHP memory limit:

# php.ini
memory_limit = 512M

Troubleshooting

Common Issues

1. Port Already in Use

# Check what's using the port
lsof -i :80

# Kill the process
kill -9 <PID>

# Or change the port in .env
APP_PORT=8080

2. Permission Issues

# Fix file permissions
./vendor/bin/sail artisan storage:link
sudo chown -R $USER:$USER .

3. Container Won't Start

# Rebuild containers
./vendor/bin/sail build --no-cache

# Check logs
./vendor/bin/sail logs

# Reset everything
./vendor/bin/sail down -v
./vendor/bin/sail up -d

4. Database Connection Issues

# Check if MySQL is running
./vendor/bin/sail ps

# Restart MySQL
./vendor/bin/sail restart mysql

# Check MySQL logs
./vendor/bin/sail logs mysql

Debugging Commands

# View all container logs
./vendor/bin/sail logs

# View specific service logs
./vendor/bin/sail logs laravel.test
./vendor/bin/sail logs mysql

# Access container shell
./vendor/bin/sail shell

# Check container status
./vendor/bin/sail ps

# View resource usage
docker stats

Advanced Configuration

1. Custom Dockerfile

Create a custom Dockerfile for additional extensions:

# Dockerfile
FROM sail-8.2/app

# Install additional PHP extensions
RUN docker-php-ext-install pdo_mysql

# Install additional system packages
RUN apt-get update && apt-get install -y \
    git \
    curl \
    libpng-dev \
    libonig-dev \
    libxml2-dev \
    zip \
    unzip

# Install Composer dependencies
COPY composer.json composer.lock /var/www/html/
RUN composer install --no-dev --optimize-autoloader

# Copy application code
COPY . /var/www/html

# Set permissions
RUN chown -R sail:sail /var/www/html

2. Multiple Environments

Create different docker-compose files:

# Development
./vendor/bin/sail up -d

# Testing
./vendor/bin/sail -f docker-compose.testing.yml up -d

# Staging
./vendor/bin/sail -f docker-compose.staging.yml up -d

3. Custom Services

Add additional services to docker-compose.yml:

services:
    # Existing services...

    elasticsearch:
        image: 'docker.elastic.co/elasticsearch/elasticsearch:8.5.0'
        ports:
            - '${FORWARD_ELASTICSEARCH_PORT:-9200}:9200'
        environment:
            discovery.type: 'single-node'
        volumes:
            - 'sail-elasticsearch:/usr/share/elasticsearch/data'
        networks:
            - sail

    kibana:
        image: 'docker.elastic.co/kibana/kibana:8.5.0'
        ports:
            - '${FORWARD_KIBANA_PORT:-5601}:5601'
        environment:
            ELASTICSEARCH_HOSTS: 'http://elasticsearch:9200'
        networks:
            - sail

Production Considerations

1. Don't Use Sail in Production

Sail is designed for development only. For production:

  • Use proper Docker orchestration (Kubernetes, Docker Swarm)
  • Use managed services (AWS RDS, ElastiCache)
  • Use proper load balancers and reverse proxies

2. Security

# Don't expose database ports in production
# Remove port mappings from docker-compose.yml

# Use strong passwords
DB_PASSWORD=your-strong-password-here

# Enable SSL/TLS
# Configure proper certificates

3. Performance

# Use production-optimized images
# Enable OPcache
# Use Redis for caching
# Optimize database queries

Bash Aliases (Optional)

For faster development, add these aliases to your ~/.bashrc or ~/.zshrc:

# Sail aliases
alias sail='./vendor/bin/sail'
alias sartisan='./vendor/bin/sail artisan'
alias snpm='./vendor/bin/sail npm'
alias scomposer='./vendor/bin/sail composer'
alias sphp='./vendor/bin/sail php'
alias smysql='./vendor/bin/sail mysql'
alias sredis='./vendor/bin/sail redis'

# UltraViolet specific aliases
alias uv-setup='./setup.sh'
alias uv-sail='./run-sail.sh'
alias uv-local='./run.sh'

After adding aliases:

# Reload your shell
source ~/.bashrc  # or source ~/.zshrc

# Now you can use shorter commands
sartisan migrate
snpm run dev
scomposer require package/name

# UltraViolet shortcuts
uv-setup    # Run setup script
uv-sail     # Start with Sail
uv-local    # Start with local PHP

Common Aliases Usage

# Database operations
sartisan migrate:fresh --seed
sartisan db:seed

# Development
snpm run dev
snpm run build

# Testing
sartisan test
sartisan test --filter=CounterTest

# Package management
scomposer require package/name
scomposer update

Resources

Summary

Key Benefits of Laravel Sail:

  1. ✅ Zero Local Dependencies - No PHP, Composer, or Node.js needed
  2. ✅ Consistent Environment - Same setup across all machines
  3. ✅ Easy Setup - One command to get started
  4. ✅ Isolated Development - No conflicts with other projects
  5. ✅ Production Parity - Closer to production environment
  6. ✅ Easy Cleanup - Remove containers to clean up

When to Use Sail:

  • ✅ New to Laravel development
  • ✅ Working on multiple projects
  • ✅ Team collaboration
  • ✅ Want consistent environment
  • ✅ Don't want to manage local dependencies

When to Use Direct PHP:

  • ✅ Already have PHP 8.2+ installed
  • ✅ Prefer faster startup times
  • ✅ Need local debugging tools
  • ✅ Comfortable managing dependencies

Ready to sail? Run ./setup.sh and then ./run-sail.sh to get started! 🚢

A huement.com Original Project