Robust Craft CMS deployments with Buddy

Front-end development

Craft CMS prioritizes developers by offering a meticulously crafted and comprehensively documented codebase, along with a flourishing community of developers and a dedicated support team.

The CMS provides developers with an expansive and ever-expanding assortment of plugins and extensions, enabling them to effortlessly enhance the platform's capabilities and introduce novel features.

Additionally, the dynamic community of developers and users actively collaborates, sharing expertise, providing assistance, and actively contributing to the ongoing advancement of the platform.

The structure of a web project

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

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 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.

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.

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)

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.

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

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

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.

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.

My frontend build step only requires the following code

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.

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

Next we will update the 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.

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.

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.