Compare deployments
When Foil deploys the edge, it needs access to your CDN account and keeps the edge up to date for you:
When you run the edge, Foil needs no access to your CDN and deploys nothing; you keep the edge up to date:
Deploying on AWS CloudFront with your own Terraform is coming soon. See AWS CloudFront with your Terraform.
Whichever deployment you choose, Foil keeps the integration on the current SDK release. When Foil changes the edge adapter itself, it redeploys the edges it deployed. An edge you run changes only when you change it, and the integration page’s Edge adapter field shows when a newer version is available.
Before you begin
- An owner or admin role in your Foil organization, with Integrations enabled.
- A hostname your CDN already serves, such as
www.example.com. It must resolve publicly over HTTPS. - A path on that hostname your application doesn’t use, such as
/foil. Foil’s routes live under it. - Access to publish a TXT record in the DNS zone for that hostname.
- A publishable key in the environment you plan to use. A Test integration accepts only
pk_test_*keys and a Live integration onlypk_live_*keys.
Create the integration
- In the Foil dashboard, open Integrations and select Add integration.
- Under Provider, select Cloudflare, AWS CloudFront, or Custom proxy.
- Under Who deploys it, choose who runs the edge. For Cloudflare, choose Foil or Your Worker. For AWS CloudFront, Foil deploys the edge. A custom proxy is always yours.
- Select the Test or Live environment.
- Enter a Name. The name appears only in the dashboard, and you can rename the integration later.
- In Domain, enter your site’s domain without
https://or a path, for exampleexample.com. - In Subdomain, enter the subdomain your pages load from, for example
www. Leave it blank to use the domain itself. - In Path, enter the path Foil’s routes live under, for example
foil. The preview shows the resulting Site origin and Integration URL. - Leave Serve every domain routed to this integration on, unless the integration should answer only on its own hostname. You can change this later. See Serve several domains.
- Complete the fields for your deployment, described in the following sections.
- Select Create integration.
https://www.example.com/foil. An organization can have up to 10 integrations at a time, and each integration URL can belong to only one integration.
Follow the integration page
The integration page is a checklist. Work through it in order:
Below the checklist, the Manage area holds the settings you change after setup. See Manage an integration.
Add the DNS record
Step 1 lists a TXT record that proves you control the integration URL’s hostname:
Publish it in your DNS provider, or select Add with Cloudflare on a Cloudflare integration whose token has DNS Edit. Keep the record in place for as long as the integration exists. Foil checks it every time it runs the integration’s checks, and an integration whose record disappears stops accepting new sessions until the record returns.
Foil doesn’t reserve a hostname until ownership verifies. If another Foil organization has already verified the same integration URL, verification fails and you need to contact Foil support.
Cloudflare, deployed by Foil
Foil deploys a Worker namedfoil-<integration ID> to your account and a Worker route in your zone. The route is <hostname>/<path>/*, or *<zone>/<path>/* when the integration serves every domain, which covers the zone’s apex and every subdomain in it. The Worker forwards Foil’s routes and returns 404 for any other request on that route.
Cloudflare requirements
- The integration hostname is in the Cloudflare zone you select and is proxied through Cloudflare, so Worker routes run on it.
- No existing Worker route overlaps the integration route. A route such as
www.example.com/*overlaps every path on the hostname, and Foil refuses to install rather than replace it. A zone-wide integration route overlaps any route on any hostname in the zone that covers the same path. If your site already runs a Worker on the hostname, choose Your Worker instead. - An API token with these permissions, scoped to the account and the site’s zone:
Foil stores the token encrypted. Find websites fails when the token can see more than 500 zones, so scope the token to the site rather than to every zone in the account.
Set up Cloudflare
- Under Who deploys it, choose Foil.
- In Account and zone, choose Automatic to paste the token and select Find websites, then pick the site from Website. Choose Manual to enter the account ID and zone ID yourself and add the token after you create the integration.
- Optionally let Foil add the DNS records to Cloudflare for you. Foil checks each record before writing it and doesn’t overwrite a conflicting record.
- Select Create integration.
- In step 1, publish the TXT record if Foil didn’t write it.
- In step 2, add the Cloudflare token if you chose Manual.
- In step 3, select Install integration. Foil verifies the TXT record, deploys the Worker and route, and runs the checks.
- Continue with Add Foil to your pages.
Cloudflare, with your Worker
Choose Your Worker when a Cloudflare Worker you operate already serves the integration hostname. Foil deploys nothing to your Cloudflare account and needs no token. Instead, the integration page generates a Worker module with the integration’s values filled in, and you call it first in your Worker’sfetch handler.
- Under Who deploys it, choose Your Worker, then select Create integration.
- In step 1, publish the TXT record.
- In step 2, copy the Worker module, store the proxy credential as a Worker secret, call the module from your
fetchhandler, and deploy your Worker. See Run inside an existing Cloudflare Worker. Your Worker’s routes must cover the integration path on every hostname that should load Foil. - In step 3, select Start accepting traffic. Foil installs nothing on your Worker. It verifies the TXT record, starts accepting requests from your Worker, and runs the checks.
- Continue with Add Foil to your pages.
t.js on the integration URL returns 401 before then.
AWS CloudFront, deployed by Foil
Choose this option when Terraform or another tool doesn’t manage the distribution’s configuration, because Foil edits the distribution itself. If Terraform manages the distribution, the nextterraform apply removes Foil’s changes.
Foil deploys a Lambda@Edge function named foil-<integration ID> in us-east-1 and adds it to your distribution through a role in your AWS account. Foil stores no AWS access keys. It assumes your deployment role for each operation, with an external ID unique to the integration.
On the distribution, Foil adds:
- An origin named
foil-<integration ID>that points toapi.usefoil.comover HTTPS only. The origin carries two custom headers: the proxy credential and the integration’s public configuration. - Cache behaviors at the top of the behavior list that send Foil’s routes to that origin through the function on origin request:
<path>/v2/collect/*and<path>/t*.jswhen the integration URL has a path, or/v2/collect/*,/t.jsand/t.*.jswhen it’s the site root, so your own scripts keep their behaviors.
Origin fallback is the domain each request arrived on. Otherwise, it’s the integration’s site origin for all of them.
CloudFront requirements
- The integration hostname is an alternate domain name on the distribution.
- A deployment role that Foil assumes. Step 2 of the integration page shows the integration’s external ID and two policy templates with it filled in, ready to copy:
- A trust policy that lets Foil’s AWS principal assume the role only with the external ID. Its
Principalis Foil’s AWS principal, which you get from Foil. - A permissions policy that lets the role update the selected distribution, manage the integration’s Lambda@Edge function in
us-east-1, pass the execution role to it, and replicate it to edge locations.
- A trust policy that lets Foil’s AWS principal assume the role only with the external ID. Its
- A Lambda execution role that trusts
lambda.amazonaws.comandedgelambda.amazonaws.comand grants only CloudWatch Logs permissions.
Set up CloudFront
- Create the Lambda execution role and a deployment role in your AWS account. The form asks for both ARNs. You replace the deployment role’s policies in step 2, once the integration has an external ID.
- Under Who deploys it, choose Foil.
- Enter the Distribution ID, Deployment role ARN, and Lambda execution role ARN.
- Select Create integration.
- In step 1, publish the TXT record.
- In step 2, copy the trust policy and the permissions policy, and apply them to the deployment role.
- In step 3, select Install integration. Foil verifies the TXT record, publishes the function, and updates the distribution. CloudFront takes several minutes to propagate the change, and Foil keeps retrying the checks until the distribution is deployed.
- Continue with Add Foil to your pages.
AWS CloudFront with your Terraform
Deploying Foil’s edge with a Terraform module, on a CloudFront distribution you already manage with Terraform, is coming soon. Until it’s available, the create form offers only Foil under Who deploys it for CloudFront and notes that your own Terraform is coming soon. If Terraform manages your distribution today, run the edge as a Custom proxy on the distribution, or contact Foil.Custom proxy
Foil deploys nothing for a custom integration. You run the edge on your own CDN, load balancer, or reverse proxy and implement the custom edge contract: forward Foil’s routes toapi.usefoil.com, forward only the allowlisted headers, and add the proxy credential, integration ID, and visitor IP.
- Select Create integration.
- In step 1, publish the TXT record.
- In step 2, select Reveal proxy config. The dashboard shows the Integration ID, Forward to, Integration URL, Site origin, Credential, and Edge adapter version. Deploy your edge with those values.
- In step 3, select Start accepting traffic. Foil installs nothing on your CDN. It verifies the TXT record, starts accepting requests from your edge, and runs the checks.
- Continue with Add Foil to your pages.
t.js on the integration URL returns 401 before then.
Add Foil to your pages
Step 4 of the integration page takes you through three things in order:- Pick a publishable key in the integration’s environment. The page shows whether the key’s allowed origins cover the site origin, or the
https://*.<domain>wildcard when the integration serves every domain. If they don’t, select Add to allowed origins. To allow domains outside that wildcard, edit the key under API Keys. - If your site sets a Content Security Policy, add the
script-srcandconnect-srclines the page shows next to the install snippet. The snippet is an inline module script, so the policy must also allow it. See Content Security Policy. - Copy the install snippet into the
<head>of each page that should load Foil through the integration. It uses the value of the key you picked.
modulepreload link uses the path alone:
t.js from the integration URL and passes that URL as endpoint. See Load the SDK from your domain.
Verify the integration
-
Request the SDK through the integration URL:
The response has status
200and noSet-Cookieheader. - Load a page that runs the install snippet, then reload it once.
- In step 5 of the integration page, confirm that Domain verified, SDK loading, and Secure cookie round-trip pass. The integration moves to Active the next time the checks run. Select Re-check setup to run them right away.