Download the PHP package innocenzi/deployer-recipe-forge without Composer

Forge recipe for Deployer

Seamless zero-downtime deployment on Forge with Deployer

composer require --dev innocenzi/deployer-recipe-forge

  # About `deployer-recipe-forge` is a recipe for [Deployer](https://deployer.org/) that helps implementing zero-downtime on [Laravel Forge](https://forge.laravel.com/servers). It uses [Forge's API](https://forge.laravel.com/api-documentation) to fetch a site's credentials, such as its IP address and the remote username, so you don't have to hardcode them in your `deploy.php`. It automatically finds the right Forge site using your repository's name, so the only configuration to do happens on Forge. Additionally, it's able to send notifications on Slack with either [Deployer's integration](https://deployer.org/docs/7.x/contrib/slack), which requires that you setup a webhook, or by pinging [Forge's deployment URL](https://forge.laravel.com/docs/sites/deployments.html#using-deployment-triggers).   # Installation Install the package as a development dependency:   Then, create a `deploy.php` file at the root of your project. [Import the autoloader](https://github.com/deployphp/deployer/issues/3605), and call `\Deployer\Forge::make()->configure();`. You may then customize your deployment script as usual with Deployer.   # Usage ## Setting up the repository This recipe is designed to be used within a GitHub workflow, using the [action provided by Deployer](https://github.com/deployphp/action). Setting it up requires at least two [repository secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository): - Your server's _private_ SSH key, which will be used by `deployphp/action` to SSH - Your [Forge API token](https://forge.laravel.com/docs/accounts/api.html), which will be used by the recipe to fetch your site and server's credentials These repository secrets must then be forwarded to the action as environment variables, or, for the SSH key, as the `private-key` argument:   > [!WARNING] > Note that the `REPOSITORY_BRANCH` and `REPOSITORY_NAME` variables are required for the recipe to work, since they are used to match your site and branch to your site Forge. > [!NOTE] > For convenience, if you are using a paid GitHub plan, you may setup your Forge API token and Slack webhook as [organization-wide secrets](https://docs.github.com/en/codespaces/managing-codespaces-for-your-organization/managing-secrets-for-your-repository-and-organization-for-github-codespaces#adding-secrets-for-an-organization).   ## Setting up Forge ### Creating a new site The following steps explain how to setup a new site on Forge to work with this recipe on GitHub Actions. 1. Create an [isolated](https://forge.laravel.com/docs/sites/user-isolation.html#overview) site. > Currently, this recipe only works with isolated Forge sites. You must then create an isolated site. 2. Install the repository using the [GitHub integration](https://forge.laravel.com/docs/sites/the-basics.html#git-repository). > You may uncheck "install composer dependencies" to make the installation faster, as the site directory will be erased anyway.
