> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Use a CDN or proxy

> Put Cloudflare, Fastly, Bunny, CloudFront or another proxy in front of an app domain.

A CDN in front of an app domain caches pages near your visitors and filters
traffic before it reaches the cluster. Turn on **Behind a CDN or proxy** in
the domain's settings (`behind_proxy` in [IaC](/iac/networking)). The settings
then show a preset for your CDN, the [origin lock](/iac/networking#origin-lock)
and a live setup checklist. **Check again** re-runs every check.

## Setup steps

Work through them in this order:

1. **Verify ownership.** The organization domain needs its `TXT` record, like
   any [app domain](/concepts/domains#organization-domains).
2. **Add the `_acme-challenge` CNAME.** It sends only the certificate
   challenge to A-Line, so the certificate is issued over DNS whatever the
   CDN does with HTTP (see [Behind a CDN or proxy](/concepts/domains#behind-a-proxy)).
3. **Wait for the certificate.** Get it issued *before* you turn the proxy
   on. A CDN that checks certificates strictly gets an error from A-Line until
   one exists.
4. **Point the domain at the CDN**, and the CDN at A-Line. The check fetches
   `https://<your domain>/` through the CDN and confirms it reached this app.
5. **Use HTTPS to the origin**, with the certificate checked. Never plain
   HTTP: on Cloudflare that is the Flexible mode.
6. **Turn on the origin lock** and have the CDN send `X-Aline-Origin-Key`, so
   nobody can skip the CDN by calling the load balancer directly.
7. **Optional: cache HTML at the edge** (see [what A-Line caches](#default-caching)).

## Cloudflare

1. **DNS > Records**: add the ownership `TXT` record and the
   `_acme-challenge` `CNAME` from the checklist. Set the CNAME's proxy status
   to **DNS only** (grey cloud).
2. Add the domain's `A`/`AAAA` (or `CNAME`) records as **DNS only** and wait
   until the checklist shows the certificate as issued.
3. Switch the domain's records to **Proxied** (orange cloud).
4. **SSL/TLS > Overview > Configure**: choose **Full (strict)**. Never
   Flexible: Cloudflare then talks plain HTTP to A-Line, so cookies, logins
   and the origin key cross the internet unencrypted, and the site loops on
   A-Line's redirect to HTTPS. A-Line always has a publicly trusted
   certificate, so Full (strict) costs you nothing.
5. **Rules > Transform Rules > Modify Request Header > Create rule**: when
   *Hostname equals* your domain, **Set static** header `X-Aline-Origin-Key`
   to the key you got when you turned on the origin lock.
6. Set the client IP header to `CF-Connecting-IP` (the preset does this) and
   save it: your app reads the visitor's address from it.
7. **Caching > Cache Rules > Create rule**: when *Hostname equals* your
   domain, choose **Eligible for cache** and Edge TTL **Use cache-control
   header if present**. Cloudflare caches by file extension only, so without
   this rule HTML is never cached at the edge.
8. **After a deploy**, HTML at the edge refreshes within a minute on its own.
   For it to change at once, use **Caching > Configuration > Purge Cache >
   Custom Purge** with your page URLs (or Purge Everything).

## Fastly

- **Origins > Hosts**: add the domain's addresses from the checklist on port
  443 with TLS on. Set the certificate hostname and SNI hostname to your
  domain, and keep the request's `Host` header.
- **Content > Headers > Create header**: type *Request*, action *Set*,
  destination `http.X-Aline-Origin-Key`, source your key in quotes.
- Client IP header: `Fastly-Client-IP`.
- Fastly follows A-Line's `Cache-Control` (`s-maxage`) without extra rules.
- Point your domain at Fastly (a `CNAME` to the service) once the certificate
  is issued.

## Bunny

- **Pull zone > General > Origin**: origin URL `https://` with one of the
  domain's addresses, and **Forward Host Header** on. Never an `http://`
  origin.
- **Edge Rules**: action *Set Request Header*, `X-Aline-Origin-Key`, your key.
- Client IP header: Bunny's own header for the visitor's address, if your
  pull zone sends one. `X-Forwarded-*` headers cannot be used.
- Set the cache expiration time to respect the origin's `Cache-Control`.
- Point your domain at the pull zone hostname once the certificate is issued.

## CloudFront

- **Origins**: origin domain is the app's A-Line hostname, protocol
  **HTTPS only** on port 443. Use the **AllViewer** origin request policy so
  your domain reaches A-Line as the `Host` header.
- **Origins > Add custom header**: `X-Aline-Origin-Key` with your key.
- Client IP header: `True-Client-IP`, set by a viewer-request CloudFront
  Function:

  ```js
  function handler(event) {
    event.request.headers['true-client-ip'] = { value: event.viewer.ip };
    return event.request;
  }
  ```
- Use a cache policy with Minimum TTL 0, so A-Line's `Cache-Control` decides.
- Add your domain as an alternate domain name and `CNAME` it to the
  distribution once the certificate is issued.

## Other proxies

Any reverse proxy works the same way: connect to the domain's addresses on
port 443 over HTTPS with the certificate checked against your domain, keep
the `Host` header, add `X-Aline-Origin-Key` to every request, and pass the
visitor's address in a header of your choice (not `X-Forwarded-*`).

## What A-Line caches by default

Static sites send these `Cache-Control` headers, which every CDN follows.
`s-maxage` applies only to shared caches such as a CDN; browsers revalidate
HTML on every visit. A site's `_headers` file overrides them per path.
Container apps send their own headers.

| Response | `Cache-Control` |
|---|---|
| HTML pages (also the single-page app fallback) | `public, max-age=0, s-maxage=60, stale-while-revalidate=86400` |
| Assets with a build fingerprint in the name | `public, max-age=31536000, immutable` |
| Service worker, web manifest | `no-cache` |
| Other assets | `public, max-age=300, s-maxage=3600` |
| 404 / 410 | `public, max-age=0, s-maxage=30` |
| 5xx | `no-store` |
| Redirects and other statuses | `no-cache` |
| Preview, version and temporary hosts | `private, no-store` |

## Troubleshooting

| You see | Why | Fix |
|---|---|---|
| 521 Web server is down | The CDN reached the address but nothing answered on 443 | Check that the origin addresses are the ones in the checklist |
| 522 Connection timed out | The CDN could not connect to the origin address | Point the origin at the checklist's addresses; nothing else is reachable |
| 525 SSL handshake failed | The CDN connected without your domain as SNI, or the app is not deployed | Send your domain as SNI, and check the domain's route is live |
| 526 Invalid SSL certificate | Full (strict) before the certificate was issued | Set the proxy to DNS only until the checklist shows the certificate issued |
| Too many redirects | Cloudflare Flexible: plain HTTP to A-Line, redirected to HTTPS | Set SSL/TLS to Full (strict) |
| 403 on every page | The origin lock is on, but the CDN does not send the key | Add the `X-Aline-Origin-Key` header rule with the current key |
| Visitor IP is the CDN's | No client IP header, or the origin lock is off | Turn on the origin lock and save the CDN's client IP header |
