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: { mode: none }

Run edgible stack deploy -f app.yml.

The deploy will move into a pending_dns (or similarly-named) state. The control plane is now waiting for api.example.com to resolve to the gateway.

2. Get the gateway target

edgible stack status -f app.yml

The output includes the value you need to point DNS at — usually a CNAME target like gw-12345.edgible-edge.com (the exact form depends on your gateway placement).

3. Update your DNS

In your DNS provider, create a CNAME record:

Name	Type	Value
api	CNAME	gw-12345.edgible-edge.com

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

If you need an A record instead — e.g., because you’re putting the hostname at a zone apex that doesn’t allow CNAMEs — use the gateway’s IP instead. edgible stack status will give you both.

4. Wait for the certificate

Once DNS resolves, the platform requests a certificate from a public CA. Validation completes within a minute or two on the happy path. edgible stack status will move to ready.

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

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

Multiple hostnames on one access entry

You can publish the same workload at several hostnames at once:

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

The platform will request a certificate covering both names (a SAN cert) once DNS for both points at the gateway.

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. Most modern DNS providers (Cloudflare, Route53, DNSimple, others) support this. If yours doesn’t, use an A record pointing to the gateway IP — edgible stack status will give you the value.

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.