Custom Domains

Custom Domains & SSL

Every Flux App automatically receives a default hostname, but production applications typically need a branded custom domain with SSL encryption. Flux provides built-in support for custom domains, automatic SSL certificate provisioning via Let's Encrypt, and DNS-based load balancing across your app instances. This guide covers the complete setup process.

Default Hostnames

When you deploy an app on Flux, it is immediately accessible via a default hostname following the pattern <appname>.app.runonflux.io. For example, an app named "my-web-app" is available at my-web-app.app.runonflux.io. This hostname resolves to all healthy instances of your app via round-robin DNS managed by the Flux Domain Manager (FDM). SSL is automatically provisioned for the default hostname — no configuration is needed.

You can also access individual instances directly via their node IP and port (e.g., http://157.230.45.123:31000), which is useful for debugging but not recommended for production traffic.

Setting Up a Custom Domain

To use a custom domain with your Flux App, you need to complete two steps: configure a DNS record with your domain registrar, and add the domain to your app specification in the FluxOS dashboard.

1. 1

   Add the domain to your app specification

   In the FluxOS dashboard at home.runonflux.io, navigate to "My Apps", select your app, and click "Update". In the domains field, add your custom domain (e.g., "app.yourdomain.com"). Submit the update and sign it with your Zel ID.

2. 2

   Create a CNAME DNS record

   Log into your domain registrar or DNS provider (e.g., Cloudflare, Namecheap, Route53). Create a CNAME record pointing your custom domain to your Flux app's default hostname.

3. 3

   Wait for DNS propagation

   DNS changes can take anywhere from a few minutes to 48 hours to propagate globally, though most providers propagate within 5-30 minutes. Use a tool like dig or nslookup to verify propagation.

4. 4

   Verify SSL certificate

   Once DNS resolves correctly, the Flux Domain Manager automatically requests an SSL certificate from Let's Encrypt. This usually completes within a few minutes. Your custom domain will then be accessible via HTTPS.

DNS Configuration Step-by-Step

Here is the exact DNS record you need to create:

# Check CNAME record
dig CNAME app.yourdomain.com +short
# Expected output: my-web-app.app.runonflux.io.

# Check full resolution
dig app.yourdomain.com +short
# Expected output: multiple IP addresses of Flux nodes

# Alternative using nslookup
nslookup app.yourdomain.com

SSL Certificate Auto-Provisioning

Flux uses Let's Encrypt to automatically provision and renew SSL certificates for your custom domains. Once your CNAME record is properly configured and DNS has propagated, the Flux Domain Manager detects the new domain and initiates a certificate request. The process is fully automatic — no manual certificate management is required.

• •Certificates are provisioned via the HTTP-01 ACME challenge
• •Certificate issuance typically completes within 1-5 minutes after DNS propagation
• •Certificates are automatically renewed before expiration (Let's Encrypt certificates last 90 days)
• •Both RSA and ECDSA certificates are supported
• •HTTPS is enforced by default — HTTP requests are redirected to HTTPS

Multiple Domain & Subdomain Support

You can assign multiple custom domains to a single Flux App. This is useful for supporting both a root domain and subdomains, or multiple brand domains pointing to the same application. Add all desired domains to the domains array in your app specification:

{
  "domains": [
    "app.yourdomain.com",
    "www.yourdomain.com",
    "api.yourdomain.com"
  ]
}

Each domain needs its own CNAME record pointing to your Flux hostname. SSL certificates are provisioned separately for each domain. Note that bare/apex domains (e.g., yourdomain.com without a subdomain prefix) require special handling because CNAME records are not allowed at the DNS zone apex per the RFC specification. Some DNS providers (like Cloudflare) offer CNAME flattening or ALIAS records that work around this limitation.

Using Cloudflare with Flux Apps

Cloudflare is a popular choice for DNS and CDN services. When using Cloudflare with Flux Apps, pay attention to the proxy mode setting:

• •DNS Only mode (grey cloud) — Cloudflare acts purely as a DNS provider. Traffic goes directly to Flux nodes. Flux handles SSL via Let's Encrypt. This is the simplest and recommended configuration.
• •Proxied mode (orange cloud) — Cloudflare proxies all traffic through its CDN. This adds Cloudflare's DDoS protection, caching, and WAF. However, SSL is terminated at Cloudflare's edge, and Cloudflare connects to Flux using its own certificate. Set the SSL mode to "Full (Strict)" in Cloudflare to maintain end-to-end encryption.

The Flux Domain Manager (FDM)

The Flux Domain Manager (FDM) is the system responsible for routing traffic to your app instances. It performs several critical functions:

• •DNS resolution — Resolves your app hostname to the IP addresses of healthy instances
• •Health checking — Periodically probes each instance to verify it is responsive. Unhealthy instances are removed from DNS rotation.
• •Load balancing — Distributes incoming requests across instances using round-robin DNS
• •SSL termination — Manages TLS certificates and terminates HTTPS connections at the edge
• •Domain routing — Maps custom domains to the correct app and port

The FDM operates as a distributed system across the Flux network, with no single point of failure. If one FDM node goes offline, other FDM nodes continue to handle DNS resolution and routing.

Troubleshooting DNS & SSL Issues

1. 1

   Domain not resolving

   Verify the CNAME record is correctly configured using "dig CNAME yourdomain.com +short". If the record exists but is not resolving, wait up to 48 hours for full DNS propagation. Check that the CNAME target matches your exact Flux app hostname.

2. 2

   SSL certificate not provisioning

   The Let's Encrypt HTTP-01 challenge requires that port 80 is accessible and that DNS resolves to Flux nodes. If using Cloudflare proxied mode, temporarily switch to DNS Only mode to allow the challenge to complete, then re-enable proxying.

3. 3

   ERR_TOO_MANY_REDIRECTS

   This typically occurs when Cloudflare is in proxied mode with SSL set to "Flexible". Change Cloudflare SSL mode to "Full" or "Full (Strict)" to resolve the redirect loop.

4. 4

   Domain works intermittently

   This may indicate that some DNS resolvers have cached the old record while others have the new one. Wait for full propagation. You can flush DNS caches locally with "ipconfig /flushdns" on Windows or "sudo dscacheutil -flushcache" on macOS.

5. 5

   Mixed content warnings

   Ensure your application generates all internal URLs with HTTPS. If your app references HTTP resources, browsers will block or warn about mixed content. Update your application to use protocol-relative or HTTPS URLs.

Best Practices for Production Domains

• •Use subdomains (app.yourdomain.com) rather than bare domains to avoid CNAME-at-apex issues
• •Set low TTL values (300 seconds) during initial setup so DNS changes propagate quickly. Increase TTL to 3600+ seconds after everything is stable.
• •Monitor SSL expiration — While Flux auto-renews certificates, set up external monitoring (e.g., Uptime Kuma, SSL Labs) to alert you if renewal fails.
• •Keep domain in your app spec — If you update your app specification, make sure the domains field still includes all your custom domains. Removing a domain from the spec will stop routing traffic to your app for that domain.
• •Plan for zero-downtime updates — When updating your app, existing TLS sessions may be interrupted. Consider using Cloudflare or another CDN to absorb connection resets during updates.
• •Document your DNS configuration — Maintain a record of all DNS entries associated with your Flux apps. This simplifies troubleshooting and team onboarding.

Custom domains and SSL are essential for presenting a professional, trustworthy application to your users. Flux's automatic SSL provisioning and DNS-based load balancing make the setup straightforward, while the flexibility to use external DNS providers like Cloudflare gives you full control over your domain infrastructure.