Skip to main content
Open console

CDN

Serve your site from the edge, and clear its cache from your own code.

11 min read

A CDN serves copies of your site from datacentres near your visitors. You buy an amount, and the platform sets up the pull zone, your domains and their certificates.

Buying it

Buy it in the configurator when you set a project up, or afterwards under Commercial terms on the project's configuration page, under Edge. It is bought by the terabyte a month, minimum one, on one of two networks.

It is a commitment, not a meter: you pay for what you bought whether or not you use it. The CDN tab shows what you have served this month.

Raising the amount takes effect at once, charged for the rest of the period. Lowering it, or setting it to zero, takes over at your next invoice. Until then you keep what you bought, and it is not credited. See Billing.

Once zero applies, the pull zone is removed, and your domains stop being served from the edge the moment DNS catches up.

Pointing a domain at it

  1. Add your domain under Routing and prove you control it.
  2. Copy the address the CDN tab shows and point the domain at it.
  3. Wait for the certificate, issued once the name resolves to the edge.

An apex domain cannot hold a CNAME. If your DNS provider offers ALIAS or ANAME, point that at the same name; if not, use a subdomain such as www. Either way, remove the records it had before. An old A or AAAA left beside the new one sends some visitors to your old address and stops the certificate being issued.

The console attaches the hostname, asks for the certificate and tells you when it is ready. Until then the name does not serve over HTTPS: the CDN is waiting for your DNS. After that, the CDN sends every plain HTTP request on that name to HTTPS.

The CDN is for your own domains. An environment's …vallic.cloud hostname is never put behind it: it stays a direct route to the machine.

If your site cannot answer, because it is restarting or a request runs out of time, visitors see the same error page the platform's edge shows, not the CDN's. It carries the status, your hostname and their own address to quote.

Clearing the cache from your code

Your application can clear the cache without any credential. These variables arrive in the environment only when the CDN is on:

VALLIC_CDN_PURGE_SOCKET=/run/vallic-cdn/purge.sock
VALLIC_CDN_PURGE_URL=http://localhost/purge
VALLIC_CDN_PURGE_TOKEN=…

Send the request through the socket; the URL supplies only the path.

Drupal

Install Vallic Purge, which needs Drupal 11.3 or later and no configuration:

composer require 'drupal/vallic_purge:^2.0'
drush en vallic_purge

It tags every public page and clears exactly the pages a change affects, once the request that saved it ends. Then:

  1. Export your configuration, so every environment has the module on its next deploy.
  2. Set Browser and proxy cache maximum age under Configuration → Development → Performance.

Until Drupal says a page may be cached, the CDN keeps no copy of it. Pages for signed-in visitors are sent as private and are never cached, whatever this is set to.

Keep the module enabled everywhere. On your laptop, in CI, or on an environment without the CDN, it sends nothing and adds nothing to your responses. The status report shows which of those it is.

Cache Purifier, which comes with it, decides which tags reach the CDN: its rules can stop, say, visitors' comments from purging anything.

A site on 1.x, which went through the Purge module, upgrades as the module's README says.

Anything else

Send a POST through the socket, with the token as a bearer:

{"scope": "all"}
{"scope": "url", "values": ["https://www.example.com/news"]}
{"scope": "tag", "values": ["* node:42 *"]}
Scope Clears
all The whole cache. For after a deploy that changed templates.
url Individual addresses. Only hostnames this environment answers on are accepted; anything else is ignored without failing the batch.
tag Every response whose tags match. For a CMS that already knows which pages a change affects.

You never name the pull zone: the token decides which environment is asking. Treat it like any other secret in the environment.

Tagging a response

Tag a response with a CDN-Tag header. The CDN keeps it as one string, not a list, and matches each purge value against the whole string, with * standing for anything. So a page sent with

CDN-Tag: : node:42 node_list :

is cleared by * node:42 *, but not by node:42, which only matches a header that is exactly node:42. Separate the tags with spaces and put a character at each end, as above, so every tag has a space on both sides. Purge with * tag *.

Keep the header short: one that runs to many kilobytes can be refused on the way out, which fails the page instead of caching it. Shorten long tags to a hash of a few characters and purge by the same hash. The Drupal module writes each tag as five characters, and stops before the CDN's 1024 bytes.

After a deploy

A deploy does not clear the CDN: a release that changes templates, stylesheets or scripts leaves the old pages at the edge until they expire. To start a release from an empty cache, clear it in the last deploy step.

Emptying the cache makes every page miss at once, so your machine is at its busiest in the minutes after a release. A site that already clears by tag often needs this only when the look of the site changed.

For Drupal with Vallic Purge:

deploy:
  steps:
    - 'drush deploy'
    - 'drush vallic-purge:all'

If the platform can't be reached at that moment, the purge waits for cron and the step still succeeds, so a release is never rolled back over it.

For anything else:

deploy:
  steps:
    - '[ -z "$VALLIC_CDN_PURGE_URL" ] || curl -fsS --unix-socket "$VALLIC_CDN_PURGE_SOCKET" -X POST "$VALLIC_CDN_PURGE_URL" -H "Authorization: Bearer $VALLIC_CDN_PURGE_TOKEN" -d "{\"scope\":\"all\"}"'

The test at the front skips the call where the CDN is off, so the same manifest deploys staging too.

By hand: Clear the CDN cache on the environment's CDN tab, for anybody who can deploy.

Who is really asking

Behind a CDN, the address your framework reports is one of a few hundred edge servers, not your visitor's. Two headers carry the visitor instead, on every request:

X-Vallic-Ip: 203.0.113.9
X-Vallic-Country: DE

Read X-Vallic-Ip wherever you would have read the client address: rate limiting, fraud checks, anything that logs who did what. X-Vallic-Country is the visitor's country as a two-letter code, for a price list or a language default.

