Easy WordPress theme deployment using Deployer
Tags: engineeringmonday, wordpress, deployment, tutorial
Published: 2021-04-19 10:29:21

In this article, I’ll show you an easy and fast way how to set up WordPress theme deployment without downtime using Deployer in 5 steps.

## Table Of Contents
 * [Setting up Deployer](#step-1)
 * [Setting up the Server](#step-2)
 * [Setting up SSH Agent Forwarding](#step-3)
 * [Setting up deploy.php](#step-4)
 * [Testing our Script](#step-5)

###Step 1 <a name="step-1"> - Setting up Deployer

[Deployer](https://deployer.org/docs/getting-started.html) is a simple **open-source** PHP-based **deployment** tool. It’s easy to use and set up.

There are multiple ways to **install** the tool on their website but the easiest way is to run these 3 commands: 

```
curl -LO https://deployer.org/deployer.phar
mv deployer.phar /usr/local/bin/dep
chmod +x /usr/local/bin/dep
```

To check if everything is installed ok run the command:

```
dep
```

###Step 2 <a name="step-2"> - Setting up the Server

In this tutorial, we will be using AWS Lighstail, but you can use any other server.
The only requirement is that you have **SSH Access**.

####Creating an instance - you can skip this part if you have a server and SSH access

Log in to your AWS account and search for Lightsail in the search bar. 
![Lightsail](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/r7g6c2bzs1xv8xyo0hmq.png)

Create an instance using the WordPress blueprint and Linux platform. When the server is up and running, open the server terminal and add your public SSH key to the **~/.ssh/authorized_keys** file.

####Setting up GIT

We need **Git** on the server because **Deployer** will pull the theme from the repository. 

As we are on a Linux-based server, the command to install git is:

```
sudo apt-get install git
```

To verify the installation run the command:

```
git --version
```

###Step 3 - Setting up SSH Agent Forwarding

To be able to pull the repository, the server needs access to it. We can use **deploy keys** or **SSH Agent Forwarding**. Both ways are pretty straightforward when it comes to the set up, but we will go with Agent Forwarding in this tutorial.

On your local machine position yourself in the **~/.ssh** folder. If it doesn't exist, create a file named "config".
Enter the following text into the file, replacing example.com with your server's domain name or IP:

```
Host example.com
  ForwardAgent yes
```

The key must be available to **ssh-agent**. You can check that by running the command:

```
ssh-add -L
```

If the command says that no identity is available, you'll need to add your key:

```
ssh-add yourkey
```

*For your server SSH Agent Forwarding troubleshooting refer to this tutorial -> [Using SSH Agent Forwarding](https://docs.github.com/en/developers/overview/using-ssh-agent-forwarding)

###Step 4 <a name="step-4"> - Setting up deploy.php

**Deploy.php** is the main **config file** for Deployer. As we want to only deploy the WordPress theme, we will put the deploy.php in the **theme root**.

Position yourself in the theme root and enter the command:

```
dep init
```

You will need to provide some basic info. Choose the **0 - Common script** as it has the basic stuff that we need. 
Next, enter your theme repository. In the repository, only the theme files should be present. 
In the last step, you can choose to submit anonymous usage information to the PHP-Deployer community.
Now we have the basic deploy.php file. We will do some **changes** to make our script work.

First, let's name our application/theme:

```
set('application', 'my_project');
```

We can enter anything but let's put our theme name: "super-theme".

We will set a new variable:

```
set('theme_dir', 'path_to_themes_folder');
```

Here we need to enter the **server path to the themes folder**. In our example, we used AWS Lightsail with preinstalled WordPress so the path is: "/home/bitnami/apps/wordpress/htdocs/wp-content/themes".

Next, we set the host and modify it:

```
host( 'project.com_or_IP' )
	->set( 'branch', 'master' )
	->user( 'bitnami' )
    ->set( 'deploy_path', '~/{{application}}' )
	->forwardAgent();
```

We can use the **domain name or IP** for the host. We set up the **branch** that we want to deploy, the **SSH user** in our case "bitnami". 
The **deploy_path** contains the deployment path on the server that can be left as is, and we enable **Agent Forwarding** so that our local SSH key is used for pulling the repository on the server.

For our script, we need to add an **additional task** that symlinks the current folder to the themes folder so that we can have the latest theme active after the deployment.

```
task( 'deploy:theme', function () {
	run( 'ln -sfn {{deploy_path}}/current {{theme_dir}}/{{application}}' );
} );
```

The last part is to **add** the created task to the main task **"deploy"**. 
```
task( 'deploy', [
	'deploy:info',
	'deploy:prepare',
	'deploy:lock',
	'deploy:release',
	'deploy:update_code',
	'deploy:shared',
	'deploy:writable',
	'deploy:vendors',
	'deploy:clear_paths',
	'deploy:symlink',
	'deploy:theme',
	'deploy:unlock',
	'cleanup',
	'success'
] )->desc( 'Deploy your theme' );
```

We added the "deploy:theme" task after the current symlink is created.

The **whole file** should look something like this:

```
<?php

namespace Deployer;

require 'recipe/common.php';

// Theme name
set( 'application', 'super-theme' );

// Theme repository
set( 'repository', 'git_repository' );

// Theme directory
set( 'theme_dir', '/home/bitnami/apps/wordpress/htdocs/wp-content/themes' );


// [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', [] );
set( 'allow_anonymous_stats', FALSE );


// Hosts
host( 'project.com_or_IP' )
	->set( 'branch', 'master' )
	->user( 'bitnami' )
	->set( 'deploy_path', '~/{{application}}' )
	->forwardAgent();


task( 'deploy:theme', function () {
	run( 'ln -sfn {{deploy_path}}/current {{theme_dir}}/{{application}}' );
} );

/**
 * Main task
 */
task( 'deploy', [
	'deploy:info',
	'deploy:prepare',
	'deploy:lock',
	'deploy:release',
	'deploy:update_code',
	'deploy:shared',
	'deploy:writable',
	'deploy:vendors',
	'deploy:clear_paths',
	'deploy:symlink',
	'deploy:theme',
	'deploy:unlock',
	'cleanup',
	'success'
] )->desc( 'Deploy your theme' );

// [Optional] If deploy fails automatically unlock.
after( 'deploy:failed', 'deploy:unlock' );
```

###Step 5 <a name="step-5"> - Testing our Script

To run our script we enter the command:
```
dep deploy
```

If everything is **successful** it should look like this:
![Successful deploy](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/9midvc9gsw3457vz8i09.png)

If something is wrong you can use the verbose mode to debug:
```
dep deploy -v, provides default installation view with the least information 
dep deploy -vv, provides some more details as compared with the default mode 
dep deploy -vvv, provides a detailed view of the installation output
```

###Conclusion
 
Those are the 5 steps for a fast deployment setup for a WordPress theme.
 If you use the same server for all of your projects you can set up this only once and only modify the variables in the deploy.php file.

There are many ways to manage a WordPress theme and set up deployments. I find this an easy way to quickly set up the workflow, what do you think?