Robust Craft CMS deployments with Buddy

TechnologyCraft CMSLearningDevops

Learn how to use Buddy pipelines to automatically and safely deploy changes to your Craft CMS website

Published: 04 October 2023
Updated: 14 May 2024

Getting your locally developed website onto a server can be a challenge. Back in the old days we fired up an FTP client and uploaded every file to a remote server. Doing it this way these days is very error-prone and will cause headaches. A modern project will most likely be build using some kind of framework involving a build step and even some scripts that need to be run after deployment.

This repetitious work is something that can easily be done by computers, automatically.

The structure of a web project

Let's take a look at a typical project setup:

Web project anatomy

The Git repository is where all the source code is kept and allow us to work with multiple people on the same code. Github, Gitlab, Bitbucket are good places to host this Git repository.

I also recommend using cloud file storage such as Amazon S3 as a place to store client uploaded assets such as images, videos and documents.

A general workflow for code deployment is:

  • Push code changes from a local development environment to the Git repository
  • Pull code changes down from your Git repository to your staging and production environments

If you are working with multiple people on the same project, you may also have to pull code down to your local development environment to stay in sync with the rest of your team.

Setup a project in Buddy

Choose the hosting provider where your project's code is hosted. Select the integration, organization and the repository you want to deploy.

Buddy - Create a project

Buddy pipelines

You can setup multiple pipelines in a project with each their own actions that need to be run. I recommend setting up a pipeline for your production environment and a separate pipeline for your staging environment. Give your pipeline a distinct name and set the trigger mode. I recommend setting the trigger mode to "On events -> Git push". Don't forget to set the correct git branch you want to deploy. I use the main branch to deploy to production and the develop branch to deploy to the staging.

Buddy - Create a pipeline

Setup pipeline variables

Before we do anything else, we are going to setup some pipeline variables. These pipeline variables can easily be reused in different actions and also makes it possible to export this pipeline and reuse it for another project.

Click on the variables tab inside a pipeline to start adding some variables.

Buddy - Pipeline variables

Setup the pipeline actions

Once you have created a pipeline, it is time to define the actions that need to be performed. All pipelines run in a containerized environment before actual files get transferred to the server. So if an action fails in the Buddy container, your server won't be affected.

I recommend setting up the following actions:

  • Send a notification that the pipeline has started (optional)
  • Execute a "composer install"
  • Execute a "npm run build"
  • Rsync the compiled files to the server
  • Execute some recommended commands on the server
  • Send a notification that the pipeline has finished the actions (optional)
Buddy - Overview of actions

Pipeline notifications

These notification actions are completely optional, but are a great way to notify the correct people about the status of a deployment. You can also setup a notification if a pipeline has failed, so you can act accordingly.

Buddy - Actions run on failure

I usually add the following variables to my pipeline:

  • REMOTE_SSH_HOST - The hostname that should be used to ssh into your server
  • REMOTE_SSH_USER - The username that should be used to ssh into your server
  • REMOTE_SSH_PATH - The path to the root directory of the project on the server

Setup "composer install" command

Add a new action and search for "php". Select this and edit the command that should be run

Buddy - Composer commands settings

I added a few flags to the composer install so everything runs smoothly. You can find the full command I use below.

composer install --no-dev --no-progress --no-scripts --no-interaction --prefer-dist --optimize-autoloader --ignore-platform-reqs

Switch to the environment tab and select the correct package you want to use and select the correct version for your project. Don't forget to save your changes.

Buddy - Composer PHP settings

Setup "npm run build"

In my most recent projects I use Vite JS for my frontend tooling. Other build tools will most likely also use the command "npm run build" to start building the distribution files of your project.

Add a new action and search for "node", select it and add the commands for your build.

Buddy - Node commands settings

My frontend build step only requires the following code

npm install
npm run build

Just like my composer action, I need to set the correct nodejs version for my project. In the environment tab you can select which nodejs image you want to use and which version. Don't forget to save your changes.

App buddy works maxpdesign mpdwee pipelines pipeline 468419 action 1359823 edit 1

Setup "Rsync" action

Now that all of our project files are ready and compiled, it is time to transfer them to our server. To do this we are going to be using Rsync to transfer the files.

So create another action and search for "Rsync".

Check the following options:

  • Compress file data during file transfer
  • Archive mode
  • Delete extraneous files outside pipeline filesystem
  • Recurse into directories
Buddy - Rsync action

Next we will update the target settings

Buddy - Rsync target settings

Use the pipeline variables we set to fill out the settings so the action can connect to the server by SSH and transfer the files to the correct path. Don't forget to save your settings

Environment variables

You can use the filesystem inside your Buddy pipeline to create your .env file and fill out your variables. These extra files you create inside the pipeline filesystem will also get transferred to the server during the Rsync action.

Run some post deploy commands

Next we want to create another action in the pipeline which will run some commands on the server trough SSH. So search for SSH when adding the new action. In the first tab of the action we will define which commands should be run on the server.

Buddy - Post deploy commands

Below is an example of the commands I recommend should be run after a deployment. These commands include running migrations, applying project config changes and clearing some caches.

echo "Running craft migration..."
php craft migrate/all --no-content --interactive=0

echo "Applying project config..."
php craft project-config/apply

echo "Running craft additional migration..."
php craft migrate --track=content --interactive=0

echo "Clear multiple caches..."
php craft clear-caches/compiled-classes
php craft clear-caches/compiled-templates
php craft clear-caches/cp-resources
php craft clear-caches/data

echo "Application deployed"

Pipeline is ready!

Now everything is setup for your deployments, you can get back to developing the project and by pushing your code to the correct branch your pipeline will do it's thing. No more connecting to the server trough FTP and manually copying over the files you changed. No more making mistakes during this step by forgetting a file. Just sit back and let your Buddy pipeline do the heavy lifting. If you have also setup the notification action, you will get a message when Buddy is done deploying your application.

minute read

Share this post:

Maxime pardon 2023 11 14 112600 fogr
Written by
Maxime Pardon

— Also interesting

9 December 2022
Craft CMS

Completely revamped website for Oorlogsgravenstichting

Future proofing data and content management. Integration of a new SRS with a new website.

20 must-skills for software developers in 2021
28 April 2021

20 must-skills for software developers in 2021

Whether you are already an experienced developer or just starting out, if you want to become really good in this industry, you need to constantly hone your skills to stay relevant.

10 March 2023

Co-creation of the new Gumption website

Implementation of a redesign by Oddball and migration of existing content.

Want to work together? Let's talk

hello@maxpdesign.beContact us

Follow me