Learn how to use Buddy pipelines to automatically and safely deploy changes to your Craft CMS website
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:
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.
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
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.
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.
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
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.
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.
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.
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.
Share this post:
— Related blog articles
—Why I use Craft CMS
There are loads of CMS frameworks to choose from, I always choose Craft CMS. Why? Let's find out!
—Go-live checklist for for a successful launch
Time to double check your stuff and to put the dots on the i's