Laravel Deployer is a deployment automation tool designed to simplify and automate the deployment of Laravel applications. It allows you to deploy code to your server seamlessly and efficiently, with support for features like atomic deployments, parallel execution, and rollbacks.
Key Features:
- Zero-Downtime Deployments: Ensure your application stays online while deploying new code.
- Automated Tasks: Automate common deployment tasks like updating dependencies, running migrations, and clearing caches.
- Rollback Support: Easily roll back to a previous release if something goes wrong.
- Parallel Execution: Run tasks across multiple servers in parallel for speed and efficiency.
Installation and Setup
1. Install Deployer
You can use Deployer via Composer by installing it as a dependency in your Laravel project:
|
1 |
composer require deployer/deployer --dev |
Alternatively, you can install it globally:
|
1 |
composer global require deployer/deployer |
2. Initialize Deployer
To set up Deployer in your Laravel project, run the following command to create the deploy.php file, which contains the configuration for your deployment:
|
1 |
dep init |
This command will prompt you to select the type of deployment you want. Choose Laravel from the list of templates.
3. Configure Deployment
The deploy.php file will be created in the root of your Laravel project. It contains all the configurations and tasks that will be executed during deployment.
Here’s an example configuration file:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
<?php namespace Deployer; require 'recipe/laravel.php'; // Project name set('application', 'my-laravel-app'); // Project repository set('repository', 'git@github.com:username/repository.git'); // [Optional] Allocate tty for git clone. Default value is false. set('git_tty', true); // Shared files/dirs between deploys add('shared_files', []); add('shared_dirs', []); // Writable dirs by web server add('writable_dirs', []); // Hosts host('your-server.com') ->set('deploy_path', '/var/www/my-laravel-app'); // Tasks task('build', function () { run('cd {{release_path}} && build'); }); // [Optional] If deploy fails, automatically unlock. after('deploy:failed', 'deploy:unlock'); // Migrate database before symlinking new release. before('deploy:symlink', 'artisan:migrate'); |
Deployment Workflow
A typical deployment with Laravel Deployer involves the following steps:
- Clone the repository: Deployer will pull the latest code from your Git repository.
- Install dependencies: Composer dependencies will be installed on the server.
- Run migrations: Laravel database migrations will be executed to keep the database schema up to date.
- Symlink the new release: The new release is symlinked to the current directory to make it live.
- Clear cache: Laravel’s cache will be cleared to ensure the application runs with the latest configurations and data.
Running Deployments
Once your deploy.php configuration is ready, you can run the deployment process with:
|
1 |
dep deploy |
This will execute the deployment to the server specified in the deploy.php configuration.
Rollbacks
If something goes wrong during deployment, you can quickly roll back to the previous version using the following command:
|
1 |
dep rollback |
This will restore the symlink to point to the previous release, effectively rolling back the application.
Custom Tasks
You can also define custom tasks in the deploy.php file. For example, if you want to clear the cache after deployment, you can create a custom task like this:
|
1 2 3 |
task('artisan:cache:clear', function () { run('php {{release_path}}/artisan cache:clear'); }); |
Then, hook it into the deployment process:
|
1 |
after('deploy:symlink', 'artisan:cache:clear'); |
Additional Features
- Parallel Execution: Deployer can run tasks across multiple servers in parallel for faster deployment.
- Zero-Downtime Deployments: By using atomic symlinking, Deployer ensures that your application remains available during deployment.
- Notifications: You can integrate notifications (Slack, Telegram, etc.) to notify your team when deployments succeed or fail.
Conclusion
Laravel Deployer simplifies the process of deploying Laravel applications by automating repetitive tasks and providing features like rollback and zero-downtime deployments. With minimal configuration, you can quickly set up automated deployments, ensuring your application is consistently deployed and available.
Output
The output of using Laravel Deployer is generally seen during and after the deployment process.
1. Command-Line Output During Deployment
When you run the deployment command (dep deploy), Deployer will output the progress of each task in the terminal:
Example command:
|
1 |
dep deploy |
The command-line output will look something like this:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
➤ Executing task deploy:prepare ✔ Executing task deploy:prepare ➤ Executing task deploy:lock ✔ Executing task deploy:lock ➤ Executing task deploy:release ✔ Executing task deploy:release ➤ Executing task deploy:update_code ✔ Executing task deploy:update_code ➤ Executing task deploy:shared ✔ Executing task deploy:shared ➤ Executing task deploy:vendors ✔ Executing task deploy:vendors ➤ Executing task artisan:migrate ✔ Executing task artisan:migrate ➤ Executing task deploy:symlink ✔ Executing task deploy:symlink ➤ Executing task deploy:unlock ✔ Executing task deploy:unlock ➤ Executing task cleanup ✔ Executing task cleanup ✔ Successfully deployed! |
2. Error Output
If there are any issues during deployment, Deployer will show error messages in the terminal. For example, if there’s a problem with permissions on the server, you might see an error like this:
|
1 2 3 4 5 6 7 8 |
➤ Executing task deploy:vendors In Client.php line 103: [Deployer\Exception\RuntimeException (-1)] The command "cd /var/www/my-laravel-app/releases/5 && (which git)" failed. Exit Code: 1 (General error) Host: your-server.com ================ Permission denied |
3. Log Files on the Server
Deployer creates a releases directory on the server where it stores all the release versions of your application. Each release has its own directory named with a timestamp. You can view logs for each release by checking the deployment log files (if logging is enabled) or looking at Laravel’s logs in the storage/logs/laravel.log file.
4. Rollback Output
If you perform a rollback with:
|
1 |
dep rollback |
The output will show the rollback steps:
|
1 2 |
➤ Executing task rollback ✔ Rolled back to previous release: /var/www/my-laravel-app/releases/4 |
This confirms that the symlink has been switched back to the previous release.
5. After Deployment: Viewing the Deployed App
Once deployment is completed, you can view your live application by visiting the domain associated with your server (e.g., https://your-app.com). The changes from the new release will be live, and any deployment tasks like database migrations, cache clearing, or asset compilation will have taken effect.
Summary of Outputs:
- Terminal Output: During deployment, the terminal provides real-time feedback on tasks being executed.
- Error Output: If something fails, error messages are shown in the terminal.
- Server Log Files: Check the
storage/logs/laravel.logfor detailed logs about your application after deployment. - Application: You’ll see the final deployed version of your Laravel app by visiting your server or domain.