Set up a custom domain
Back to home
On this page
Once your project is ready for production, replace the automatically generated domain with your own custom domain. Note that adding a domain disables the automatically generated URL for your Production environment only.
You can also customize the URLs for your preview environments.
Before you begin 
You need:
- A project that’s ready to go live
- A domain with access to its settings with the registrar
- A registrar that allows
CNAMErecords or one of the alternatives on apex domains - Optional: The CLI installed locally
If you are planning to use several subdomains of the same domain on different projects, see how to manage multiple subdomains before you add your domain to Upsun.
1. Get the target for your project
You want to point your DNS record to the automatically generated URL. Your domain needs to point to that target for your site to go live.
Get the target by running the following CLI command:
upsun environment:info edge_hostname- Navigate to your production environment and click Settings.
- Select the Domains tab.
- In the Configure your domain section, copy the content of the CNAME record field.
2. Configure your DNS provider
Your DNS provider (usually your registrar) is where you manage your domain.
Most registrars offer similar functionalities regarding DNS configuration but use different terminology or configuration.
For example, some registrars require you to use an @ to create custom records on the apex domain, while others don’t.
Check your registrar’s documentation.
Note that depending on your registrar and the time to live (TTL) you set, it can take anywhere from 15 minutes to 72 hours for DNS changes to be taken into account.
To configure your domain name to point to your project:
- Consult your provider’s documentation to find out how to add or edit DNS records.
- Open your registrar’s domain management system.
- Set the TTL on your domain to the lowest possible value to minimize transition time.
- Add a
CNAMErecord pointing from your domain to the target. Not all registrars allow these kinds of records. If yours doesn’t, see the alternatives. - Optional: If you have multiple domains you want to be served by the same app, add a
CNAMErecord for each of them. That includes thewwwsubdomain if you are using it in your routes configuration. - Set the TTL value back to its previous value.
If your domain is example.com and you are using the www subdomain, you have records like the following:
example.comis aCNAME/ANAME/ALIASrecord pointing tomain-abcd123.abcdefgh1234567.eu.platformsh.site.www.example.comis aCNAMErecord pointing tomain-abcd123.abcdefgh1234567.eu.platformsh.site.
Both example.com and www.example.com point to the same target.
Redirects are handled by the router you configure.
To configure your CDN and your domain name to point to your project:
- Open your CDN’s management system.
- Point the CDN at your target.
- Open your registrar’s domain management system.
- Open your registrar’s domain management system and configure your DNS zone settings to point at your CDN.
The address or
CNAMErecord to use varies by CDN provider. Refer to the official documentation of your DNS provider and CDN provider. - Check that redirects and subdomains are set correctly for the TLS certificate ownership verification.
- Disable the router cache.
- Optional: For increased security and to prevent the CDN from being bypassed, you can force all traffic to go through the CDN.
- Optional: If you have multiple domains you want to be served by the same app, add a
CNAMErecord for each of them. That includes thewwwsubdomain if you are using it in your routes configuration.
Adding a custom domain sets your site as visible to search engines.
See how you can further configure your CDN.
3. Set your domain
Add a single domain to your project:
Run the following command:
upsun domain:add YOUR_DOMAIN- Select the project where you want to add a domain.
- Click Settings.
- Click Domains.
- In the Domain field, enter your domain.
- Click Add domain.