{"id":13462605,"url":"https://github.com/papertank/envoy-deploy","last_synced_at":"2026-02-06T23:04:55.428Z","repository":{"id":28892711,"uuid":"32417400","full_name":"papertank/envoy-deploy","owner":"papertank","description":"Laravel Envoy Deployment","archived":false,"fork":false,"pushed_at":"2022-11-14T10:58:03.000Z","size":59,"stargazers_count":425,"open_issues_count":0,"forks_count":86,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-03-25T02:36:43.470Z","etag":null,"topics":["laravel-envoy"],"latest_commit_sha":null,"homepage":null,"language":"Blade","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/papertank.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-03-17T20:08:53.000Z","updated_at":"2025-02-18T14:46:16.000Z","dependencies_parsed_at":"2022-08-07T14:00:55.131Z","dependency_job_id":null,"html_url":"https://github.com/papertank/envoy-deploy","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/papertank/envoy-deploy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertank%2Fenvoy-deploy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertank%2Fenvoy-deploy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertank%2Fenvoy-deploy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertank%2Fenvoy-deploy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/papertank","download_url":"https://codeload.github.com/papertank/envoy-deploy/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/papertank%2Fenvoy-deploy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29179579,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-06T22:12:24.066Z","status":"ssl_error","status_checked_at":"2026-02-06T22:12:09.859Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["laravel-envoy"],"created_at":"2024-07-31T12:00:53.479Z","updated_at":"2026-02-06T23:04:55.404Z","avatar_url":"https://github.com/papertank.png","language":"Blade","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Laravel Envoy Deploy\n\nThis repository includes an Envoy.blade.php script that is designed to provide a basic \"zero-downtime\" deployment option using the open-source [Laravel Envoy](https://laravel.com/docs/envoy) tool.\n\n## Requirements\n\nThis Envoy script is designed to be used with Laravel 7+ projects and can be used within the Laravel root, or downloaded separately and included in your Laravel project.\n\n## Installation\n\nYour must have Envoy installed using the Composer global command:\n\n\tcomposer global require \"laravel/envoy\"\n\n### Standalone\n\nTo download and run out-with your Laravel project, clone this directory and do a composer install.\n\n### Laravel\n\n#### Laravel 9+\n\nTo use within an existing Laravel 8+ project, you simply need to download the version 5 `Envoy.blade.php` file to your project root:\n\n```\nwget https://raw.githubusercontent.com/papertank/envoy-deploy/master/Envoy.blade.php\n```\n\n#### Laravel 7+\n\nTo use within an existing Laravel 7+ project, you simply need to download the version 4 `Envoy.blade.php` file to your project root:\n\n```\nwget https://raw.githubusercontent.com/papertank/envoy-deploy/v4/Envoy.blade.php\n```\n\n#### Laravel 5-6\n\nTo use within an existing Laravel 5 or 6 project, you simply need to download the version 2 `Envoy.blade.php` file to your project root:\n\n```\nwget https://raw.githubusercontent.com/papertank/envoy-deploy/v2/Envoy.blade.php\n```\n\n## Setup\n\n### Config\n\nEnvoy Deploy uses [DotEnv](https://github.com/vlucas/phpdotenv) to fetch your server and repository details. If you are installing within a Laravel project, there will already be a `.env` file in the root, otherwise simply create one.\n\nThe following configuration items are required:\n\n  - `DEPLOY_SERVER`\n  - `DEPLOY_REPOSITORY`\n  - `DEPLOY_PATH`\n\nFor example, deploying the standard Laravel repository on a Forge server, we might use:\n\n```\nDEPLOY_SERVER=forge@example.com\nDEPLOY_REPOSITORY=https://github.com/laravel/laravel.git\nDEPLOY_PATH=/home/forge/example.com\nDEPLOY_HEALTH_CHECK=https://example.forge.com\n```\n\nThe `DEPLOY_PATH` (server path) should already be created in your server and must be a blank directory.\n\n### Host\n\nEnvoy Deploy uses symlinks to ensure that your server is always running from the latest deployment. As such you need to setup your Apache or Nginx host to point towards the `host/current/public` directory rather than simply `host/public`.\n\nFor example:\n\n```\nserver {\n    listen 80;\n    server_name example.com;\n    root /home/forge/example.com/current/public;\n\n    location / {\n        try_files $uri $uri/ /index.php?$query_string;\n    }\n\n    location ~ \\.php$ {\n        fastcgi_split_path_info ^(.+\\.php)(/.+)$;\n        fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;\n        fastcgi_index index.php;\n        include fastcgi_params;\n        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;\n        fastcgi_param DOCUMENT_ROOT $realpath_root;\n    }\n\n    location ~ /\\.ht {\n        deny all;\n    }\n}\n```\n\n## Usage\n\n### Init\n\nWhen you're happy with the config, run the init task on your local machine by running the following.\n\n\tenvoy run init\n\nYou only need to run the init task once.\n\nThe init task creates a `.env` file in your root path (from your `.env.example` file), so make sure and update the environment variables appropriately. Once you have run the init task, you should proceed to run the deploy task (below).\n\n### Deploy\n\nEach time you want to deploy simply run the deploy task on your local machine in the repository direcory\n\n\tenvoy run deploy\n\nYou can specify the Laravel environment (e.g. for artisan:migrate command) and git branch as options\n\n\tenvoy run deploy --branch=develop --env=development\n\n### Deploy with Cleanup\n\nIf you could like to deploy your repository and cleanup any old deployments at the same time, you can run\n\n\tenvoy run deploy --cleanup\n\nThis will run the deploy script and then delete any old deployments older than 48 hours, leaving at least 4.\n\nYou can also run the cleanup script independently (without deploying) using\n\n\tenvoy run deployment_cleanup\n\n### Deploy with Maintenance Mode\n\nAlthough this script is designed to use zero-downtime deployments, you can activate Laravel's maintenance mode while deploying by using the down option:\n\n\tenvoy run deploy --down\n\n### Health Check\n\nIf you would like to perform a health check (for 200 response) after deploying, simply add your site's URL in the .env file:\n\n```\nDEPLOY_HEALTH_CHECK=https://example.forge.com\n```\n\n### Rollback\n\nTo rollback to the previous deployment (e.g. when a health check fails), you can simply run \n\n\tenvoy run rollback\n\n## Commands\n\n#### `envoy run init`\n\nInitialise server for deployments\n\n    Options\n        --env=ENVIRONMENT        The environment to use. (Default: \"production\")\n        --branch=BRANCH          The git branch to use. (Default: \"master\")\n\n#### `envoy run deploy`\n\nRun new deployment\n\n    Options\n        --env=ENVIRONMENT        The environment to use. (Default: \"production\")\n        --branch=BRANCH          The git branch to use. (Default: \"master\")\n        --cleanup                Whether to cleanup old deployments\n        --down\t\t\t\t\t Enable maintenance mode\n\n#### `envoy run deployment_cleanup`\n\nDelete any old deployments, leaving just the last 4.\n\n#### `envoy run rollback`\n\nIn case the health check does not work, you can rollback and it will use the previous deploy.\n\n## How it Works\n\nYour `$path` directory will look something like this after you init and then deploy.\n\n\treleases/\n\tcurrent -\u003e ./releases/20220103125914\n\tstorage/\n\t.env\n\nAs you can see, the *current* directory is symlinked to the latest deployment folder\n\nInside one of your deployment folders looks like the following (excluded some laravel folders for space)\n\n\tapp/\n\tartisan\n\tboostrap/\n\tcomposer.json\n\t.env -\u003e ../.env\n\tstorage -\u003e ../storage\n\tvendor/\n\nThe deployment folder .env file and storage directory are symlinked to the parent folders in the main (parent) path.\n\n## Optional Features\n\n### Restart Queue Workers\n\nIf you use Laravel's queue daemon, you should set the following environment variable to `true` to automatically run `php artisan artisan queue:restart`\n\n```\nDEPLOY_RESTART_QUEUE=true\n```\n\nAlternatively, if you use [Laravel Horizon](https://laravel.com/docs/9.x/horizon) for your Redis queue management, you should set the value to `horizon` to automatically `php artisan horizon:terminate`\n\n```\nDEPLOY_RESTART_QUEUE=\"horizon\"\n```\n\n### Reload PHP FPM\n\nIf you use something like OPCache, you should reload the PHP FPM service at the end of each deployment.\n\nSimply update the following environment variable to your PHP-FPM service name, which will automatically run `sudo -S service  php8.1-fpm reload`\n\n```\nDEPLOY_PHP_FPM=\"php8.1-fpm\"\n```\n\n### Multiple PHP Versions\n\nIf you use multiple PHP versions on your server (e.g. with Laravel Forge) and are not with the default version, you should update your environment variables to specify the version and binaries. For example:\n\n```\nDEPLOY_PHP_CMD=\"/usr/bin/php7.4\"\nDEPLOY_COMPOSER_CMD=\"/usr/bin/php7.4 /usr/local/bin/composer\"\nDEPLOY_PHP_FPM=\"php7.4-fpm\"\n```\n\n\n### Laravel Mix / NPM\n\nIf you use Laravel mix / npm dependencies in your project, you should add the (disabled by default) `deployment_npm` task to the deploy story. For example:\n\n```\n@story('deploy')\n\tdeployment_start\n\tdeployment_links\n\tdeployment_composer\n\tdeployment_npm\n\tdeployment_migrate\n\tdeployment_cache\n\tdeployment_symlink\n\tdeployment_reload\n\tdeployment_finish\n\thealth_check\n\tdeployment_option_cleanup\n@endstory\n```\n\nIf you only use Laravel mix for asset compilation and don't use any node scripts after deployment, you can update your deployment script to remove the node_modules folder and save some disk space on old deployments:\n\n```\n@task('deployment_npm')\n\techo \"Installing npm dependencies...\"\n\tcd {{ $release }}\n\tnpm install --no-audit --no-fund --no-optional\n\techo \"Running npm...\"\n\tnpm run {{ $env }} --silent\n\trm -rf {{ $release }}/node_modules\n@endtask\n```\n\n## Disclaimer\n\nBefore using on live server, it is best to test on a local VM (like [Laravel Homestead](https://laravel.com/docs/8.x/homestead)) first.\n\n## Changes\nV5.0\n- Added $php and $composer variables to allow binary paths to be updated.\n- Added $releases variable for /releases path.\n- Added optional $php_fpm variable (DEPLOY_PHP_FPM env variable) to reload FPM service.\n- Added --down option to enable maintenance mode.\n- Added deployment_reload task. \n- Added $restartQueue variable (DEPLOY_RESTART_QUEUE env variable) to restart queue / horizon.\n\nV4.1\n- Added fastcgi_param SCRIPT_FILENAME and DOCUMENT_ROOT variables (for better nginx symlink handling).\n\nV4.0\n- Added optional deployment_npm task (disabled by default).\n- Tidied up deployments into releases folder.\n- Removed deploy_cleanup story to simplify - use 'envoy run deploy --cleanup'.\n- Removed storage/public link and replaced with 'php artisan storage:link' command.\n\nV3.0\n- Updated DotEnv to \"^4.0\" for Laravel 7 compatibility.\n\nV2.2\n- Added `health_check` task and config.\n- Added `rollback` task to update current to previous deployment.\n- Updated `cleanup` to delete old deploys and leave last 4.\n- Removed `deployment_optimize` task (no longer needed for Laravel 5 projects).\n- Updated `deployment_composer` to use `--prefer-dist --optimize-autoloader` options.\n\nV2.1 - Updated init to only initialize (rather than deploy).\n\nv2.0 - Switched to using DotEnv (removing `envoy.config.php`) and cleaned up tasks/stories.\n\nv1.0.1 - Added `cleanup` task and `deploy_cleanup` macro after changing cleanup command.\n\n## Contributing\n\nPlease submit improvements and fixes :)\n\n## Credits\n\n * [Servers for Hackers](https://serversforhackers.com/video/enhancing-envoy-deployment) for inspiration\n * [@noeldiaz on Laracasts](https://laracasts.com/@noeldiaz) for deployment cleanups idea\n * [Harmen Stoppels](https://serversforhackers.com/video/enhancing-envoy-deployment#comment-1900893160) for cloning HEAD only\n * [Jordi Puigdellívol @badchoice](https://github.com/BadChoice) for V2.2 updates (health check and rollback).\n\n\n## Author\n\n[Papertank Limited](http://papertank.co.uk)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapertank%2Fenvoy-deploy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpapertank%2Fenvoy-deploy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpapertank%2Fenvoy-deploy/lists"}