Guides

Custom domains

The manifest field exists and sets your app's hostname — but on the hosted platform the DNS target and certificate are not yet provisioned, so a custom domain needs operator setup.

Every app is served at https://<alias>-<org>.dibbla.com from its first deploy, with TLS, and that address is not going anywhere. This page is about serving the same app on a hostname you own instead.

Not self-service on the hosted platform yet

The manifest half of this works today. The two halves that make a hostname reachable — a DNS target you can point at, and a certificate for your name — are not currently provisioned on dibbla.com. Talk to us before you plan around a custom domain, rather than deploying and waiting for something to resolve.

On a self-hosted install this is a matter of your own ingress and certificate setup, and the manifest field below is the part you were going to need anyway.

What the manifest field does

domain: is a real dibbla.yaml field. Set it and the service’s ingress rule is created for that hostname verbatim instead of the generated one — so an app that wants a custom domain has a manifest even if it is a single service:

version: 1
services:
  web:
    build: .
    port: 3000
    public: true
    domain: app.example.com

$dibbla manifest validate .
$dibbla deploy . --alias my-app -m "feat: serve on app.example.com" --update

`manifest validate` does not check this field

It validates the manifest’s shape, and domain: is accepted as any string. A typo, a hostname you do not own, or a name nobody has pointed DNS at all validate and deploy cleanly. The failure shows up later, as a request that never arrives.

What is missing, concretely

Worth knowing precisely, because “custom domains are not supported” is too blunt and would send you looking for a workaround that does not exist:

No DNS target to point at. On the hosted platform, traffic arrives through a tunnel whose routing table matches *.dibbla.com and *.dibbla.app and returns 404 for everything else. A CNAME from your hostname to that target reaches the platform and is refused by it.
No certificate is issued for your hostname. Nothing in the deploy path requests one — there is no certificate-issuer annotation and no TLS block on the ingress it creates. A browser reaching the app on your name would be presented the platform’s own wildcard certificate, which does not match it.

Both are operator-side, and neither is something you can work around from a dibbla.yaml.

If you are self-hosting

The manifest field is genuinely useful here, because you control the two missing pieces:

Point DNS at your own ingress, however you normally do.
Terminate TLS for that hostname yourself — a certificate issuer watching the ingress, or a certificate you manage.

The domain: field then does exactly what it says: your service answers on that hostname.

The dibbla.com address keeps working either way

A custom domain is added, not swapped. The generated address continues to serve the same app, which is what you want while DNS propagates and for anything that already links to it.

← Previous

Connecting a database

SSO & access control