Skip to main content

​
Cloudflare

This page shows how to move your domain to Cloudflare and configure DNS, CDN caching, and SSL/TLS so traffic reaches your Refract backend safely.
📖 See also: Cloudflare R2 CDN for user-upload object storage (profile pictures) — R2 bucket setup, S3-compatible credentials, and custom-domain publicUrl configuration are separate from app-origin DNS on this page.

​
How it works

Cloudflare sits at the edge in front of your origin deployment, resolves your DNS records, serves cached static assets when possible, and handles certificate management for inbound HTTPS.

​
Extending this system

Use this recipe to onboard or migrate a production domain to Cloudflare for Refract.
  1. Prepare the current DNS zone Export your current DNS records from your existing registrar/DNS host. Reduce TTL on critical records (for example A, CNAME, and MX) to speed up cutover.
  2. Transfer or delegate your domain to Cloudflare In Cloudflare, add the domain and choose either full registrar transfer or nameserver delegation. Confirm all imported DNS records are complete before switching traffic.
  3. Point app hostnames to origin Create proxied DNS records for your production hostnames (orange cloud enabled). Point these at your hosting provider target (for example Railway-generated domain).
  4. Configure SSL/TLS and edge behavior Set SSL/TLS mode to Full (strict) and enable automatic HTTPS rewrites. Add cache rules for static assets and keep API/GraphQL routes uncached.
  5. Validate and monitor Verify certificate status, DNS resolution, and app behavior from multiple networks. Keep a rollback plan ready for mail/DNS misconfiguration during the first hour.
  6. Optional: create email aliases with Cloudflare Email Routing
If you want aliases like [email protected] that forward to your real mailbox, you can use Cloudflare Email Routing.
  1. In the Cloudflare dashboard, open Email Routing and enable it.
  2. Review the records Cloudflare wants to add (it will add the required MX and TXT records to your DNS zone).
  3. Create a Custom address (for example [email protected]).
  4. Add your Destination address (the mailbox you want to forward to), then verify the destination email Cloudflare sends for.
  5. Activate and test by sending an email to your new alias.
Notes:
  • When Email Routing is enabled, no other email services can be active for the domain. Cloudflare will prompt you to delete existing MX records if they conflict.
  • Email Routing forwarding supports a single destination email per custom address. If you need multiple destinations, create a Workers redirect (Cloudflare describes this flow in their Email Routing docs).
⚠️ Watch out: MX/mail records must stay correct. This overlaps with the anti-pattern below: keep mail-related DNS records unproxied.
  1. Verify in project workflow Run the normal project build checks after domain/env updates.

​
What not to do

❌ Never use Flexible SSL in production. It can create redirect loops and weak origin security. ❌ Never proxy mail records (MX, most mail-related TXT/CNAME) through Cloudflare CDN. ❌ Never enable Email Routing while the domain still has competing MX records from another email provider. ❌ Never cache authenticated or mutation API routes such as GraphQL POST operations. ❌ Never change DNS and SSL settings during an active incident without a rollback owner.

​
File conventions

Infrastructure docs for deployment providers live in apps/documentation/deployment/ and use lowercase provider filenames like cloudflare.mdx, railway.mdx, and fly.mdx (if added later). For domain or DNS docs updates:
  • put provider-specific operational guidance in apps/documentation/deployment/cloudflare.mdx
  • keep quality/process guidance in apps/documentation/quality/documentation.mdx
  • add or update navigation entries in apps/documentation/docs.json

​
What’s next?

  • Railway for origin deployment configuration behind Cloudflare.
  • Configuration for APP_URL, PORT, and production env setup.
  • Documentation for style and publishing rules.