We're introducing an exciting new feature to the deployment dashboard for SilverStripe Platform and the Common Web Platform, allowing customisation in how you build the code you deploy to your site. With the new and improved approach to deployments, you can build code your way.
This update will allow you to specify a pre-packaged codebase to deploy to your environments, as an alternative to specifying a Git commit or branch.
By embracing package deployments, your team can tightly integrate your existing Continuous Integration tooling into the Platform Dashboard, and deploy code without manual intervention (although approval is still required for production deployments).
What is it?
The deployment dashboard now includes a new option under ‘advanced options’ for deploying a tar.gz package. This functionality is also accessible through the Dashboard API.
This option allows you to specify a URL to a hosted, tar compressed version of your codebase (this could be an S3 bucket, for example).
Once you’ve specified the location and continued through the deployment workflow, the dashboard will download your codebase, and validates it for deployment.
Note: Any HTTP auth or GET parameters entered at this stage are not stored in the dashboard database. They are only used for the life-cycle of the request to download the packaged codebase.
How does it work?
When you choose to deploy a tar.gz package, the dashboard skips the usual build scripts to build your website, such as composer install and composer vendor-expose. Your package is simply deployed to your site as-is and then a dev/build is run.
You can see the CircleCI configuration we used for this example here: silverstripeltd/cd-test
Using CircleCI to build and test our code, we can set-up automatic deployments of our develop branch to UAT, and automatically queue deployments to Production of our master branch using the Dashboard API.
- First, we build our codebase after pushing a commit to our chosen repository. In this example, we are just running a composer install and composer vendor-expose. At this stage, you could compile your front-end files or other dependencies.
- Then, we test the built codebase to make sure it is functioning as we need. We are using PHPUnit to run unit tests, and a dev/build to catch anything else that could be site breaking or cause our deployment to fail.
- If the testing step is successful, then we tar compress the codebase and store it as an artifact in CircleCI. Artifacts are accessible to whoever has access to the repo CircleCI is building from, but can also be accessed with a token in the GET parameters.
- Once we have packaged our code, we call the dashboard API to queue the deployment for prod or run the deployment for UAT.
In this example, we used CircleCI to create the packaged codebase; however, it is entirely up to you how you would like to create your packages.
- We have created two CircleCI environment variables:
- CIRCLE_CD_TOKEN - Your API token for CircleCI, used to access build artefact locations, and posted to the dashboard to allow it to download your artefact.
- DASH_TOKEN - Your API token for the dashboard, used to call the API, and create the deployments.
- Feel free to build on this configuration for your own builds, but remember to update:
- The CircleCI location on lines 98 and 117
- The email address and stack code on lines 100 and 119
Can we still deploy the old way?
You can still deploy by selecting a Git commit revision from the repo associated with your stack. This is just an additional option for those who are after fine-grained control of their build, by allowing you to choose your own build steps, whatever they may be. The only caveat is that your codebase needs to be able to successfully run a dev/build.
Package deployments can still trigger a full-deployment on SSP if there are changes to the .platform.yml file, or other infrastructural changes being made, such as additions to whitelists or environment variables being changed.
When will this be available?
We are enabling this new feature on Saturday, July 28th 2018, after which you will see the new deployment options when creating a deployment.
For SilverStripe Platform, this new feature requires platform version 3.20.0, which is being automatically rolled out. However, you can speed this up by performing a full deploy of your base stack after 3.20.0 is made available on Tuesday, July 24th 2018.
Want to know more?
Alternatively, for answers to a range of questions - jump on the SilverStripe community forum.