{"id":471,"date":"2025-08-27T22:43:31","date_gmt":"2025-08-27T22:43:31","guid":{"rendered":"https:\/\/1v0.net\/blog\/?p=471"},"modified":"2025-08-27T22:43:32","modified_gmt":"2025-08-27T22:43:32","slug":"automating-laravel-deployments-with-deployer","status":"publish","type":"post","link":"https:\/\/1v0.net\/blog\/automating-laravel-deployments-with-deployer\/","title":{"rendered":"Automating Laravel Deployments with Deployer"},"content":{"rendered":"\n

Automating Laravel Deployments with Deployer<\/strong><\/h2>\n\n\n\n

Manual deployments invite mistakes: forgotten cache clears, missing assets, downtime during uploads. Deployer<\/strong> is a PHP deployment tool that automates releases with a safe, repeatable, zero-downtime<\/em> flow. In this guide you\u2019ll install Deployer, configure hosts, define tasks (Composer, Vite build, migrations, cache), and wire in a tiny UI to display the current deployed version.<\/p>\n\n\n\n

<\/div>\n\n\n\n

1 \u2014 Install Deployer<\/strong><\/h2>\n\n\n\n

You can install Deployer globally with Composer or use its PHAR. Composer keeps it versioned alongside your toolchain.<\/p>\n\n\n

# Install Deployer globally<\/span>\ncomposer global require deployer\/deployer<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
This makes the dep<\/code> command available on your machine (ensure ~\/.composer\/vendor\/bin<\/code> or ~\/.config\/composer\/vendor\/bin<\/code> is on your PATH). Alternatively, download the PHAR and run php dep.phar<\/code>.<\/p>\n\n\n\n
<\/div>\n\n\n\n
2 \u2014 Initialize in Your Project<\/strong><\/h2>\n\n\n\n
Deployer can scaffold a Laravel-ready config. Run this inside your project root to create deploy.php<\/code>:<\/p>\n\n\n
dep init --template=Laravel<\/code><\/span>Code language:<\/span> Bash<\/span> (<\/span>bash<\/span>)<\/span><\/small><\/pre>\n\n\n
The generated deploy.php<\/code> contains common tasks (Composer install, symlink, caches). You\u2019ll customize hosts, shared files, writable directories, and hooks next.<\/p>\n\n\n\n
<\/div>\n\n\n\n
3 \u2014 Configure Hosts & Paths<\/strong><\/h2>\n\n\n\n
Tell Deployer where to SSH and where releases live on the server. Use a non-root user (e.g., deploy<\/code>) with key-based auth.<\/p>\n\n\n
\/\/ deploy.php (excerpt)<\/span>\nnamespace<\/span> Deployer<\/span>;\n\nrequire<\/span> 'recipe\/laravel.php'<\/span>;\n\nset('application'<\/span>, 'your-app'<\/span>);\nset('repository'<\/span>, 'git@github.com:your-org\/your-repo.git'<\/span>);\nset('keep_releases'<\/span>, 5<\/span>);\n\nhost('your-server.com'<\/span>)\n    ->set('remote_user'<\/span>, 'deploy'<\/span>)\n    ->set('deploy_path'<\/span>, '\/var\/www\/your-app'<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
deploy_path<\/code> will contain releases\/<\/code>, shared\/<\/code>, and a symlink current<\/code>. Each deployment creates a timestamped release and atomically switches current<\/code> to the new one for zero-downtime.<\/p>\n\n\n\n
<\/div>\n\n\n\n
4 \u2014 Shared Files & Writable Directories<\/strong><\/h2>\n\n\n\n
Persist environment files and user data across releases. Mark storage\/cache as writable by the web server user.<\/p>\n\n\n
\/\/ deploy.php (continued)<\/span>\nadd('shared_files'<\/span>, ['.env'<\/span>]);\nadd('shared_dirs'<\/span>,  ['storage'<\/span>]);\nadd('writable_dirs'<\/span>, ['storage'<\/span>, 'bootstrap\/cache'<\/span>]);\nset('writable_mode'<\/span>, 'chmod'<\/span>); \/\/ or 'acl' if setfacl is available<\/span><\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
Deployer creates symlinks from the new release to shared\/<\/code>, so uploads and logs survive code updates. Ensure ownership\/permissions (e.g., www-data<\/code>) are correct on the server.<\/p>\n\n\n\n
<\/div>\n\n\n\n
5 \u2014 Composer, Vite Build & Optimizations<\/strong><\/h2>\n\n\n\n
Hook a build step after Composer, then warm Laravel caches for faster boot times.<\/p>\n\n\n
\/\/ deploy.php (build & optimize hooks)<\/span>\ntask('build'<\/span>, function<\/span> ()<\/span> <\/span>{\n    run('cd {{release_path}} && npm ci --no-audit --no-fund'<\/span>);\n    run('cd {{release_path}} && npm run build'<\/span>);\n});\n\nafter('deploy:vendors'<\/span>, 'build'<\/span>);\n\ntask('artisan:optimize'<\/span>, function<\/span> ()<\/span> <\/span>{\n    run('cd {{release_path}} && php artisan config:cache && php artisan route:cache && php artisan view:cache'<\/span>);\n});\n\nafter('artisan:migrate'<\/span>, 'artisan:optimize'<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
npm ci<\/code> ensures reproducible installs; npm run build<\/code> compiles your assets (Vite). Running Laravel\u2019s cache commands after migrations keeps the app snappy on first request.<\/p>\n\n\n\n
<\/div>\n\n\n\n
6 \u2014 Database Migrations & Queues<\/strong><\/h2>\n\n\n\n
Migrate safely during deploy, then restart workers so they load new code. If you use Horizon, call its artisan command.<\/p>\n\n\n
\/\/ deploy.php (migrate & queues)<\/span>\nafter('deploy:symlink'<\/span>, 'artisan:migrate'<\/span>); \/\/ Deployer's recipe uses --force in prod<\/span>\n\ntask('queue:restart'<\/span>, function<\/span> ()<\/span> <\/span>{\n    run('cd {{release_path}} && php artisan queue:restart'<\/span>);\n});\nafter('deploy:symlink'<\/span>, 'queue:restart'<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
artisan migrate<\/code> runs with --force<\/code> in production to apply schema changes. queue:restart<\/code> signals workers to gracefully restart and pick up the new code without killing in-flight jobs.<\/p>\n\n\n\n
<\/div>\n\n\n\n
7 \u2014 Expose Version & Rollbacks<\/strong><\/h2>\n\n\n\n
Write the current Git commit to a file during deploy, show it in an admin page, and keep a few releases for quick rollbacks.<\/p>\n\n\n
\/\/ deploy.php (version stamp)<\/span>\ntask('app:stamp_version'<\/span>, function<\/span> ()<\/span> <\/span>{\n    run('cd {{release_path}} && git rev-parse --short HEAD > REVISION || echo $(date +%s) > REVISION'<\/span>);\n});\nafter('deploy:symlink'<\/span>, 'app:stamp_version'<\/span>);<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This stores a short commit hash (or timestamp) in REVISION<\/code> so you can see exactly what\u2019s live. Deployer also keeps previous releases; revert quickly with dep rollback<\/code>.<\/p>\n\n\n
\/\/ routes\/web.php (admin-only version page)<\/span>\nuse<\/span> Illuminate<\/span>\\\\Support<\/span>\\\\Facades<\/span>\\\\Gate<\/span>;\n\nRoute::middleware(['auth'<\/span>])->get('\/admin\/version'<\/span>, function<\/span> ()<\/span> <\/span>{\n    abort_unless(Gate::allows('viewAdmin'<\/span>), 403<\/span>);\n    $revision = base_path('REVISION'<\/span>);\n    $value = file_exists($revision) ? trim(file_get_contents($revision)) : 'unknown'<\/span>;\n    return<\/span> view('admin.version'<\/span>, ['revision'<\/span> => $value]);\n});<\/code><\/span>Code language:<\/span> PHP<\/span> (<\/span>php<\/span>)<\/span><\/small><\/pre>\n\n\n
This route reads the REVISION<\/code> file (written at deploy time) and displays it for admins. It\u2019s helpful when correlating bug reports to a specific release.<\/p>\n\n\n
<!-- resources\/views\/admin\/version.blade.php --><\/span>\n@extends('layouts.app')\n@section('content')\n<div<\/span> class<\/span>=\"container\"<\/span>><\/span>\n  <h1<\/span> class<\/span>=\"mb-4\"<\/span>><\/span>Deployed Version<\/h1<\/span>><\/span>\n  <p<\/span>><\/span><strong<\/span>><\/span>Revision:<\/strong<\/span>><\/span> {{ $revision }}<\/p<\/span>><\/span>\n  <p<\/span> class<\/span>=\"text-muted\"<\/span>><\/span>Tip: Keep 5 recent releases to enable fast rollbacks with Deployer.<\/p<\/span>><\/span>\n<\/div<\/span>><\/span>\n@endsection<\/code><\/span>Code language:<\/span> HTML, XML<\/span> (<\/span>xml<\/span>)<\/span><\/small><\/pre>\n\n\n
Keeping version info visible reduces confusion across teams and speeds up incident response. Since releases are kept on disk, you can roll back instantly if a migration or bug slips through.<\/p>\n\n\n\n
<\/div>\n\n\n\n
8 \u2014 CI\/CD Integration (Optional)<\/strong><\/h2>\n\n\n\n
Trigger deployments from your pipeline after tests and builds pass. A common pattern is: test \u2192 build assets \u2192 create release artifact \u2192 dep deploy<\/code>. For a full pipeline walkthrough, see Step-by-Step CI\/CD Pipeline Setup for Laravel 12 on GitHub Actions<\/a>.<\/p>\n\n\n
# .github\/workflows\/deploy.yml (excerpt)<\/span>\nname:<\/span> Deploy<\/span>\non:<\/span>\n  workflow_dispatch:<\/span>\n  push:<\/span>\n    branches:<\/span> [<\/span> \\\"main\\\"<\/span> ]<\/span>\n\njobs:<\/span>\n  deploy:<\/span>\n    runs-on:<\/span> ubuntu-latest<\/span>\n    steps:<\/span>\n      -<\/span> uses:<\/span> actions\/checkout@v4<\/span>\n      -<\/span> uses:<\/span> shivammathur\/setup-php@v2<\/span>\n        with:<\/span>\n          php-version:<\/span> '8.3'<\/span>\n      -<\/span> name:<\/span> Install<\/span> Deployer<\/span>\n        run:<\/span> composer<\/span> global<\/span> require<\/span> deployer\/deployer<\/span>\n      -<\/span> name:<\/span> Deploy<\/span> to<\/span> Production<\/span>\n        env:<\/span>\n          SSH_AUTH_SOCK:<\/span> \/tmp\/ssh_agent.sock<\/span>\n        run:<\/span> ~\/.composer\/vendor\/bin\/dep<\/span> deploy<\/span> production<\/span> -n<\/span><\/code><\/span>Code language:<\/span> YAML<\/span> (<\/span>yaml<\/span>)<\/span><\/small><\/pre>\n\n\n
This minimal workflow installs PHP and Deployer, then executes dep deploy<\/code>. Use OIDC\/SSH keys securely via repository secrets; add caching for speed as needed.<\/p>\n\n\n\n
<\/div>\n\n\n\n
Wrapping Up<\/h2>\n\n\n\n
Deployer brings reproducible, zero-downtime releases to your Laravel stack: atomic symlinks, shared storage, safe migrations, warmed caches, and quick rollbacks. Add a small version UI for visibility and trigger the process from CI\/CD to move fast without breaking prod.<\/p>\n\n\n\n
<\/div>\n\n\n\n
What\u2019s Next<\/h2>\n\n\n\n