HTTP Deployment Handler

Handles the deployment of one or more Deployment Packages to a custom HTTP endpoint.

The custom HTTP endpoint is described by:

  • url
  • statusUrl
  • username
  • password

Custom HTTP endpoints are useful for a large variety of purposes, including writing data into custom databases, synchronizing content from Cloud CMS with existing Content Management products, hooking into custom logic for CDN or cache invalidation and much more.

Configuration

{
    "url": "{url}",
    "statusUrl": "{statusUrl}",
    "username": "{username}",
    "password": "{password}"
}

Where url is the remote address of the server and username and password describe the credentials to be applied using Basic Authentication. The statusUrl is optional - it enables Cloud CMS to poll your endpoint for completion.

How it works

The remote HTTP endpoint must be a POST handler. All POSTs to the endpoint will be multipart/form-data and will contain the following parts:

package
archive-{guid1}
archive-{guid2}
...

There will be at least 2 parts (package and archive-{guid1}) where guid1 is the ID of the archive that contains the JSON and binaries being deployed. A deployment package may also have multiple archives in which case there will be more parts. Your custom HTTP endpoint should consider the prefixes of the incoming parts to determine how each is applicable.

The package part provides the JSON for the deployment package.

The HTTP endpoint should acknowledge receipt of the deployment package by returning a 200 and a JSON payload that contains an ID for the deployment package on the endpoint. It may look like this:

{
    "_doc": "{remoteDeploymentPackageId}"
}

This _doc, for all intents and purposes, serves as a job ID or a task ID for the background processing that is now occurring against the deployment package on the remote HTTP server.

The statusUrl property is optional. If it is provided, Cloud CMS will poll the HTTP endpoint using the aforementioned _doc to check on the status of the deployment package.

If you do choose to provide statusUrl, then it should point to a GET method that returns the deployment package JSON. This JSON should more or less look like this:

{
    "_doc": "",
    "state": "PENDING|PROCESSING|SUCCESS|ERROR",
    "operation": "DEPLOY|UNDEPLOY",
    "retain": true|false,
    "records": [{
        "_doc": "",
        "state": "NONE|DIRTY|PROCESSING|FINISHED|ERROR",
        "operation": "DEPLOY|UNDEPLOY",
        "ref": "",
        "success": true|false,
        "message": ""
    }, ...]
}

The state of the deployment package indicates whether the HTTP endpoint has finished processing all of the records contained within it. When it finishes, it should either flip to SUCCESS or ERROR. Further, each individual deployment record should have its state adjusted to FINISHED or ERROR. Further, the success field should be tripped to either true or false. Any deployment records that fail should have their message set so that meaningful information can be conveyed back to Cloud CMS about what went wrong.

The statusUrl value is allowed to use a special id field to fill in the _doc of the deployment record as acquired from the initial push. You can populate this using handlebars, like this:

http://deployer.mywebsite.com/status/{{id}}

Or:

http://deployer.mywebsite.com/status?id={{id}}

Example Configuration

{
    "url": "http://deployer.mywebsite.com/push",
    "statusUrl": "http://deployer.mywebsite.com/status/"
    "username": "inigo",
    "password": "montoya"
}

Building your own HTTP Deployment Receiver

We encourage you to go on and build some really cool and interesting Cloud CMS Deployment Receivers. To help you get started, we provide a Node.js-based custom HTTP Deployment Receiver that shows off what is possible. It is available in our SDK, here:

https://github.com/gitana/sdk/tree/master/http-deployment-receiver

To configure this within your own Cloud CMS environment, just add an http Deployment Target and configure it a bit like this:

[object Object]

This Custom HTTP Deployment Receiver uses a small library which is available here:

https://github.com/gitana/cloudcms-http-deployment-receiver

We encourage you to take a closer look at this library. It may be give you a head start in terms of building out your own custom HTTP Deployment Receivers. At the very least, it should serve as a useful technical reference to compare your own implementations against.

When testing your receiver, you need to ensure that the endpoint is accessible to the outside world, or at the least accessible to the API. On premise users using the API in a docker container hosted on a Mac or Windows PC can access receiver services hosted on the same machine by using the host.docker.internal address. So, for example, when creating your deployment receiver in cloudcms to connect to a local server bound to port 3000, you would configure to the url parameter as http://host.docker.internal:3000.