Deployment

Connect a domain

Copy page

Serve a service on a domain you own, and split one domain across several services by path.

Every service that serves HTTP gets a public address the moment it is created, and you can put your own domain in front of it. Both kinds of domain are served over HTTPS — there is nothing to configure and nothing to renew.

Where each action lives:

Pick a domain

Custom domains are added per environment, so staging and production each have their own.

Plain HTTP is answered with a permanent redirect to the same URL over HTTPS, with host, path and query preserved.

Connect your own domain

1. Pick a base domain — one of the domains your organization has already registered on the platform. Lessly lists the ones available to you.
2. Call deployment_domain_add with either a subdomain of that base (api, app) or the root domain itself, and the service that traffic goes to by default. It returns the exact set of DNS records to publish — see the records you publish.
3. Publish every record it lists at your DNS provider. If your DNS is managed through the platform, the records are published for you and there is nothing to copy.
4. Wait. Lessly re-checks your DNS every minute and moves the domain along on its own. To force a check rather than wait for the next one, call deployment_domain_verify.
5. Read the status until it reaches Active with deployment_domain_get.

Statuses

Removing a custom domain with deployment_domain_remove tears down its routing and its certificate and stops serving it.

The records you publish

Alongside the routing records, the list always carries a TXT record at _lessly-verify.<your-host> holding a token. That record is what proves the host is yours, and verification does not pass without it.

The routing records themselves depend on what you connected:

Those addresses are read from a live resolution of the edge at the moment you add the domain. That is exactly why adding a root domain requires Lessly’s routing addresses to be resolvable at that moment: in the rare case they are not, the add is refused outright with an explanation rather than registering a domain that would silently never route — retry in a moment.

Move a hostname that is behind a CDN or a proxied record

Verification compares the addresses your hostname resolves to against the edge’s own addresses. A proxied record — Cloudflare’s “orange cloud” mode and its equivalents — resolves to the CDN instead, so the check cannot pass.

Turn proxying off for that record, so the host resolves cleanly to the target Lessly gave you, and leave it off until the domain reaches Active. The next check picks the change up within a minute.

How long the certificate takes

Publishing every record Lessly lists is what makes this fast. Among them is a CNAME at _acme-challenge.<your-host>, and the certificate is issued against it.

That record is also why nothing appears to happen immediately after verification. The certificate is not requested at all until _acme-challenge is visible in public DNS — asking earlier makes the certificate authority cache the miss and stalls issuance for far longer than the wait costs. Lessly re-checks every minute; if the record is never published, the certificate is never requested.

The www redirect

For a root domain you can also have www.<your-domain> redirect to it permanently. The option is offered when you add the domain and is on by default; turn it on or off afterwards with deployment_domain_redirect_www.

It is only available on a root domain — a subdomain has no root to redirect to. Turning it off leaves the rest of the domain untouched, so switching it back on is immediate.

The www host gets a certificate of its own, and always the slower kind. Expect the redirect to start working tens of minutes after the root domain is already serving. The root domain’s own certificate is not affected either way.

Split a domain across services

A custom domain can serve more than one service by path. Each route maps a path prefix to a service in the same environment — add one with deployment_domain_routes_add:

Rules to know:

• Every domain has exactly one default route, on /, created with the domain. You can point it at a different service, but you cannot delete it.
• A path is unique within a domain — two routes cannot claim /api.
• Paths are normalized: a missing leading slash is added, a trailing slash is dropped.
• The service on a route must belong to the same environment as the domain.
• The most specific match wins: the longest matching prefix takes the request, and the default route catches everything else. If two routes are equally specific, the one with the higher priority wins.
• Route changes take effect on their own — no redeploy needed.
• The generated domain does not take routes; it has one fixed route to its service.

When the generated domain is not serving yet

The hostname exists immediately, but it takes a few minutes before it actually serves.

Lessly checks this by actually requesting the hostname from the outside, so Active means a response from your service reached the edge — not that a configuration record was written. Only an Active domain is shown as a clickable link.

A failed route usually means the service itself is not answering yet: it has not finished deploying, it is not listening on the port it declared, or its health check never passed. The status carries a hint pointing at which of those it is. Redeploying the service re-applies the routing, which is the usual fix if the domain was working before.

A service that sleeps when idle is not one of those cases: it still answers domain and route checks, and a request simply waits while it starts.

Next steps

• Set up a service: check the port a domain routes to, and the health check that gates it.
• Deploy, redeploy and roll back: redeploy to re-apply routing after a failed route.
• Work with environments: a fork gets its own generated hostnames and none of your custom domains.
• Read how deployment works: where a domain sits relative to an environment and a service.