PageBuilder Engine Deployer API

Note

This is relevant only for non-Themes environments.

Deployment Strategies

While there are multiple ways to run your deployments our best practices and recommendations are as follows:

• Set your default branch in your repository to your development branch
• Configure branch restriction rules on master so it cannot be deleted and must pass a continuous integration test build
• Configure branch restriction rules on your dev branch so pull requests require a review before they can be merged and must pass a continuous integration test build
• Setup your continuous integration (Example: Configuring CircleCI to automate deployments)
• Setup your slack channel to notify you of deployment success/failures (optional but extremely helpful)
• Select one day at the end of every sprint (towards the beginning of the week usually works best) to upload a deployment bundle and promote it to your environment or configure your CI to automatically promote a bundle anytime you merge your development branch into your master branch

Generating Bundles

PageBuilder Engine comes with a built in functionality to generate an uploadable bundle using npx fusion zip, however it will not exclude all your unnecessary folders (ie coverage, linter configs) and it will not run your custom webpack configurations before generating the bundle. Therefore bundles run using the Fusion zip command will often be larger than necessary for your actual deployment. While the fusion command is a fast way to create a bundle file you can upload to the deployer it is not best practice to deploy these larger bundles to your production environment if you can reduce the size.

Our recommendation for generating a bundle is to run a native zip cmd excluding unnecessary folders like so:

zip config/deploy/bundle.zip -r . -x .git/\* .env node_modules/\* coverage/\* .github/\* .fusion/\* .circleci/\* .dist/\* src/\*.scss .stylelintrc.json

Continuous Integration

Our recommendation is to use continuous integration in your project to streamline uploading and deploying bundles. See Configuring CircleCI to automate deployments.

PageBuilder Engine Deployment Endpoints

The most up to date documentation is always available in your deployer section of PageBuilder Admin.

Base URL: CONTENT_BASE

Bundles

Retrieve a list of all uploaded bundles

GET /deployments/fusion/bundles

Upload a new bundle

POST /deployments/fusion/bundles?name=:bundleName[&force=true][&skipValidation=css,js,json]

By default, if a bundle with this name already exists, upload will fail. Setting force=true will allow you to overwrite it. Setting skipValidation will allow you to specify a comma-delimited selection of file-types to avoid validation.

Inspect the named bundle

GET /deployments/fusion/bundles/:bundleName

Delete the named bundle

POST /deployments/fusion/bundles/:bundleName/delete

Services

A service is a deployment you would see in Deployer UI at the top list called “Running” (bundles). Service terminology is inherited from underlying AWS service and the current API response object may contain raw AWS resource properties.

Retrieve a list of all running services

GET /deployments/fusion/services

Deploy a new service

POST /deployments/fusion/services?bundle=:bundleName&version=5.1.2[&warn=true][&force=true]

Deploy a new service using the named bundle and specified PageBuilder Engine version. By default, a deployment will fail if the bundle is missing any chains/features that are currently in-use. Setting warn=true will be more strict and also fail if you have added new chains/features, or removed unused chains/features. Setting force=true will allow you to deploy any collection of chains/features.

Inspect the named service

GET /deployments/fusion/services/:deploymentId

Promote the named service

POST /deployments/fusion/services/:deploymentId/promote?[&warn=true][&force=true]

Promote the named service. By default, a promotion will fail if the service bundle is missing any chains/features that are currently in-use. Setting warn=true will be more strict and also fail if you have added new chains/features, or removed unused chains/features. Setting force=true will allow you to promote a service with any collection of chains/features.

Terminate a service

POST /deployments/fusion/services/:deploymentId/terminate

Events

Retrieves a list of deployment-related events

GET /deployments/fusion/events?:queryParameters

Query parameters:

PARAMETER	VALUE
type	Options: upload, delete, deploy, promote, terminate
timestamp	Time in milliseconds used for filtering. You can use values such as &timestamp<=10000000&timestamp>=10000000 to search between time periods.
bundle	The name of the bundle
version	The PageBuilder version i.e. 5.1.2
username	Your username i.e. johndoe

Troubleshooting

A bundle is deploying but will not run

Typically this is because PageBuilder Engine’s webpack didn’t compile the components correctly due to a feature-level issue with the code. Most commonly we see these in in an output-type file or a file that you added recently where the code error was not picked up by the local webpack watcher. Try restarting your webpack watcher or restart PageBuilder Engine.

A bundle will not deploy

This is typically due to an upload issue, invalid credentials or an error in your continuous integration setup.

A deployment will not promote or stop

Sometimes your bundle’s thread gets hung up and you will notice a deployment in your Pagebuilder Admin that will not promote or will not terminate but just shows a spinner icon next to it. You can terminate these manually using the Fusion service terminate endpoint and then try promoting the bundle again.