> If you haven't [associated the server's deploy key with your GitHub repository](https://forge.laravel.com/docs/servers/ssh.html#server-ssh-key-git-project-access), make sure that you do or that you [create a deploy key for this site](https://forge.laravel.com/docs/servers/ssh.html#deploy-keys). 3. If necessary, add the server's public key (`~/.ssh/id_rsa.pub`) to the [repository's deploy keys](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/managing-deploy-keys#deploy-keys). > This will allow Deployer to clone the repository from its SSH session on the server. 4. SSH into the server to copy its public key (`~/.ssh/id_rsa.pub`) and add it to the [server's authorized keys](https://forge.laravel.com/docs/accounts/ssh.html#adding-ssh-key-to-existing-servers) on Forge. > This is the first step to allow the Deployer action to SSH into the server.
> The key should be associated to the correct isolated site username. 5. Finally, copy the server's private key (`~/.ssh/id_rsa`) and add it to the [repository's secrets](https://docs.github.com/en/actions/security-guides/using-secrets-in-github-actions#creating-secrets-for-a-repository). > This is the last step to allow the Deployer action to SSH into the server.
> We suggest naming the secret after the target environment. For instance, if you are creating a staging site, it may be named `STAGING_SSH_KEY`. 6. You may then trigger the deployment workflow.   ### Adding to an existing site First, make sure the website is isolated. It must be located at `/home//` on the server. Otherwise, you must create a [new isolated site](#creating-a-new-site). You must first **backup your `.env` file and `storage` directory**, since Deployer will delete the site's directory to replace it with a symlink. After backing them up, you may follow steps 3 to 6. Once the deployment is complete, you may restore your `.env` and `storage` in `/home//deployer//shared`.   > [!WARNING] > Proceed with caution. Make sure to put the site on maintenance and think of the potential side-effects that may happen during this migration.   ## Slack notifications ### Using Deployer This recipe supports sending Slack notifications using a webhook. To create it, you may follow [Slack's documentation](https://api.slack.com/messaging/webhooks) on the topic. You must then add the webhook as a repository or organization secret, and forward it to the action as an environment variable. > [!NOTE] > Note that `RUNNER_ID` is required, because the Slack notifications link to the associated GitHub workflow.   ### Using Forge Alternatively, you may [set up Slack notifications on Forge](https://forge.laravel.com/docs/sites/deployments.html#slack), and trigger a deployment on Forge. This way, you also get to use Forge's deployment history. To trigger the deployment on Forge, simply call `triggerDeploymentsOnForge`: > [!WARNING] > When using this strategy, make sure to empty the default deployment script configured by Forge.   ## Multiple environments This recipe supports deploying to multiple environments, such as staging or production, without any specific configuration, other than adding the different private SSH keys to your repository secrets. It works by associating the repository branch to the one defined on the Forge site. For instance, you may have a `main` branch associated to `example.com`, and a `develop` branch associated to `staging.example.com`.   ### For two environments The private SSH key must be provided to the `private-key` argument, for instance using a conditional, as follows:   ### For more environments If you have more than two environments, you may simply duplicate the actions and use an [`if` statement](https://docs.github.com/en/actions/using-jobs/using-conditions-to-control-job-execution) to ensure they run for the correct branches:   ## Building on CI or on server By default, the recipe will build assets on CI, and upload them on the server after. To build on the server, call `buildOnServer`: Note that, by default, no `deploy:build` task is provided, and you should write your own. For instance, you may build assets using Bun: Obviously, make sure Bun is [installed on CI](https://github.com/oven-sh/setup-bun) before using that example. ## Example workflow This workflow deploys on production or staging, depending on the branch that pushed, after running the `test.yml` and `style.yml` workflows. It will skip deployments if the commit body contains `[skip deploy]`, and will notify about deployments on Slack. Additionally, you may [dispatch the workflow manually](https://docs.github.com/en/actions/using-workflows/manually-running-a-workflow).   ## Using `dep` locally Since the recipe depends on multiple environment variables, you cannot easily call `vendor/bin/dep` locally. You may work around that limitation by adding `FORGE_API_KEY` to your `.env`, as well as `REPOSITORY_NAME` and `REPOSITORY_BRANCH`: Then, you may add the following script to `composer.json`, and run `composer dep` instead of `vendor/bin/dep`: > [!WARNING] > Using `dep` locally will create a `.deployer_cache` file, which you should add to `.gitignore`. > [!NOTE] > If you get denied SSH access, make sure to [add your public key on your server](https://forge.laravel.com/docs/accounts/ssh.html#adding-ssh-key-to-existing-servers) and associate it to your site's user.   # Q&A **Why not [Envoyer](https://envoyer.io/)?** > Envoyer's integration with Forge removes the convenience of being able to manage everything within Forge directly, instead forcing us to juggle between two different user interfaces. Our developer experience is better with Deployer and this recipe. **Why are issues closed?** > This recipe is mostly used internally at Jetfly, and we are not willing to do support for it nor add many features. Pull requests for fixes and small additions may be welcome, though.