A Code builder is a Docker image used by Silverstripe Cloud to transform your codebase into a production-ready build during deployments. The primary action these builders take on Silverstripe CMS projects is installing Composer dependencies, but you can also provide custom scripts to perform other tasks like building front-end dependencies.
Selecting a Code builder
You can select which builder to use on a per-Environment basis. This can be helpful when migrating between builders, as you can test the new builder in a UAT environment while still using your original builder in Production deployments.
To see which Code builder your environment is currently using or to change it, open the Code builders tab in the Environment view.
Pinned Environments
In some cases, your Environments may be pinned to a specific Docker image by the Silverstripe Cloud operations team, which will prevent you from selecting a Code builder until the pin is removed. Contact the service desk for more information.
Available Code builders
1.0.2 - Composer v1
This is the standard builder in use by most Silverstripe Cloud stacks. It is limited to installing Composer dependencies, and does not run any scripts during this process.
The Docker image for this builder is silverstripe/platform-build:1.0.2.
1.2.0 - Composer v1 & Node.js v6-12
This is a new builder that enables scripts during the Composer installation process, and allows custom scripts to be run during the build process.
The Docker image for this builder is silverstripe/platform-build:1.2.0.
2.0.0 - Composer v2 & Node.js v6-16
This builder introduces Composer v2. It also provides latest versions of Node.js (v14 and v16). Older versions of Node.js are still available, and frontend builds work exactly the same as in 1.2.0. This builder is backwards incompatible due to Composer v2 having some edge-case issues with composer.lock files generated by Composer v1. We recommend testing Composer v2 builds on UAT or test environments before deploying to production.
The Docker image for this builder is silverstripe/platform-build:2.0.0.
2.1.0 - Composer v2 & Node.js from v16-20
Composer 2.5.5. Node.js support only for v16 (default), v18 and v20. Please use previous versions of code builder for older Node.js support
The Docker image for this builder is silverstripe/platform-build:2.1.0.
Composer Scripts
Since Node.js builders enable scripts during the Composer installation process, you can define pre-install or post-install scripts that will be triggered during deployment. You can also make use of tools like Composer Patches.
If you have existing pre-install or post-install scripts that you do not wish to have run during deployments, you can wrap them in a check for the presence of a CLOUD_BUILD environment variable.
NPM / Yarn Scripts
Node.js builders will also check for the presence of a package.json file in the root directory of your project. If this exists, and it contains a script called cloud-build, your NPM dependencies will be installed and the builder will attempt to run the cloud-build script. This is most commonly used to compile front-end code via Webpack or other Node-based tools, allowing the built files to be removed from version control. For more information on how to write these scripts, see the NPM Scripts documentation.
Some important considerations for using this feature:
- If a yarn.lock file is present, Yarn will be used to fetch dependencies and run the script instead of NPM.
- By default, scripts will be run with Node 10 (code builder v2.0.0 and below) or Node 16 (code builder v2.1.0). If you provide an .nvmrc configuration file in the root of your project, you can specify another major release of Node to use. Versions 6, 8, 10, 12, 14, 16, 18 and 20 are currently supported.
- Ensure that the cloud-build script builds the production-ready version of your code. There is currently no way to identify whether the deployment is targeting a Production or UAT environment, but including source maps in your production build will allow you to debug JS / CSS issues using your browser's devtools.
- To minimise disk space issues, the node_modules folder will be removed after your script is run, and will not be present on your web servers. Ensure you copy any required files into a separate directory.
Debugging
Before adopting a new Code builder, or if you encounter issues during deployments related to it, you can run the builder from your development environment in order to test its behaviour against your project. You will need Docker installed.
In a terminal window, run the following command from the project folder to trigger the builder (ensuring you set the correct Docker image version based on the Code builder you are using):
docker run \
--interactive \
--tty \
--volume composer_cache:/tmp/cache \
--volume ~/.ssh/id_rsa:/root/.ssh/id_rsa:ro \
--volume $PWD:/app \
silverstripe/platform-build:1.2.0
Requirements failure during dev/build
In some cases when updating from the Basic code builder to the Advanced code builder, you may experience a dev/build failure during deployment that references missing Requirements. This can commonly be resolved by performing a full deployment. If you continue to experience issues, please contact the service desk.
Further considerations
Adding custom scripts to the build process can result in slower deployments. This will only impact each version of your code when deploying for the first time, as the output is cached after the first run. Depending on the size and complexity of your scripts, this may be neglible, but if you observe excessive deployment lengths it may be necessary to apply optimisations to your build process, and in severe cases it may be better to revert to pre-compilation. As a last resort, if the build process exceeds 60 minutes, the process will time out and the deployment will fail.
Silverstripe Cloud also supports Package Deployments, which enables your CI workflow to push a complete code package to the dashboard for direct deployment, bypassing the code builder. Depending on your project requirements and structure, this may be a better approach, as it front-loads the build work that would otherwise be performed during the deployment process. However, in case a manual deployment is necessary, you should ensure that your selected Code builder can still produce a working version of your site.