How We Handle Custom Domains: DNS, SSL, and Routing Automation

How We Handle Custom Domains: DNS, SSL, and Routing Automation

Adding a custom domain to your app should be one click, not a multi-step manual process involving DNS configuration, SSL certificate provisioning, and reverse proxy setup. Deployxa automates all of this: you add the domain, configure one DNS record, and the platform handles SSL provisioning and routing automatically. Here is how the system works.

The direct answer is that Deployxa's custom domain system has three components: the domain registration (which adds the domain to the platform and provides DNS instructions), the SSL provisioning (which obtains an SSL certificate via Let's Encrypt), and the routing configuration (which configures Traefik to route traffic from the domain to the container). The system is fully automated, which means you do not need to manually obtain SSL certificates, configure reverse proxies, or manage DNS records (beyond the initial CNAME). For more on SSL, see our article on how we handle SSL at scale.

The Three Components

1. The domain registration

When you add a custom domain in the Deployxa dashboard, the platform registers the domain and provides DNS instructions. For subdomains (e.g., app.myapp.com), the instruction is to add a CNAME record pointing to cname.deployxa.app. For apex domains (e.g., myapp.com), the instruction is to add an A record pointing to Deployxa's IP (or to use a DNS provider that supports ALIAS/ANAME records). The platform checks DNS propagation periodically and proceeds once the DNS is propagated.

2. The SSL provisioning

Once the DNS is propagated, the platform provisions an SSL certificate via Let's Encrypt. The platform uses the HTTP-01 challenge (serving a specific file on the domain) to verify domain ownership. Once verified, Let's Encrypt issues the certificate, which the platform installs in Traefik. The entire process takes 30-60 seconds. The platform also handles certificate renewal automatically (certificates expire every 90 days and are renewed 30 days before expiration).

3. The routing configuration

Once the SSL certificate is provisioned, the platform configures Traefik to route traffic from the custom domain to the container. Traefik's dynamic configuration (via Docker labels) means the routing is updated without a reload, which means there is no downtime during the configuration change. Traefik handles SSL termination (the connection between the user and Traefik is encrypted) and proxies the request to the container (the connection between Traefik and the container is unencrypted, but on the same host, so it is secure).

Step-by-Step: How a Custom Domain Is Added

Here is the step-by-step process for adding a custom domain.

Step 1: The user adds the domain

In the Deployxa dashboard, the user enters the custom domain (e.g., myapp.com) and clicks "Add Domain".

Step 2: The platform provides DNS instructions

The platform displays the DNS instructions: "Add a CNAME record: myapp.com -> cname.deployxa.app". The user adds the CNAME record in their DNS provider.

Step 3: The platform checks DNS propagation

The platform checks DNS propagation every 60 seconds. Once the DNS resolves to Deployxa's infrastructure, the platform proceeds to SSL provisioning.

Step 4: The platform provisions the SSL certificate

The platform runs the Let's Encrypt HTTP-01 challenge, which verifies domain ownership. Once verified, Let's Encrypt issues the certificate, and the platform installs it in Traefik.

Step 5: The platform configures routing

The platform configures Traefik to route traffic from myapp.com to the container. The routing is updated dynamically (no reload), which means there is no downtime.

Step 6: The platform verifies the setup

The platform runs deployxa doctor to verify the setup: SSL is valid, DNS is correct, routing is working, and the app is healthy.

Step 7: The user is notified

The dashboard shows the domain as "Active", and the user is notified that their custom domain is live with SSL.

Common Pitfalls and Troubleshooting

