Robust Craft CMS deployments with Buddy

Getting your locally developed website onto a server can be a challenge. Back in the old days we fired up an FTP client and uploading every file to a remote server. Doing it this way these days is very error-prone and will cause headaches. 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:

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 os:

• 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 in 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

You can define pipeline variables that can easily be reused in different actions. Click on the variables tab inside a pipeline.

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

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.

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.