Domains
Give a service a generated domain or your own.
A service is reachable from the internet once it has a domain. Domains are managed under Public Networking in the service settings.
Generated domains
Press Add domain, then Generate. You get a domain like web-k3x9pa.your-domain.com that works right away, with HTTPS.
Generated domains need a wildcard DNS record on your instance. If Generate is not offered, the person who runs the instance has to set the Wildcard Domain. See DNS Setup.
Your own domain
Add the domain
Press Add domain and type the domain, like app.example.com. Pick the Port your app listens on. Ports that Unbind detected are marked Detected.
Create the DNS record
Unbind shows the record to create at your DNS provider:
| Type | Name | Content |
|---|---|---|
| A | app.example.com | your server's IP address |
The status changes from Waiting for DNS record to DNS record detected once it resolves. You can save before that and add the record later.
Deploy
Press Deploy on the changes bar. The certificate is requested from Let's Encrypt on the first request and renewed for you. It can take a minute, and browsers may show a certificate warning until it is ready.
A service can have several domains, and each one can point at a different port.
To remove a domain, press the trash icon on it and deploy. Removing the last one makes the service private.
Cloudflare
If the record is proxied through Cloudflare (orange cloud), Unbind shows Cloudflare detected. That works for a normal domain. Set Cloudflare's SSL mode to Full (strict) so traffic between Cloudflare and your server stays encrypted.
Wildcard domains
A wildcard domain like *.example.com sends every subdomain of example.com to one service. Use it when your app gives each user, site or document its own subdomain. It does not cover example.com itself, so add that as a second domain if you need it.
Add it like any other domain, with a * record at your DNS provider:
| Type | Name | Content |
|---|---|---|
| A | *.example.com | your server's IP address |
A wildcard domain gets a self-signed certificate, because Let's Encrypt can't issue wildcard certificates the way Unbind requests them. Browsers don't trust it, so put a proxy in front that serves visitors its own certificate. With Cloudflare, proxy the record (orange cloud) and set the SSL mode to Full. Full (strict) rejects a self-signed certificate.
A few rules apply:
- Only one
*is allowed, as the first label.*.comis refused. - A wildcard can't cover a domain that another team uses, and another team can't add a domain under your wildcard. Inside your team, a service can take
app.example.comwhile another holds*.example.com. The exact domain wins. - A wildcard can't cover the domain of your Unbind instance or its generated domains.
UNBIND_URL_PUBLICand the other public variables never point at a wildcard. They use the service's other domains.
Split a domain by path
A domain can send each path to a different service, like example.com to the website and example.com/api to the API. Add the domain to every service that takes a part of it, and type a Path under Advanced Settings on each one except the service that answers the rest. The longest matching path wins.
- A path covers itself and everything under it:
/apitakes/apiand/api/users, not/apis. - The service gets the full path: the one under
/apisees/api/users, not/users. - One service can take several paths of a domain, like
/apiand/socket.io. - The paths of a domain share its DNS record.
- Only services of one team can share a domain. A gRPC domain can't be split.
- A redirect, proxy, basic auth or response header applies to the path it is set on, so
example.com/blog/oldcan redirect tohttps://example.com/blog/newwhile the rest of the domain reaches the service. UNBIND_URL_PUBLICincludes the path, likehttps://example.com/api.
Redirect a domain
A domain can send visitors to another URL instead of the service. Press the pencil on the domain, open Advanced Settings, type the URL in Redirect, like https://example.com, pick the Redirect Status and deploy. The URL cannot carry a query string, and its path only takes letters, digits and / . _ ~ ! * + , : @ = -.
- A URL with no path keeps the path and query of the request:
www.example.com/pricinggoes toexample.com/pricing. - A URL with a path drops it: every page of
plugins.example.comgoes toexample.com/plugins.
The status is 308 by default, which keeps the request method. 301 is the classic permanent redirect, 302 and 307 are temporary ones that browsers don't cache.
A redirect domain still needs a DNS record and gets its own certificate, so visitors on HTTPS are redirected without a warning. It is not one of the service's addresses: UNBIND_URL_PUBLIC and the links in the app skip it.
This is how to send www.example.com to example.com: add www.example.com to the service that serves example.com, with a redirect to https://example.com.
Proxy a domain
A domain can serve another URL without a redirect, so visitors stay on your domain. Press the pencil on the domain, open Advanced Settings, type the URL in Proxy, like https://raw.githubusercontent.com/org/repo/main/install.sh, and deploy. Tools that don't follow redirects, like curl without -L, get the content itself.
- A URL with no path keeps the path of the request:
docs.example.com/startservesexample.net/start. - A URL with a path serves that path for every request, like the install script above.
- The query of the request is kept.
- The upstream sees its own hostname in the
Hostheader. HTTPS URLs are checked against the public certificate authorities, so a self-signed upstream fails. - The URL needs a public hostname. IP addresses and names inside the cluster are refused.
A proxied domain still needs a DNS record and gets its own certificate. Basic auth and response headers work on it. Like a redirect, it is not one of the service's addresses.
Proxies need Envoy Gateway, the default. Installs on ingress-nginx or Traefik don't show the setting.
Password protect a domain
Basic Auth asks visitors for a username and password before the service answers. Press the pencil on the domain, open Advanced Settings, type a username and a password and deploy. Browsers show a login prompt, and tools send the pair with curl -u.
Unbind keeps a hash of the password, never the password itself, and never shows it again. To change it, type a new one. Leaving the password empty on a later edit keeps the current one. A domain with a redirect has no basic auth, since the service never answers on it.
Response headers
Response Headers, under Advanced Settings of a domain, adds headers to every response of it, typed as Name: value. A header the service already sends is replaced.
Common ones:
| Header | What it does |
|---|---|
Strict-Transport-Security: max-age=31536000; includeSubDomains | Browsers that saw it only ever open the domain over HTTPS |
Cache-Control: public, max-age=600 | Caches and Cloudflare keep responses for ten minutes |
X-Frame-Options: DENY | No other site can show the page in a frame |
Names use letters, digits and dashes. Values can't have quotes, backslashes or dollar signs, and the headers that frame a response, like Content-Length, can't be set.
The HSTS header is worth adding when you move a site from a host that sent it: Unbind doesn't send it on its own, and browsers that cached it keep it for up to a year.
Visitor IP addresses
Behind a proxy like Cloudflare, every request reaches your server from the proxy, so a service sees the proxy's address as the visitor and X-Forwarded-For ends with your own server's address. The proxy's own header, like CF-Connecting-IP, always carries the visitor's address.
Client IP Header under Networking in the service settings names that header. Unbind then takes the visitor's address from it for its own logs and policies, and passes X-Forwarded-For on as the proxy sent it instead of appending your server's address. A request without the header, from a visitor who connects directly, keeps the address of the connection.
Leave it empty for the automatic choice: CF-Connecting-IP while one of the service's domains is proxied through Cloudflare, nothing otherwise. The choice is made on every deploy, so a domain moving on or off Cloudflare is picked up on the next one. Type a header to use another proxy's, like X-Real-IP.
Only trust a header when every domain of the service goes through that proxy. Anyone who reaches your server directly can put any address in it.
The setting shows on installs that route through Envoy Gateway, the default. On ingress-nginx, X-Forwarded-For from the proxy is trusted as installed, and services read the proxy's own header themselves.
Max request size
A request with a body larger than 100 MB, like a big file upload, is refused with 413 Request Entity Too Large. To change it, type a size from 1 MB to 10240 MB in Max Request Size at the bottom of Networking in the service settings and deploy. An empty field means 100 MB.
The limit only exists on installs that route traffic with ingress-nginx or Traefik. Installs on Envoy Gateway, the default, accept any size and don't show the setting.
Redirects, basic auth and response headers work on every install. On ingress-nginx the redirect and the headers go through a configuration snippet, which the controller only accepts with annotations-risk-level set to Critical, the value Unbind installs it with.
Cloudflare applies its own limit to proxied domains: 100 MB on the Free and Pro plans.
Sticky sessions
A service with more than one replica spreads requests across them. An app that keeps sessions or websocket state in a replica's memory needs each visitor to keep reaching the same replica. Turn on Sticky Sessions under Load Balancing in Networking in the service settings and deploy. The setting only shows for a service with more than one replica. Unbind then pins each visitor to one replica with a cookie.
It is off by default. Leave it off for anything a cache should serve: Cloudflare and other caches don't store responses that set a cookie, so every request reaches your service.
Private networking
Your services reach each other without going through the internet. Every service has a private address, shown under Private Networking. You rarely need to type it: reference it from a variable instead.
API_URL=${API.UNBIND_URL_PRIVATE}A service with no domain is private. Workers, queues and internal APIs never need one. With network isolation on, a private address only answers services in the same team, unless a system admin adds an exception.
Databases and other TCP services
Domains are for HTTP. Databases are exposed with Network Access instead, which gives them a public address and port. See Databases.