Working with a specific static site generator?
Customize CloudCannon's documentation to suit your SSG.
Great! We'll show you documentation relevant to .
You can change this any time using the dropdown in the navigation bar.
Once your files are synced to CloudCannon the next step is to run your build. This mirrors your local development environment: Every time your files change, a build is run to produce your website. This workflow allows you to have complete control over how your website looks and functions.
Setting up your build#
When setting up a site you will be asked how to build your static site from your source files. This includes options for:
- Selecting your SSG and its CLI options
- Setting environment variables
- Setting the folder that will contain your built site
- CloudCannon specific options
If you have any questions about the options in your build, see the Configuring your build document or contact support.
What happens during a build#
CloudCannon has a CI/CD (Continuous Integration/Continuous Delivery) system built into the core of the product. Every build runs as follows:
- Your files are downloaded to the server
- Your selected install commands are run (e.g.
npm install,bundle install) - Your selected build commands are run (e.g.
npm run build) - The output files are indexed for editing
- Your files are uploaded to CloudCannon hosting for previewing and/or delivery
Additionally you can hook into steps to your build to run extra commands. This is useful for downloading external data, running testing commands and much more.
The build commands are run using bash in an isolated environment powered by Ubuntu which has a comprehensive list of build tools and programming languages installed. Most software installed comes with a version manager which allows you to keep consistency between builds. This is covered in the build environment section of the documentation.
Reading the output of builds#
As builds run they produce logs which are crucial for understanding what is happening. These logs are available live in a terminal within your Site / Status page. From here you can also dig into your previous builds. This can be useful for tracking down when issues started occurring.
These logs come with timing metrics which can assist with improving your build speed. If your build fails for any reason, be sure to check the build logs first. We also provide some automated suggestions for common build errors to help you get back to a successful build quicker.
Caching between builds#
Build speed is very important for the experience of editing your website. CloudCannon attempts to send your consecutive builds to the same server. This allows you to configure caching of files between each build to skip expensive repetitive operations. This is great for image optimization, installation steps and external data fetching. Look at the build caching section for more information.
How builds are started#
Builds can be started by:
- Files being changed from Git or within the editing interfaces
- Changing build configuration (e.g. CLI options, SSG Choice, caching options or toggling building locked)
- Triggering a rebuild from the Site / Status page
- Using automatic scheduling or manual scheduling
- Using our API currently on private beta
Sites can be prevented from building by turning on ‘Building Locked’ within the site settings. This is useful when you want to manage a deployment more manually. Most editing configuration is read at build time, so changes to configuration may be delayed while building is locked.