The first pitfall is DNS propagation delays. DNS propagation can take anywhere from a few minutes to 48 hours, which means the platform needs to be patient. The fix is to check DNS periodically and to provide clear instructions to the user. The second pitfall is DNS misconfiguration. The user might configure the DNS records incorrectly (e.g., wrong CNAME target, wrong record type), which prevents propagation. The fix is to provide clear instructions and to verify the DNS configuration. The third pitfall is SSL provisioning failures. SSL provisioning can fail for various reasons (e.g., Let's Encrypt rate limits, domain validation failures), which means the platform needs to handle failures gracefully. The fix is to retry SSL provisioning and to troubleshoot if retries fail. The fourth pitfall is apex domain issues. Apex domains (e.g., myapp.com) cannot use CNAME records (in standard DNS), which means they need an A record or an ALIAS record. The fix is to provide different instructions for apex domains (A record) and subdomains (CNAME record). The fifth pitfall is wildcard domains. Wildcard domains (e.g., *.myapp.com) require a different SSL certificate (a wildcard certificate), which might need additional configuration.

How Custom Domains Integrate with the Readiness Engine

The custom domain check is one of the 14 checks in the readiness engine. The check verifies that the custom domain is configured correctly (DNS, SSL, routing). If the check fails, the readiness grade drops, which catches domain configuration issues before they affect users.

Advanced Custom Domain Patterns

Beyond the basics, the custom domain system supports several advanced patterns. The first is wildcard domains. Wildcard domains (e.g., *.myapp.com) allow you to serve any subdomain (e.g., user1.myapp.com, user2.myapp.com) from a single app. This is useful for multi-tenant apps where each user gets their own subdomain. The system provisions a wildcard SSL certificate (via Let's Encrypt's DNS-01 challenge), which covers all subdomains. For more on multi-tenant patterns, see our article on the state management mess.

The second pattern is apex domain support. Apex domains (e.g., myapp.com) cannot use CNAME records (in standard DNS), which means they need an A record or an ALIAS record. The system supports apex domains by providing an A record target (Deployxa's IP address) and by using Cloudflare's CNAME flattening (which allows CNAME records at the apex). This means apex domains work the same as subdomains, without any special configuration.

The third pattern is domain forwarding. The system supports domain forwarding (e.g., redirect www.myapp.com to myapp.com), which is useful for SEO (to avoid duplicate content) and for user experience (users who type www are redirected to the non-www version). The forwarding is configured via the dashboard and handled by Traefik.

The fourth pattern is custom SSL certificates. For apps that need custom SSL certificates (e.g., EV certificates, wildcard certificates from a commercial CA), the system supports uploading custom certificates. This is useful for enterprise apps that require specific certificate types for compliance.

The fifth pattern is domain health monitoring. The system monitors each custom domain's health (DNS resolution, SSL validity, HTTP response) and alerts if any check fails. This catches domain configuration issues (e.g., DNS misconfiguration, SSL expiration) before they affect users.

How Custom Domains Integrate with the MCP Server

The custom domain system is exposed via the Deployxa MCP server as the deployxa_add_domain, deployxa_get_ssl_status, and deployxa_get_domains tools. This means your AI assistant (in Cursor or Claude Desktop) can add domains, check SSL status, and list domains directly. For example, you can say "add myapp.com to my app," and your AI assistant calls deployxa_add_domain, provides DNS instructions, waits for DNS propagation, checks SSL status, and reports when the domain is live. This is the agentic domain management workflow. For more on this, see our article on building an AI agent that manages custom domains.

Lessons Learned

Building the custom domain system taught us several lessons. First, DNS propagation is the biggest bottleneck. DNS propagation can take anywhere from a few minutes to 48 hours, which means the domain setup process needs to be patient. The system checks DNS propagation every 60 seconds and proceeds once the DNS is propagated, which balances patience with speed. Second, Let's Encrypt is reliable but has rate limits. Let's Encrypt has rate limits (e.g., 50 certificates per registered domain per week, 5 duplicate certificates per week), which means you need to cache certificates and avoid unnecessary re-issuance. The system caches certificates and renews them 30 days before expiration, which avoids hitting the rate limits. Third, the HTTP-01 challenge is simple but has limitations. The HTTP-01 challenge requires the domain to serve HTTP traffic on port 80, which some DNS providers (e.g., those that proxy traffic) do not support. The system falls back to the DNS-01 challenge for these cases, which verifies domain ownership via DNS records. Fourth, Traefik's dynamic configuration is a game-changer. Traefik's dynamic configuration (via Docker labels) means SSL certificates and routing rules can be added, updated, and removed without a reload, which means there is no downtime during domain configuration changes. Fifth, apex domains are trickier than subdomains. Apex domains cannot use CNAME records (in standard DNS), which means they need special handling (A records or ALIAS records). The system handles this automatically, but it is a common source of confusion for users. For more on Deployxa's engineering, see our articles on how we handle SSL at scale and the container networking model.

Conclusion: Custom Domains in One Click

Adding a custom domain should be one click, not a multi-step manual process. Deployxa's custom domain system automates DNS, SSL, and routing, which means you can add a custom domain in minutes, without manually obtaining SSL certificates or configuring reverse proxies. For more on Deployxa's engineering, see our articles on the build cache architecture and the health check system. Learn about how we handle container restarts and the audit log system in our companion articles. Explore our free developer tools to speed up your workflow. Try Deployxa Drop for an instant live preview with zero signup.