Getting Started with Turbulence

Setting up Turbulence for a domain takes a few minutes. You create a Turbulence site in the PicPerf dashboard, copy the DNS records it gives you, add them to wherever your DNS is managed, and wait for verification. That’s it. You don’t need to touch your server, your codebase, or your hosting provider — your origin stays exactly as it is.

This guide walks through the whole process, with a focus on making it work no matter who your DNS provider is.

Free setup help

DNS can be fiddly depending on your provider — apex domains, TXT record formatting, and origin configuration trip people up more often than the Turbulence side of things. If you’d like a hand getting your domain pointed at Turbulence, I’m happy to walk you through it at no extra charge. Get in touch on my contact page and we’ll get you sorted.

A Quick Note on How DNS Works (Just Enough)

When someone visits https://www.yourdomain.com/, their browser needs to know which server to ask for the page. The DNS system is the lookup table that answers that question. To use Turbulence, you’ll be adding two kinds of entries to that lookup table:

• A TXT record. This is a free-form text entry used for verification. It proves to PicPerf that you actually control the domain.
• A CNAME record. This tells the rest of the internet “instead of asking my server, ask this other server.” That other server is Turbulence.

If those terms feel new, the rest of this guide is written so you don’t need to know more than that to get going. Just follow the steps.

Step 1: Create an Account and Turbulence Plan

Turbulence requires a PicPerf account with an active Turbulence subscription. Sign up at go.picperf.io/signup/turbulence — new Turbulence plans include a 14-day free trial.

Once subscribed, open the dashboard at go.picperf.io and go to Turbulence. If you don’t have a subscription yet, you’ll see plan options instead of the domain list.

Step 2: Add a Domain

On the Turbulence page, use Add Domain and fill in two fields:

• Custom Domain — the hostname visitors will use, e.g. www.yourdomain.com or yourdomain.com. This is what you’ll point at Turbulence with a CNAME.
• Origin — where Turbulence fetches your HTML when the cache needs a refresh. Enter a hostname (recommended), e.g. origin.yourhosting.com, or a bare IP address if your server has no public hostname. Do not include https:// — the dashboard strips protocol prefixes automatically.

Both fields are required. After submitting, you’re taken to the domain’s setup page with the exact DNS records to add. Keep that page open for the next step.

Step 3: Add the DNS Records

Open a new tab and go to wherever your DNS is managed. That could be your domain registrar (GoDaddy, Namecheap, Google Domains, Squarespace Domains, etc.) or a dedicated DNS service like Cloudflare or AWS Route 53. The interface will look different in each case, but the records themselves are the same.

Record #1: A TXT Record for Verification

This proves to PicPerf (via Cloudflare custom hostname verification) that you control the domain. It’s a simple text entry with no effect on how your site loads.

The dashboard shows the exact Name and Value to use — copy them from the Verification TXT Record section on your domain’s setup page. For the type, choose TXT.

A typical example might look like this:

Field	Value (example)
Type	TXT
Name	_cf-customhostname.yourdomain.com
Value	abc123def456...

The name format comes from Cloudflare and varies per domain. Always use the values shown in your dashboard, not a generic placeholder.

A few things to watch out for:

• Your provider might prepend your domain automatically. Cloudflare custom hostname verification names often look like _cf-customhostname.yourdomain.com. Some DNS UIs want just the subdomain portion (_cf-customhostname) and append the root domain for you; others want the full hostname. Match however your other records are formatted — the dashboard shows the exact string to copy.
• The value often has to be wrapped in quotes. Some DNS providers expect the TXT value in double quotes. Your provider’s documentation will tell you, or it will reject the record if quotes are required and missing.
• TXT records can take a few minutes to propagate. DNS is eventually consistent, so don’t panic if verification doesn’t happen immediately.

Record #2: A CNAME Record to Route Traffic

This is the one that actually points your domain at Turbulence. Once this is in place, requests for your hostname will flow through PicPerf’s edge instead of directly to your origin.

Field	Value (example)
Type	CNAME
Name	www.yourdomain.com (your full custom domain)
Value	optimize.picperf.io

The dashboard’s CNAME Record section shows your hostname as the Name and optimize.picperf.io as the Target. Some DNS providers want just the subdomain portion (e.g. www) if they append the root domain automatically — match however your other records are formatted.

