Projects
Custom Domains
This guide will walk you through the process of setting up a custom domain for your project's edge deployment environment. You can manage all domain settings related to a project in the Custom Domains section of the Settings tab of your project. Custom Domains are available on Builder plans and above.
Note
Custom domains cannot be added to development environments. You can tell if an
environment is development if the domain ends with zuplo.dev
.
Adding a new custom domain#
The following steps will guide you on how to add and configure a custom domain for your Zuplo project.
1. Navigate to your project's Custom Domain Settings#
Go to your project in the Zuplo portal and open to the Settings tab (1),
then select Custom Domain (2) and click on the Add New Custom Domain
button to open the New Custom Domain
configuration modal.
2. Add your domain#
Then, pick the environment you want to assign the domain to and enter your apex domain (e.g. example.com) or subdomain (e.g. api.example.com)
Once saved, you will be provided with a CNAME
configuration that will look
something like the one below that you'll use in the next step.
CNAME api.example.com cname.zuplo.app
3. Configure your DNS#
Once you have added your custom domain to your Zuplo project, you will need to configure the DNS records of your domain with your registrar.
Using the CNAME configuration provided at the end of the previous step, you will create that record on your DNS registrar. Cloudflare will then query your domain periodically until it can verify everything. If everything is configured correctly, it should take a few minutes for your production Zup to start responding to traffic on your custom domain. On the other hand, if a misconfiguration (typo) occurs and you need to make changes, Cloudflare could take up to 4 hours to retry the verification. Please be patient if this happens.
By default, you can also use the url on zuploapp.com
although, if you prefer
that to be removed contact support and we can disable it for you.
Caution
If you use Cloudflare as your DNS provider, you MUST enable Cloudflare Proxy on your custom domain.
4. Redeploy#
Some changes, like the domain set in your developer portal, only get picked up on the deployment. After you set a custom domain it is a good idea to redeploy your environment to ensure everything is applied correctly.
Cloudflare Customers#
Zuplo uses Cloudflare for routing custom domain traffic to our servers. If you use Cloudflare on your domain, there are a few limitations to be aware of. In general, these shouldn't be a problem as we handle all the complexities for you.
For host names managed by Zuplo, you cannot control some Cloudflare settings for
your Zuplo subdomain (i.e. api.example.com
). Examples include:
- Wildcard DNS
- Spectrum
- Argo
- Page Shield
See Cloudflare's documentation for more details.
Other Cloudflare features that are configured on your Cloudflare Account such as Firewall or WAF rules will function normally.
At this time, to use a wildcard domain or other complex custom domain for your environment you will need to contact support@zuplo.com.
CAA Records#
Info
In most cases this isn't required. You only need to modify CAA records if you already have them set on your DNS.
If you have a CAA DNS record set on your domain, you must add either Google Trust Services or Let's Encrypt as an authorized certificate authority.
You don't need to add both of these, just add one. The Google Trust Services (pki.goog) is the recommended Authority as it has slightly better compatibility with clients. Zuplo will use Google Trust Services by default unless only the Let's Encrypt record is set.
CAA 0 issue "pki.goog" CAA 0 issue "letsencrypt.org"
Managed SSL Certificates#
By default Zuplo will automatically manage SSL certificates for your custom domain. If you prefer to manage your own SSL certificates, please contact support@zuplo.com.
Certificates are issued by either Google Trust Services or Let's Encrypt. If you have a preference, please let us know, but we recommend (and default to) Google Trust Services as it has slightly better compatibility with clients.
Certificates are issued for 90 days and are automatically renewed aproximately 30 days before they expire. No action is required on your part.
Certificate Pinning
Certificate pinning is not recommended for Zuplo APIs as the certificates are issued for short periods of time and renewed automatically. If you or your end clients require certificate pinning, it is recommended you use a custom, long-lived SSL certificate. (Although this is not recommended for most use cases.)
For alternatives to certificate pinning, consider using HSTS headers or adding CAA records to your DNS. The CAA records required for Zuplo are shown below (depending on what authority your domain is configured to use)
# CAA records added by Let's Encrypt 0 issue "letsencrypt.org" 0 issuewild "letsencrypt.org" # CAA records added by Google Trust Services 0 issue "pki.goog; cansignhttpexchanges=yes" 0 issuewild "pki.goog; cansignhttpexchanges=yes"
TLS Versions#
Zuplo supports issuing certificates with TLS versions 1.0, 1.1, 1.2 and 1.3. By default certificates are issues with versions 1.2 and 1.3 enabled. If you require a specific version, please contact support@zuplo.com.
Legacy TLS Versions
Early Zuplo customers may have certificates issued with TLS 1.0 and greater enabled. If you wish to upgrade to a higher TLS version, please contact support@zuplo.com.
Validation Error#
If you receive a notification or email that your domain has a validation error the likely causes of the issue listed below. If you are unable to resolve the issue or have any questions, please contact support@zuplo.com.
No DNS Record or Invalid Record#
Your DNS is not configured correctly. Ensure that your domain is configured with
a CNAME
record pointing to cname.zuplo.app
.
CNAME api.example.com cname.zuplo.app
CAA Record Error#
Your DNS has been configured with CAA records that do not authorize Google Trust Services to issue certificates for your domain. To resolve add the following DNS records:
0 issue "pki.goog; cansignhttpexchanges=yes" 0 issuewild "pki.goog; cansignhttpexchanges=yes"