What reaches your application was set by your zone. Requests from another Bunny account's zone pointed at your site are refused. A request sent straight to your platform hostname, round the CDN, has both headers taken off before your application sees it.

What is cached, and what never is

A page your application marks private, no-cache or no-store is never cached, whatever else is configured.

A response with no Cache-Control at all is kept for 30 days, by the CDN and by browsers. A bare JSON route often sends none, so send one from anything that changes: no-store, or a short s-maxage as below. A browser cache time for pages of 0 minutes takes browsers out of it, and the CDN's copy then goes when you clear it.

For the CDN to keep a response that browsers should not, say so with s-maxage rather than no-store:

Cache-Control: public, max-age=0, s-maxage=3600

The CDN keeps it for the hour, and every browser asks again each time. no-store means no cache at all, the CDN included. A browser cache time for pages chosen below replaces the max-age=0, on HTML and API answers alike; leave it at As your site says if your site decides per response.

Signed-in visitors

A request from a signed-in visitor is answered by your site, never from the CDN, and reaches their browser as private, no-cache.

Static files are the exception. A stylesheet, script, image, font or video (.css, .js, .png, .jpg, .webp, .svg, .woff2, .mp4 and the like) comes from the CDN whether or not the visitor is signed in, unless your application marks it private, as Drupal does a private file.

Signed-in means the request carries your application's session cookie, under its framework's default name:

Application Session cookies
Drupal SESS…, SSESS…
WordPress wordpress_logged_in_…, wp-postpass_…
Laravel laravel_session
PHP (Symfony and others) PHPSESSID
Node.js connect.sid (Express)
Python session… (Flask)
Django sessionid
Rails named after the application, such as _shop_session — name yours under Session cookies
Go, Rust none — name yours under Session cookies
Static site none: nobody signs in to files

A session under another name goes under Session cookies on the CDN tab.

Settings on the CDN tab

On the environment's CDN tab:

  • Dynamic cache lets the CDN decide what is cacheable from your response headers, not by file type. For a site that will not be purging by URL or cache tag. Leave it off if you have tuned your cache headers yourself.
  • Browser cache time for pages and for static files, with Dynamic cache off: see Browser cache time.
  • Vary the cache by WebP or AVIF support, mobile against desktop, country, region, hostname or cookie. Each one keeps a separate copy of every page per value, and two of them multiply, so tick only what your site serves differently. Cookie takes the names of the cookies that matter, such as a language or currency choice; every other cookie is ignored. A session cookie cannot be one of them.
  • Request headers to vary by, one name per line, for a site that answers differently by a header such as Accept-Language. Cookie and User-Agent cannot be used.
  • Blocked countries are refused at the edge and never reach your site.
  • Session cookies, one name per line, for a session your application names differently from its framework's default. For a cookie with a varying suffix, give the start of the name. A visitor carrying one counts as signed in. Up to five; names only, so letters, digits, dots, dashes and underscores.
  • Never cache these paths, such as /admin/* or /cart, for anything that should always come from your application. They reach browsers as private, no-cache, whatever your site sent. Up to twenty.

The tab always shows what the edge is doing.

Browser cache time

With Dynamic cache off, these set how long visitors' browsers keep a copy before asking again:

Setting Choices Applies to
Browser cache time for pages 0, 1, 5, 15 or 60 minutes, or a day Pages, and an API's answer: JSON (REST, GraphQL, JSON:API) and XML (feeds, sitemaps)
Browser cache time for static files 1, 7 or 30 days Anything that is not a page: stylesheets, scripts, images and fonts, and PDFs, video and downloads too

The two are told apart by the Content-Type your site sends. Plain text such as robots.txt and CSV exports are left to your site.

  • At 0 minutes browsers ask every time, and the CDN still answers from its copy, so clearing the CDN reaches everybody at once.
  • Left at As your site says, your own Cache-Control decides. A long one means a browser goes on showing an old copy after you purge the CDN.
  • Keep the page time short on a site people sign in to. A page somebody saw signed out stays in their browser, signed out, for that long after they sign in.
  • A time is set, not capped: a response you mark for one minute is kept for the chosen time too.
  • Both change only what browsers are told. The CDN still keeps a response as long as your site says, so your site is not asked more often.
  • Signed-in visitors are always told private, no-cache, and anything your site marks private, no-cache or no-store keeps that.

Decided for every site

These are not switches:

  • The query string is always part of the cache key, so ?page=2 is never served the first page.
  • A stale copy is served while your site is slow or down.
  • An error response is never stored, so the edge stops serving it the moment your site answers again.
  • Redirects are passed to the browser, not followed at the edge.

How it is bought

By the terabyte a month, on one of two networks:

Network Reaches Price Suits
Volume network, selected to begin with 10 locations across Europe, Asia and North and South America One price everywhere, a fraction of the Standard network's Most sites
Standard network 119 locations worldwide By the datacentre you chose Visitors who are spread out

Anybody far from a Volume location gets a slower first byte.

You can move between them later; the pull zone stays and no hostname is lost. Moving to the Standard network happens at once. Moving to the Volume network is a reduction, so it takes over at your next invoice.

On the Standard network, Europe and North America is the cheapest, then Asia and Oceania, then South America, then the Middle East and Africa. Change the datacentre in the configurator and the figure moves with it. The configurator and the Commercial terms card both show what will be invoiced.

Two older arrangements stay until you change them:

  • A project that was behind the CDN before there was a choice is on the Standard network.
  • A CDN bought by the hundred gigabytes keeps its amount and its price. A new amount is rounded up to whole terabytes.

Next

  • Domains — adding a domain and proving it
  • Variables — where the purge settings arrive