- Print
- DarkLight
Darwinium is able to deploy its decisioning components as web workers at the routes defined in your Journey’s steps. Deployment can occur automatically when a build is pushed to your node’s git repo, manually using Terraform the Darwinium API.
This guide assumes that you have a Cloudflare account setup that is already providing CDN capabilities for the sites you wish Darwinium to protect, as well as a workers plan. Users of this guide are assumed have knowledge of Cloudflare, and have access to Cloudflare's dashboard (https://dash.cloudflare.com) with sufficient priveleges to create new API tokens.
A typical Cloudflare deployment on a one-edge deployment device takes approximately 30 minues to setup and validate under a standard configuration. Manual configuration involving terraform will take longer.
1. Enable Workers (Paid) on your Cloudflare Account
To ensure that Darwinium's workers are not subject to rate limiting, enable Cloudflare Workers (Paid) on your account.
In Cloudflare Dashboard:
- On left hand sidebar, select Workers & Pages -> Plans
- Select "Purchase Workers Paid".
- Complete your payment details if not present already.
2. Get your organization’s Cloudflare Account ID, Zone ID
After setting up your site on Cloudflare, navigate to the site you wish to deploy Darwinium upon. Your Account ID and Zone ID will be shown in the bottom right of the summary screen. Take note of these, as they will be needed later in the process:
3. Create API tokens for Darwinium: Workers token
Two API tokens are required. One for Workers and another for KV Storage.
- At the top-right of the Cloudflare console, click the menu and select My Profile.
- On the left-hand navigation, select "API tokens":
- Select “Edit Cloudflare Workers” from the API token templates section:
- Verify that only following permissions are set:
- Account: Workers KV Storage: Edit
- Account: Workers Scripts: Edit
- Zone: Workers Routes: Edit
- Setup a TTL for your token. This may vary depending on your organization’s security policy. Darwinium recommends setting a TTL between 6 months and 1 year
- Re-entering API tokens is your responsibility
In order for the service to continue operating after the TTL, you will need to generate a new API key and enter it into darwinium’s settings
- Token will be generated. Take note of these as they will only appear once in cloudflare
4. Create API tokens for Darwinium: KV Storage token
Follow the same process as for Workers token above but permissions should be only set as
- Account: Workers KV Storage: Edit
5. Setup KV stores for Darwinium
KV stores are used to store Darwinium's critical state information at the edge. Darwinium requires 3 of these to work correctly. To set these up:
- On the left-hand navigation menu, select Workers > KV
- Select Create namespace from the top-right of the screen that appears:
- Create 3 namespaces with the following names:
- DWN_LABEL
- DWN_IDENT
- DWN_DATA
- Take note of the ids of these 3 KVs - they will need to be entered into the darwinium cloudflare settings
6. Enter configuration into Darwinium Node settings
In order to configure cloudflare settings for your node, you will need to be in a group that has permission to edit the given node's settings. This can be achieved by visiting the role management section of the administration section of the Darwinium portal.
- Login to the darwinium portal, and select Administration > Nodes:
- Select settings for the node you wish to configure:
- A modal dialog should appear. Enter the settings you captured from the steps above. Note that "Automatically deploy to Cloudflare on journey build" is recommended as it will facilitate immediate publishing of your journeys to cloudflare. Alternatively this can be done through the node deployment API.
7. Testing your Configuration
To test your deployment, it is recommended that you edit a journey, and create a step triggered by a GET request on one of your pages. Push this to your node's git repo and cloudflare deployment should commence shortly afterward.
You can confirm that routes have been setup for your journey's steps by going into the cloudflare administration console, and selecting Workers > Overview.
If deployment is successful, you will see routes corresponding to a journey's step names:
8. Deployment when workers already exist
Darwinium accounts for when workers already exist on the routes it intends to deploy against.
When using Darwinium Deployment Manager, Darwinium will check all overlapping routes for the new ones intented to be deployed. The Darwinium worker does become the primary worker on the route, but it invokes the existing worker using service bindings. If a new deployment removes that Darwinium worker route, it looks at the service binding and repromotes the existing worker again.
When using webhook to manually deploy, those service bindings should be specified manually; see Controlling Darwinium Deployment and the example project.
Specifically the ability to interact with the original request/response body and headers for:
- Extracting intended attributes to Darwinium schema
- Inserting Darwinium JS profiling dynamically
- Inserting Darwinium scores and attributes into headers