Run NPM & Composer in Git Deployment Actions

What are Git additional deployment options in Plesk?

Within Plesk, you can set up a website to pull its code directly from a Git repo. By using webhooks, you can have Plesk automatically pull new versions of the project whenever commits or merges are made to the main/target branch. This way, when you deploy your work locally, it goes straight into production without the need for manual intervention.

The additional deployment options are an optional setting you can enable, allowing you to enter a series of terminal commands that are to be executed after the new code base is pulled. In my workflow, the main use for this is to have new PHP composer packages installed and updated, and the same with any NPM packages before building minified CSS and Javascript.

How to set up additional deployment options

Note: For this tutorial we will assume you already have a Git repository set up and linked to the project/domain within Plesk. If you have not set one up already, you should do so before continuing.

To add a deployment action, in the project you’d like to set them up, go to your Git settings:

From here, you can then click on ‘Repository settings’ on the bottom right to edit the current Git settings.

And within the next screen, you’ll see both the option to ‘Enable additional deployment actions’, as well as the box to type your additional deployment actions in.

Why do additional deployment commands fail

Let’s say, for example, that you’re looking at this screen for the first time and you’d like to have all composer installed whenever the git repository is fetched. I’d imagine, similar to myself, that you’d think it would be as simple as adding the following to the additional deployment actions box:

composer install

Sadly, this is where the problem kicks in. As soon as the Git repository is next fetched (manually or automatically), you’ll encounter the error:

To break down why this is happening, Plesk has a complex system of users and scopes running under the hood within Linux. Each domain you set up has its user account with its permissions and PATH. This means that, while a command might work while using SSH or the built-in terminal for the Root account, it might fail for any of the other account types if the command that’s being run requires a dependency that isn’t available within the current environment. If that made no sense, don’t worry- just keep reading for the solution and it should be clearer with the context that it provides.

Note: If you’re encountering a similar dependency error but aren’t using PHP Composer or NPM, you might be able to resolve your own issue by following the examples below.

To resolve the issue, I first logged into the server via SSH and then, with the help of some internet research, I located the install directory for PHP and Node. They’re both located within /opt/plesk.

Now that I had their locations, I updated my additional deployment action command to directly reference the composer file, instead of simply calling composer on its own:

# NOTE: I do not recommend this approach, but included it for context.
/opt/plesk/php/8.2/bin/composer install --working-dir=/var/www/vhosts/DOMAIN_NAME/httpdocs

You’ll notice the addition of the --working-dir flag. This composer-specific flag ensures that composer is executing within the correct directory. It’s important to add this flag if you’re calling the composer file directly, otherwise, you may encounter permission errors as it’ll try to work from the folder in which composer exists.

Now, technically, this is the solution as far as composer is concerned. While it works, however, it’s not great to read, and if I added any extra composer commands I would have to keep repeating the specific path and additional flag. To get around this, I took what I’d learned and translated it into a new approach to updating the PATH variable so that composer (in this example) could be utilised in the ‘standard’ approach as we saw first without the need for exact file paths or additional flags.

Running PHP Composer commands

To run a composer command within Plesk’s Git additional deployment actions, you can use the following as an example:

(export PATH="/opt/plesk/php/8.2/bin:$PATH" && cd /var/www/vhosts/DOMAIN_NAME/httpdocs && composer install --no-dev && composer update --no-dev)

First, I enclose everything with a set of brackets to ensure that all commands run within are contained in their little scope. Using &&, I run multiple commands within the brackets. Any commands run within these will lead on from the previous command, similarly to a standard terminal session.

Note: While the use of brackets allows all commands within it to utilise the established scope, for any explicit new lines created in the additional deployment box, you will need to repeat the full bracketed command from scratch. For this reason, I group similar commands within the same bracket sets.

Within the brackets, I first add PHP’s /opt/plesk/php/8.2/bin directory to the PATH and then I cd (change directory) to where I’d like the commands to be run. Bin directories in Linux are dedicated areas for storing executable files, by adding that bin directory to my PATH all of its executables are now available regardless of the current directory.

Now that I’m both in the correct directory and have PHP’s software was all accessible thanks to their bin directory being included in PATH, I can simply type out any PHP command as I normally would. In my example above, I install any packages from the composer.json file within the present directory that I navigated to, then I update all packages while ignoring any development dependencies on both of these functions by use of the --no-dev flag.

Note: If you’re using a different PHP version you’ll need to update that path accordingly. If you get similar errors with files not being found, your PHP installation directory might be slightly different.

Running Node NPM commands

(export PATH="/opt/plesk/node/21/bin:$PATH" && cd /var/www/vhosts/DOMAIN_NAME/httpdocs && npm install && npm run build)

For a full blow-by-blow breakdown of this command, see the above explanation found in the PHP Composer section. But this works in the same way. By adding Node’s software to our PATH and then navigating to the correct directory, we can run NPM commands as we normally would.

The above example shows how to run npm install followed by a custom command, in this instance build.

Summary

Git additional deployment actions are amazing but somewhat awkward to use for those who haven’t got a lot of Linux experience. By using the above approach, you can run easy-to-read commands without having to worry about weird behaviour.

If you encounter any issues with dependencies not found, you can almost guarantee it’s due to these scoping issues. If you’re using something I’ve not mentioned above, try to apply the same practice by locating the core files, updating the PATH to include the appropriate executable’s directory, then continuing as normal.

As a bonus, if you’re also using Plesk’s schedule actions, any commands that you run as per this guide should work without any required modifications.

I hope this helps in setting up a clean and reliable deployment automation for your projects!