Use a custom domain

Generated hostnames are convenient but they’re not your brand. This guide replaces your-app-abc123.edgible.app with a hostname you own, like api.example.com.

What you need

• A domain you control and can edit DNS for. We’ll use example.com in the examples.
• An application already deploying successfully under a generated hostname (the Quickstart endpoint is fine).

The two-step dance

Custom domains require a chicken-and-egg dance: you set DNS so traffic arrives, and the platform issues a certificate so the TLS handshake works. The order matters.

1. Update the application YAML

Replace the hostname: block:

app.yml

access:
  - name: public
    type: https
    target: { workload: web, port: http }
    hostname: { generated: true }
    hostname: { custom: api.example.com }
    tls: { managedBy: edgible }
    policies:
      auth: { modes: [none] }

Run edgible stack deploy -f app.yml.

The custom hostname does not block the deploy — the generated .edgible.com name keeps serving while you set DNS. When the deploy finishes, it prints the exact DNS record your custom hostname needs, right under the hostname:

Application URLs & routes:
──────────────────────────────────────────────────
  my-app
    public (primary)
      https://api.example.com (custom)
      DNS record needed for api.example.com:
        api.example.com  CNAME  api.myorg.edgible.com
      https://api.myorg.edgible.com (generated)
      /* → web:http  [none]

The CNAME target is the access’s generated .edgible.com hostname. Edgible keeps that name’s A record pointed at the gateway for you, so pointing your custom name at it chases to the gateway automatically — and survives gateway IP changes.

2. Re-print the target any time

The same DNS record is available from stack status and application get:

edgible stack status -f app.yml
# ...
#    Hostnames: api.example.com, api.myorg.edgible.com
#    DNS record needed for api.example.com:
#      api.example.com  CNAME  api.myorg.edgible.com

3. Update your DNS

In your DNS provider, create a CNAME record:

Name	Type	Value
api	CNAME	api.myorg.edgible.com

Save and wait for propagation. dig api.example.com CNAME +short should eventually return the target.

If you’re putting the hostname at a zone apex that can’t hold a CNAME, use an ALIAS/ANAME to the same target instead — see Apex domains below.

4. Wait for the certificate

Once DNS resolves, the platform validates the domain and issues a certificate from a public CA — validation completes within a minute or two on the happy path. If DNS wasn’t ready in time and the certificate went to error, the platform retries automatically once the challenge starts resolving (within ~6h). To force it immediately after fixing DNS, run:

edgible certs retry api.example.com --app <application-id>

Check progress any time with edgible certs --app <application-id>. Once issued:

curl -v https://api.example.com/

Should now return your workload’s response over a valid HTTPS certificate.

The generated hostname stays live

A custom domain is additive: adding hostname.custom does not remove the access’s generated <app>.<org>.edgible.com name — both serve at once. That makes cutover zero-downtime (the generated name answers while your DNS propagates) and leaves the .edgible.com URL as a debug escape hatch. An access can therefore hold up to two certificates — one for the generated name, one for the custom name.

Publishing at several custom hostnames

hostname.custom is a single FQDN per access. To publish the same workload at several custom hostnames, declare multiple access entries — one custom domain each — targeting the same workload:

access:
  - name: public
    type: https
    primary: true
    target: { workload: web, port: http }
    hostname: { custom: api.example.com }
    tls: { managedBy: edgible }
    policies: { auth: { modes: [none] } }
  - name: alt
    type: https
    target: { workload: web, port: http }
    hostname: { custom: api.example.net }
    tls: { managedBy: edgible }
    policies: { auth: { modes: [none] } }

Each access gets its own certificate once DNS for its custom name points at its generated target. (Removing a custom domain later is a hostname removal — the apply is refused unless you pass --allow-hostname-removal.)

Apex domains

Apex domains (example.com itself, with no subdomain) work, but require an ALIAS/ANAME record at most providers because the apex can’t be a CNAME. Edgible detects the apex case and prints the record accordingly:

DNS record needed for example.com (apex — use ALIAS/ANAME, or an A record to the gateway IP):
  example.com  ALIAS  api.myorg.edgible.com

Point the ALIAS/ANAME at the generated .edgible.com target (the same one shown for sub-domains). The generated name is derived from the app and org names (<app>.<org>.edgible.com), not from your custom domain — so an apex custom like example.com still targets your app’s generated api.myorg.edgible.com. Most modern DNS providers (Cloudflare, Route53, DNSimple, others) support this. If yours doesn’t, resolve the generated target (dig api.myorg.edgible.com +short) and use an A record to that gateway IP — note you’ll then have to update it if the gateway IP ever changes, which the ALIAS avoids.

Removing a custom domain

Switch the YAML back to a generated hostname (or delete the access entry) and re-deploy. The platform will release the cert and the gateway will stop accepting traffic for the old hostname. You can then remove the DNS record.