If You’re Pointing a Subdomain (e.g., www.yourdomain.com)

This is the easy case. Every DNS provider supports CNAME records on subdomains. Just create the record with the values above (using whatever subdomain you chose) and you’re done.

If You’re Pointing the Root Domain (e.g., yourdomain.com)

The DNS specification doesn’t allow a CNAME at the root (apex) of a domain. This used to be a hard problem, but most modern DNS providers have a workaround:

• Cloudflare: supports “CNAME flattening” automatically. You can add a CNAME for the root domain and Cloudflare will resolve it to an IP behind the scenes.
• AWS Route 53: supports “alias” records, which serve the same purpose as a CNAME at the apex. Look for the alias record type, not the CNAME type.
• Most other providers (GoDaddy, Namecheap, Google Domains, etc.): will either let you add a CNAME at the root and flatten it for you, or they’ll direct you to a special “ALIAS” / “ANAME” / “Forward” record type. If CNAME at the root is rejected, look for one of those alternatives.

The “Name” field for a root record is usually just @ or left blank — your provider’s docs will tell you which.

If your provider truly doesn’t support any kind of root-level CNAME, the simplest workaround is to use a subdomain like www (or any other) as your primary hostname, and redirect the root domain to it from your registrar.

Step 4: Wait for Verification

Once both records are in place, return to your domain’s setup page in the dashboard. The status badge next to Verification TXT Record updates automatically — Pending Verification while Cloudflare is checking, then Verified when complete. The page polls for status changes every few seconds, so you don’t need to refresh manually.

Verification usually completes within a few minutes, though DNS propagation can occasionally take longer.

You can also check from a terminal (substitute the exact verification name from your dashboard):

# Check the TXT record (use the Name value from your dashboard)
dig TXT _cf-customhostname.yourdomain.com

# Check the CNAME record
dig CNAME www.yourdomain.com

The TXT lookup should return the value shown in your dashboard. The CNAME should point to optimize.picperf.io (or a flattened IP, depending on your provider).

Step 5: Test a Request

Once verification is complete, open your domain in a browser. You should see the same site as before. To confirm it’s actually going through Turbulence, check the response headers — see Verifying It Works for the specific headers to look for.

Step 6: Update Your Origin (If Needed)

The origin is set when you add the domain, but you can change it anytime on the domain’s setup page under Origin. Turbulence syncs the new value to its edge configuration automatically.

For most setups, the origin should be a hostname the worker can reach without going through Turbulence. If you’re CNAMEing www.yourdomain.com to PicPerf, don’t use www.yourdomain.com as the origin — that would create a loop. Use a direct hostname (e.g. origin.yourhosting.com) or your server’s IP instead.

IP-Based Origins

If your origin is a bare IP address (e.g. 137.184.100.119), enter it directly in the Origin field. PicPerf stores it as an IP origin (ip:x.x.x.x in edge configuration) and routes fetches through an origin relay at go.picperf.io/api/cloudflare/turbulence-origin-fetch — Cloudflare Workers can’t open TLS connections to bare IPs directly, so the relay performs the handshake with your server’s hostname as SNI. No extra configuration is needed beyond entering the IP.

Configuring Cache and Settings

Each domain has a Settings tab in the dashboard where you can adjust the cache TTL (how long transformed HTML is considered fresh before background revalidation). Default: 3600 seconds (1 hour). Valid range: 60 seconds to 86400 seconds (24 hours). Changes sync to the edge automatically when you save.

For details on how caching, stale-while-revalidate, and cache-bypass parameters work, see Caching.

Adding a Second Hostname

Once your first hostname is working, you can add as many more as you want through the same dashboard. Each one gets its own TXT + CNAME records to add, and they’re verified and managed independently. A common pattern is to set up www first, then add the root domain as a second hostname once you’re confident things are working.

Rolling Back

If something goes wrong and you need to put things back the way they were, just remove the CNAME record from your DNS. Traffic will resume flowing to whatever’s listed in your other DNS records (usually an A record pointing to your original server). The TXT record can stay or be removed — it has no effect on traffic.

Your origin, code, and hosting stay untouched the whole time, so rolling back is just a matter of editing DNS.