How to migrate Laravel 13 + Next.js to Zero-Downtime VPS Releases
Part 9 of the CI/CD for Laravel Developers series. Migrate Laravel 13 + Next.js to zero-downtime VPS releases in under 20 minutes — no downtime during the migration itself. This post is part of the DevOps series on deploying Laravel and Next.js with GitHub Actions. Most tutorials assume you're starting from scratch. This one assumes you already have a live project at /var/www/your-project and…
Migrating Laravel 13 with Next.js to a zero-downtime VPS release involves several steps, ensuring no downtime during the process. The tutorial assumes you have a live Laravel 13 API project and Next.js 16 frontend running on an Ubuntu VPS. The goal is to move the project to a releases/symlink pattern, allowing GitHub Actions to deploy atomically.
Key steps include:
1. **Pausing Queue Workers:** Before starting, stop any queue workers to prevent disruption. Use `php artisan queue:restart` for Laravel or `php artisan horizon:pause` if using Laravel Horizon.
2. **Creating Structure:** Set up a `releases/` and `shared/` directory for storing each deployment and shared files like `.env` and `storage`, respectively. Ensure `storage` has proper permissions (`sudo chown -R www-data:www-data shared/storage && sudo chmod -R 775 shared/storage`).
3. **Backing Up Existing App:** Copy the existing Laravel 13 app to `releases/initial/` as a backup to restore if needed.
4. **Moving `.env` and `storage`:** Move the `.env` file and `storage` directory to the `shared/` directory to ensure it remains consistent across releases.
5. **Symlinking Files:** Replace the `api` directory with a symlink to the `initial/` release, pointing to the shared files for consistency. Use `ln -sfn /var/www/visa-saas/shared/storage storage` and `ln -sfn /var/www/visa-saas/shared/.env .env`.
6. **Replacing `api/` with a Symlink:** Rename the original `api/` directory to `api-backup` and create a symlink to the `initial/` release. Verify the symlink by checking the file structure.
7. **Verifying Nginx Configuration:** Ensure Nginx follows the symlink correctly. Test the configuration with `sudo nginx -t` and reload Nginx using `sudo systemctl reload nginx`.
8. **Removing Backup:** Once confirmed, delete the `api-backup` directory to clean up.
9. **Updating GitHub Actions:** Modify the GitHub Actions script to reflect the new symlink-based deployment process, ensuring deployments are atomic and seamless.
Following these steps ensures a smooth migration with minimum downtime, using the releases/symlink pattern effectively for Laravel and Next.js projects on VPS.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
