deployer/docs/getting-started.md

Getting Started

In this tutorial we will cover:

• Setting up a new host with provision recipe.
• Configuring a deployment and perfoming our first deploy.

Tutorial duration: 5 min

First, install the Deployer:

Now lets cd into the project and run the following command:

dep init

Deployer will ask you a few question and after finishing you will have a deploy.php or deploy.yaml file. This is our deployment recipe. It contains hosts, tasks and requires other recipes. All framework recipes that come with Deployer are based on the common recipe.

Provision

:::note If you already have a configured webserver you may skip to deployment. :::

Let's create a new VPS on Linode, DigitalOcean, Vultr, AWS, GCP, etc.

Make sure the image is Ubuntu 20.04 LTS as this version is supported via Deployer provision recipe.

:::tip Configure Reverse DNS or RDNS on your server. This will allow you to ssh into server using the domain name instead of the IP address. :::

Our deploy.php recipe contains host definition with few important params:

• remote_user user's name for ssh connection,
• deploy_path host's path where we are going to deploy.

host('example.org')
    ->set('remote_user', 'deployer')
    ->set('deploy_path', '~/example');

To connect to remote host we need to specify identity key or private key. We can add our identity key directly into host definition, but better to put it in ~/.ssh/config file:

Host *
  IdentityFile ~/.ssh/id_rsa

Now let's provision our server. As our host doesn't have user name deployer, but only root user. We going to override remote_user for provision via -o remote_user=root.

dep provision -o remote_user=root

:::tip If your server doesn't have a root user but your remote user can use sudo to become root, then use:

dep provision -o become=root

:::

Deployer will ask you a few questions during provisioning: php version, database type, etc. You can specify it also in directly in recipe.

Provision recipe going to do:

• Update and upgrade all Ubuntu packages to latest versions,
• Install all needed packages for our website (acl, npm, git, etc),
• Install php with all needed extensions,
• Install and configure the database,
• Install Caddy webserver and configure our website with SSL certificate,
• Configure ssh and firewall,
• Setup deployer user.

Provisioning will take around 5 minutes and will install everything we need to run a website. It will also setup a deployer user, which we will need to use to ssh to our host. A new website will be configured at deploy_path.

After we have configured the webserver, let's deploy the project.

Deploy

To deploy the project:

dep deploy

If deploy failed, Deployer will print error message and command what was unsuccessful. Most likely we need to configure correct database credentials in .env file or similar.

Ssh to the host, for example, for editing .env file:

dep ssh

After everything is configured properly we can resume our deployment from the place it stopped (But this is not required, we can just start a new deploy):

dep deploy --start-from deploy:migrate

Now let's add a build step on our host:

task('build', function () {
    cd('{{release_path}}');
    run('npm install');
    run('npm run prod');
});

after('deploy:update_code', 'build');

Deployer has a useful task for examining what is currently deployed.

$ dep releases
task releases
+---------------------+--------- deployer.org -------+--------+-----------+
| Date (UTC)          | Release     | Author         | Target | Commit    |
+---------------------+-------------+----------------+--------+-----------+
| 2021-11-05 14:00:22 | 1 (current) | Anton Medvedev | HEAD   | 943ded2be |
+---------------------+-------------+----------------+--------+-----------+

:::tip During development, the dep push task maybe useful. :::