​

How to migrate from Laravel Sail to Herd

If you’re currently using Laravel Sail for local development and want to switch to Herd, this guide will walk you through the migration process. While both tools provide excellent development environments, they have different approaches to managing services and dependencies.

​

Understanding the Differences

Laravel Sail uses Docker containers to provide isolated development environments, while Herd takes a native approach by running services directly on your machine. Here are the key differences:

​

Migration Steps

​

1. Stop Sail Services

Before switching to Herd, make sure to stop all running Sail containers:

./vendor/bin/sail down

​

2. Install Herd

Download and install Herd from the official website. Follow the installation instructions to get Herd up and running on your machine.

​

3. Update Environment Configuration

Your .env file likely contains Docker-specific configurations. Here’s how to update common settings:

​

Database Configuration

If you’re using MySQL:

# From Sail
DB_HOST=mysql
DB_PORT=3306

# To Herd
DB_HOST=127.0.0.1
DB_PORT=3306 # Default Herd MySQL port

​

Redis Configuration

If you’re using Redis:

# From Sail
REDIS_HOST=redis

# To Herd
REDIS_HOST=127.0.0.1

​

Mail Configuration

If you’re using Mailhog with Sail, switch to Herd’s mail service:

# From Sail
MAIL_HOST=mailhog
MAIL_PORT=1025

# To Herd
MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=${APP_NAME}
MAIL_PASSWORD=null
MAIL_ENCRYPTION=null

​

4. Set Up Required Services

Review your docker-compose.yml file to identify which services your application needs. Common services include:

• Database (MySQL/PostgreSQL)
• Redis
• Meilisearch

For Herd Pro users, you can install these services via the Services tab in settings. Free version users should install these services separately.

​

5. Remove Sail Dependencies

You can now remove Sail from your project:

composer remove laravel/sail --dev

Also, clean up Sail-related files:

• docker-compose.yml
• docker/ directory
• Any custom Dockerfile configurations

​

6. Update Development Scripts

Update your composer.json scripts section to remove Sail commands. For example:

{
    "scripts": {
        // Remove these Sail-based scripts
        "sail:up": "./vendor/bin/sail up -d",
        "sail:down": "./vendor/bin/sail down"
    }
}

​

7. Create Herd Configuration (optional)

Create a herd.yml file in your project root to define project-specific configurations either manually or by running herd init:

name: your-project-name
php: '8.3'
services:
    mysql:
        version: 8.0.36
        port: '${DB_PORT}'
    redis:
        version: 7.0.0
        port: '${REDIS_PORT}'

​

8. Initialize the Project

Initialize your project with Herd:

herd init

This command will configure your project according to the herd.yml file and set up any required services.

​

Common Challenges

​

Database Migration

If you need to migrate your data from Sail’s MySQL container:

1. Export your database from Sail:

./vendor/bin/sail mysql --execute="SHOW DATABASES" > databases.txt
./vendor/bin/sail mysqldump your_database > database_backup.sql

2. Import into Herd’s MySQL:

mysql -u root -P 3306 -h 127.0.0.1 -e "CREATE DATABASE your_database_name;"
mysql -u root -P 3306 -h 127.0.0.1 your_database_name < database_backup.sql

​

File Permissions

Since Herd runs services natively rather than in containers, you might need to adjust file permissions:

chmod -R 755 storage bootstrap/cache

​

Using Herd in a Team

When working with a team, make sure to:

1. Share your herd.yml configuration file via version control
2. Document any specific service requirements
3. Standardize PHP versions across the team

​

Getting Help

If you encounter issues during migration:

1. Check the troubleshooting guides
2. Join the community support

Herd Pro users can also access priority email support for migration assistance.