How to Migrate a Laravel Application to a New Server

How to Migrate a Laravel Application to a New Server

Laravel applications have specific directory structures, dependencies, and configurations that must be carefully handled during migration. This guide walks through transferring a Laravel app to a new Breeze instance while preserving all functionality.

Prerequisites

• A Breeze instance with PHP 8.1+, Composer, and a web server installed
• The required PHP extensions: OpenSSL, PDO, Mbstring, Tokenizer, XML, Ctype, JSON, BCMath
• MySQL or PostgreSQL available on the new Breeze
• Redis if your application uses it for caching or queues

Step 1: Transfer Application Code

Copy your Laravel project to the new Breeze, excluding vendor dependencies and local environment files:

rsync -avz --exclude='vendor/' --exclude='node_modules/' --exclude='.env' \
  --exclude='storage/logs/*' --exclude='storage/framework/cache/*' \
  user@source-ip:/var/www/myapp/ /var/www/myapp/

Step 2: Install Dependencies

On the new Breeze, install PHP and JavaScript dependencies:

cd /var/www/myapp
composer install --optimize-autoloader --no-dev
npm ci && npm run build

Step 3: Configure the Environment

Copy your .env file to the Breeze and update all environment-specific values:

APP_URL=https://yourdomain.com
DB_HOST=127.0.0.1
DB_DATABASE=myapp
DB_USERNAME=myapp_user
DB_PASSWORD=secure_password

CACHE_DRIVER=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis

REDIS_HOST=127.0.0.1

Generate a new application key if you are not carrying over the existing one:

php artisan key:generate

Step 4: Migrate the Database

Export the database from the source server and import it on the Breeze:

# Source server
mysqldump -u root -p --single-transaction myapp > myapp.sql

# New Breeze
mysql -u root -p -e "CREATE DATABASE myapp; GRANT ALL ON myapp.* TO 'myapp_user'@'localhost' IDENTIFIED BY 'secure_password';"
mysql -u root -p myapp < myapp.sql

Run any pending migrations to ensure the schema is up to date:

php artisan migrate --force

Step 5: Set Up Storage and Permissions

Laravel requires specific directories to be writable. Set the correct permissions:

sudo chown -R www-data:www-data /var/www/myapp
sudo chmod -R 775 storage/ bootstrap/cache/
php artisan storage:link

If your application stores user uploads in storage/app/public, ensure those files were transferred and the symbolic link is created.

Step 6: Configure the Web Server

Point Nginx to Laravel's public directory:

server {
    listen 80;
    server_name yourdomain.com;
    root /var/www/myapp/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        include snippets/fastcgi-php.conf;
    }
}

Step 7: Optimize and Cache

Run Laravel's optimization commands for production performance:

php artisan config:cache
php artisan route:cache
php artisan view:cache

Step 8: Set Up Queue Workers and Scheduler

If your app uses queues, configure Supervisor to run queue workers on the Breeze. Add the Laravel scheduler to crontab:

* * * * * cd /var/www/myapp && php artisan schedule:run >> /dev/null 2>&1

Test all scheduled tasks and queue jobs to ensure they run correctly on the new server.