The Stack Harbor PaaS accepts both internationalized domain names (IDN) and generic top-level domains (gTLD) wherever a domain name can be used — environment names, environment aliases, custom domain bindings, swap targets. This page explains how each works and the small set of constraints to be aware of.
Internationalized domain names (IDN)
IDN is the standard that lets domain names contain non-ASCII characters — Cyrillic letters, Chinese hieroglyphs, Greek, Arabic, accented Latin characters used in French and other languages. Under the hood, IDN names are encoded into ASCII using Punycode, a transformation that lets the existing DNS infrastructure (which is ASCII-only) handle Unicode names.
You see the Unicode form (café.example) in the browser address bar and in the dashboard. The DNS layer sees the Punycode form (xn--caf-dma.example). Conversion is automatic in both directions.
IDN as an environment name
When you create a new environment in the topology wizard, the Environment name field accepts Unicode. Enter the name in any language — Cyrillic, Chinese, accented Latin — and click Create. The environment is created normally and appears in the dashboard under the Unicode name.
Two constraints:
- The name must be longer than 5 characters.
- The name cannot start with
xn--. That prefix is the Punycode signature for IDN-encoded ASCII, and the platform reserves it to avoid ambiguity.
Default environment URL with IDN
If you open the environment in the browser via the dashboard, the URL appears in Punycode form because the address bar speaks ASCII. The browser may or may not render the Unicode form back depending on its IDN homograph-attack policy.
To avoid the awkward Punycode URL, bind a custom domain (which can itself be an IDN) to the environment — see Custom domains.
IDN aliases
You can also set an environment alias or per-node alias in your native language. Aliases are display-only — they make the dashboard easier to navigate without changing the underlying environment name.
Generic top-level domains (gTLD)
gTLDs are top-level domains beyond the original .com, .org, .net, .gov, .edu, .mil set, maintained by IANA. Examples include .academy, .app, .best, .cloud, .dev, .io, .tech. They are called “generic” because they are not tied to a specific country (unlike .ca, .fr, .uk, etc.) and can be registered by anyone.
On the PaaS, gTLDs are treated identically to legacy TLDs. There is no separate flow for binding a .academy domain versus a .com domain.
Custom IDN or gTLD domain — how to attach
The binding flow is the same as for any other custom domain:
- Purchase the domain (IDN or gTLD) at a registrar that supports it.
- Create a DNS record at the registrar pointing to your environment (CNAME, ANAME, or A — depending on whether you have a public IP).
- If you do not have a public IP, bind the domain to the environment in the dashboard so the shared load balancer routes traffic correctly.
Custom domains covers the full procedure.
Domain swap and IDN/gTLD
The domain swap feature (used for blue/green and staging-to-production cutovers) works with both IDN and gTLD names. The platform handles the Punycode/Unicode conversion transparently when matching the domain on each side of the swap.