The short answer
On Pro, custom domain HTTPS is three steps. Add the hostname in Domains, create the exact DNS record Cloud shows, and wait for verification and certificate readiness. The default Unbroker hostname stays, so health checks can still use it.
A custom domain is not another deploy. DNS, hostname verification, and the TLS certificate are separate states. Confirm the app on the Unbroker hostname first. Redeploying the same commit does not fix DNS.
The product flow is Domains and TLS. The walkthrough is Connect a custom domain and HTTPS. How that app got live is Deploy on git push.
Check the app before you touch DNS
Open the Unbroker-provided URL and request a route you expect. If that request fails, read the deployment and the runtime logs. The failure is in the app. Editing DNS does not explain it. The stage-by-stage read is Debug a failed deployment.
Keep the default hostname after you add your own. The domains page says it remains useful for health checks and for diagnosing custom-domain configuration. The guide says to verify that URL before you change production routing.
Custom domains need Unbroker Pro, a running HTTP service, and permission to change DNS for the domain. The plans table lists custom domains and managed TLS as not available on Free and available on Pro. Pro is $25 a month with $25 of usage credit. The credit resets each cycle and does not roll over. If eligible usage stays under the credit, the monthly charge is still the plan price. Current figures are on pricing.
Add the hostname in Cloud
Open the service’s Domains view and add the hostname you want to publish, such as api.example.com or www.example.com. That is how you add a custom domain to an app that is already running. The record on that screen is what points the domain at the service.
Cloud shows the DNS record type, name, and target. Copy those values into your DNS provider. Use the values on that screen. Do not invent a target from another service URL or from a different project.
An apex domain and a subdomain can need different records. Follow the record type Cloud shows, and the record type your DNS provider supports for that hostname. The guide says this for an apex domain: follow the record type your provider supports and the destination instructions shown in Cloud.
Adding the hostname configures the service. It does not edit the registrar, and it does not create the DNS record for you. You create that record at the provider that serves the authoritative zone.
Add the hostname with the CLI
The documented commands are:
ubctl apps domains add <serviceId> api.example.com
ubctl apps domains ls <serviceId>
ubctl apps domains status <serviceId>
Replace the service id and the example hostname. add attaches the hostname to the service. ls lists the domains on that service. status is how you read the domain state from the terminal. The same limit holds: these commands do not write records at the registrar. The source is the custom domain guide.
Three states: DNS, verification, and the certificate
Wait for Cloud to report domain verification and certificate readiness. Those are not the same moment.
You create the DNS record. Updates can show up on different resolvers at different times. Check for a conflicting record on the same hostname, and check that you edited the authoritative zone. Editing a zone that is not authoritative does not verify the hostname.
After verification, certificate readiness is tracked from the same Domains view. That readiness is the managed TLS certificate for the hostname. People also call it the custom domain SSL certificate. When it is ready, request the HTTPS URL and test an application route.
If the default URL works and the custom domain is not working after deploy, stay on DNS, hostname verification, and the certificate. Redeploying unchanged code does not repair a DNS error. The guide says to avoid repeated redeploys for that case.
Update app-level URLs
The hostname people type is an application setting as well as a DNS record. Add the new origin to OAuth callback allowlists, CORS configuration, and trusted-host settings. If a frontend baked the API origin into the bundle, rebuild it. Update canonical URLs, the sitemap origin, and absolute links so they use the public domain you intend. An Astro site sets that origin in site before the build. Static output or a server adapter is Astro hosting. What to update on the API and the frontend when those origins change is deploy a frontend and an API separately.
A Node service starts from Deploy Node.js. A Next.js app starts from Deploy Next.js. If the app was built in Lovable, Bolt, or Cursor, the checks that a public page does not cover are in Lovable app to production. The public hostname is a separate step from that list.
Migrating traffic
If this hostname already points somewhere else, lower the TTL before the cutover and account for the cache lifetime of the current record. The guide says to prepare the destination and account for that cache lifetime before you switch production traffic. Keep the default Unbroker hostname during the move.
A DNS change does not migrate a database, and it does not revoke credentials on the previous host. If old traffic can still reach that host, both sides must not write to divergent data stores.
Leaving Railway is two pages. The comparison is Unbroker as a Railway alternative. The move is Migrate from Railway. Leaving Heroku is Migrate from Heroku. This post does not repeat those runbooks.
When the custom domain fails but the default URL works
The app is up. The hostname is not. Work the list in order:
- The record is in the authoritative DNS zone for that domain.
- No conflicting record is set on the same hostname.
- The type, name, and target match what Cloud shows. They were not copied from another service.
- The Domains view reports verification.
- The same view reports certificate readiness.
- An application route on the HTTPS URL returns what you expect.
If the default URL is also failing, go back to the deployment logs. That is a failed request against the app, not a custom-domain state.
Checklist
- Request the default Unbroker URL. If it fails, debug the deployment before you touch DNS.
- On Pro, add the hostname in the service’s Domains view.
- Create the DNS record Cloud shows. Match the type, name, and target.
- Leave the default hostname in place.
- Wait for verification, then for certificate readiness.
- Update callbacks, CORS, trusted hosts, embedded API origins, canonical URLs, and the sitemap.
- Request the HTTPS URL. If only the custom domain fails, recheck the zone, conflicting records, verification, and the certificate. Do not redeploy the same commit to fix DNS.
FAQ
How do I add a custom domain with HTTPS to my PaaS app?
On Pro, add the hostname in the service's Domains view, create the DNS record Cloud shows, and wait for verification and certificate readiness. The default Unbroker hostname stays for health checks. That flow is Domains and TLS.
Why does my custom domain fail while the platform URL works?
The app is answering on the Unbroker hostname, so the deployment is already live. Check the authoritative DNS zone, conflicting records on that hostname, verification, and certificate readiness. Redeploying the same commit does not fix DNS.
Do I need Pro for a custom domain?
Yes. The plans table lists custom domains and managed TLS as not available on Free and available on Pro. The guide also starts from a running HTTP service and permission to change DNS. Pro is $25 a month with $25 of usage credit. See pricing and Plans.
Should I delete the default Unbroker hostname?
No. Keep it. It remains useful for health checks and for telling an application failure from a domain problem. The domains page says not to remove it.
Does adding a domain change DNS at my registrar automatically?
No. Adding the hostname configures the service. You create the DNS record at the provider that serves the authoritative zone. Unbroker does not edit the registrar for you.
What is the difference between an apex domain and a subdomain?
Use the record type, name, and target Cloud shows for that hostname. For an apex domain, also follow the record type your DNS provider supports. Do not copy a target from another service URL.
Does a DNS change migrate my database?
No. A DNS change points the hostname at the service. It does not move database rows, files, or credentials. If the previous host can still receive traffic, keep both sides from writing to divergent data stores.