What is a Site build?

A “build” is when CloudCannon converts all your Site files into a single, functional website. By building your Site in CloudCannon, you can make the most of features such as:

• The Visual Editor
• Preview screenshots for pages in your Collection browser
• The Test Domain
• Hosting your Site on a Custom Domain

What happens during a build?#

CloudCannon uses a CI/CD (Continuous Integration/Continuous Delivery) system. Every time you trigger a build of your Site, CloudCannon will:

1. Download your files onto our server.
2. Run your selected install commands (e.g., npm install, bundle install).
3. Run your selected build commands (e.g., npm run build).
4. Index your output files.
5. Upload your output files to CloudCannon to generate previews (i.e., the test domain, visual editor, and in-app screenshots) and deliver them to your live domain (if you are hosting with CloudCannon).

Additionally, you can configure build hooks to run extra commands during your Site build. Build hooks are useful for downloading external data, running test commands, and more.

CloudCannon runs your build commands using bash in an isolated environment powered by Ubuntu. In addition to bash, CloudCannon includes several other programs and libraries your Site may need, such as Deno, Go, Node.js, and Ruby. You can pin a version of these dependencies to maintain consistency between builds.

Starting a build#

Setting up your first Site build requires some configuration. For more information, please read our documentation on configuring your first build.

Once you have completed your first build, members of the Technical Editors, Developers, and Owners Default Permission Groups can trigger subsequent builds at any time. If your Organization uses Custom Permission Groups, team members with the site:build (or, more specifically, site:build:trigger) permission can start a build for any Sites they have access to.

You can start a build by:

• Committing edits to your Git repository after editing your files in CloudCannon or locally
• Updating your build configuration, such as your SSG, command line options, caching options, or unlocking builds on your Site.
• Clicking the Rebuild button on the Status page.
• Configuring manual build scheduling or automatic build scheduling.
• Using the CloudCannon API.

You can prevent a Site from building by locking builds.

Reading your build output logs#

CloudCannon produces a log every time it runs a build. You can use your build log to follow CloudCannon's build process and diagnose your build if CloudCannon runs into an error.

While CloudCannon is building your Site, you can read the build output files by clicking on the View Output button in the notification at the bottom right of the app. This will open the build terminal.

The build terminal has three tools: the Copy Output button and the checkboxes for Scroll to bottom and Show timing. The Copy Output button lets you copy your build log as plain text. The status of the Scroll to bottom and Show timing checkboxes will persist between builds. These checkboxes control whether the terminal displays the beginning or the end of the log by default and whether event times are logged, respectively.

You can view your most recent build logs on the Status page (this page is not available to members of the Editors Permission Group) and all past build logs on the Builds tab of the Status page.

Caching between builds#

To improve the speed of your builds, CloudCannon attempts to send consecutive builds from a single Site to the same server. You can configure file caching so that CloudCannon only uses server time for files updated between builds. This allows you to skip expensive and repetitive operations.

Caching is great for minimizing the effect of build steps that are typically slow, such as image optimization, installing dependencies, and external data fetching. For more information, please read our documentation on configuring caching between builds.