Publishing, hostnames and custom domains

Publishing makes a portal servable, and its hostname is the address visitors use to reach it. Every published portal gets a platform address automatically. You can also put it on a hostname you own, such as shop.example.com. This page explains how to publish and unpublish a site, how the platform address is formed, and how to add, verify and remove a custom domain on the Domains screen. You build the portal first, as described in Build and publish a portal. Once it serves, Portal security and Troubleshooting portals cover keeping it right.

Overview

A portal is served only when all of the following are true:

• the Portals module is enabled for your organization;
• the site is Active;
• the site is Published;
• the visitor is allowed in: either Anonymous visitors is on, or the visitor has signed in.

When any of these fails, the visitor gets a "not found" page. Publishing and unpublishing control the site as a whole. Each page has its own Publish draft and Unpublish actions on the Pages tab.

There are two kinds of hostname:

Both hostnames serve the same portal, with the same pages, data views and audience rules.

When to use it

• You have finished building a portal and want visitors to reach it.
• You need to take a portal offline for a while without losing its configuration.
• You want visitors to see your own brand in the address bar instead of the platform address.
• You are retiring a hostname, or moving it to a different portal.

How xMatix handles it

• Publish marks the site as published and adds its platform address to your organization's domain list as a verified hostname. Platform addresses need no DNS proof, because the platform owns that zone. In the Domains list, these rows show the type Platform.
• Unpublish clears the published mark and removes the platform address from the domain list. Visitors get "not found" straight away. Pages, data views, settings and custom domains are kept, so publishing again brings everything back.
• Active works on its own, separately from publishing. An inactive site is never served, even when it is published. Turning Active off doesn't change the platform address or any custom domain.
• A custom domain is first saved as unverified, and an unverified hostname serves no traffic. xMatix then attaches the hostname to the platform's edge and gives you two DNS records to create. When you click Refresh verification and the edge confirms both records, the domain becomes Verified and starts serving. Verification also proves that you control the name. Nobody can verify it for you, and the add request can't mark it verified.
• A domain belongs to one organization. If another organization has already registered a hostname, xMatix refuses it.
• A Portal custom domain is tied to the portal's slug, and the domain row keeps the slug it was created with.
• Changes reach visitors after a short delay. The portal servers cache the hostname lookup for up to five minutes, or 30 seconds after a hostname was not found. A change made on the Domains screen or by publishing can take that long to show up.

Prerequisites

• Manage portals on your security profile, to publish and unpublish a portal. The Domains screen is a platform setup screen and does not need this capability.
• The Portals module enabled for your organization (Setup → Feature Hub → Portals → Settings, Enable Portals). With it off, publishing is refused and every portal answers "not found".
• A portal that is ready to serve: at least one page published and the data views it needs active. See Build and publish a portal and Portal pages and data views.
• For a custom domain: access to the DNS zone of the hostname you want to use, and a hostname that is not under the platform's own portal domain.

Procedure

Step 1 — Check the site before you publish

Open Setup → Feature Hub → Portals → Portals and open your portal. On the General tab, check:

• Label and Slug. The slug decides the platform address and the portal a custom domain points to, so settle it before you publish.
• Active is on.
• Anonymous visitors matches your audience. With it off, only signed-in members can see the site, and everyone else gets "not found".

The page header shows State (Draft or Published), Active, Anonymous (Allowed or Sign-in only), the number of pages and data views, and Version.

Step 2 — Publish the site

Click Publish in the page header. The confirmation says "The portal becomes servable; only published pages and data views are visible to visitors." Click Publish to confirm.

You see "Portal published". State changes to Published, the header button becomes Unpublish, and the Draft tag next to Address disappears. The Address line in the header shows the platform address, and you can open or copy it from there. While the site is a draft, the address has the tooltip "Not published yet — this address returns 404."

The platform address also appears on Setup → Feature Hub → Platform → Domains with the type Platform and the status Verified.

Step 3 — Unpublish or deactivate when you need to

• To take the whole site offline, click Unpublish in the page header and confirm ("The portal stops being served to all visitors immediately."). You see "Portal unpublished", and State goes back to Draft.
• To take one page offline, go to the Pages tab and click Unpublish on that page's row.
• To stop serving without unpublishing, turn off Active on the General tab and save.

None of these delete anything. Click Publish again to restore the site exactly as it was configured.

Step 4 — Add a custom domain

Open Setup → Feature Hub → Platform → Domains and click Add domain in the page header. The Add custom domain dialog opens.

12345 Expand

1. 1

   The banner states the contract: create the returned CNAME and TXT records in your DNS zone, then use Refresh on the row to re-check verification.

2. 2

   Domain type Portal serves a portal site on this hostname; Web would make it an entry host for the application itself.

3. 3

   Domain name is the visitor-facing hostname; a subdomain such as shop.example.com is the dependable choice because apex names cannot be CNAMEs.

4. 4

   Portal site binds the hostname to one portal; the portal's own published and active state still decides whether anything is served.

5. 5

   Add records the mapping and exposes the DNS proof; it does not publish the portal or change DNS for you.

1. Under Domain type, choose Portal (serves a portal site). The default is Web (entry host for the app).
2. In Domain name, enter the full hostname, for example shop.example.com. Use a subdomain where you can. See the apex-domain problem under Common problems.
3. In Portal site, pick the portal. Each portal is listed as its label with its slug in brackets.
4. Click Add.

You see "Domain added — create the DNS records shown in the row, then Refresh." A new row appears with the type Portal: <slug> and the status Pending DNS. Its DNS records column shows the records to create.

If the hostname could not be attached to the edge yet, you see Domain recorded, edge attach pending instead. The domain is saved anyway. Click Refresh verification on the row to try the attach again.

Step 5 — Create the DNS records

At your DNS provider, create both records shown in the row's DNS records column. Each line has a copy button.

• CNAME: your hostname, pointing at the target shown.
• TXT: the record name shown (it begins with _dnsauth.), set to the value shown.

Create both records exactly as shown. The CNAME sends traffic to the platform, and the TXT record proves that you control the name.

Step 6 — Verify the domain

When the records have propagated, click Refresh verification in the row's actions. xMatix checks the edge again:

• If both records are confirmed, you see "<hostname> is verified and serving.", the status becomes Verified, and the DNS records column clears. The portal now serves on your hostname. The platform address keeps working too.
• If they are not confirmed yet, the status shows the edge's current state. It stays amber while verification is still pending and turns red when verification failed, for example because it was rejected or timed out.

The status changes only when you click Refresh verification, so click it again after any DNS change.

Step 7 — Remove a domain you no longer use

Click Remove in the row's actions. The confirmation says "The hostname is detached from the platform edge and stops serving immediately. Remember to also remove the CNAME from your DNS zone." Confirm with Remove. You see "Domain removed".

Then delete the CNAME and TXT records from your DNS zone. If they stay, the name points at something that no longer serves it.

Fields

Add custom domain dialog

Domains list

Business rules

• Visitors are served only when the site is Active and Published, the Portals module is enabled, and the visitor passes the Anonymous visitors rule. Otherwise the answer is "not found".
• Publishing adds the platform address, and unpublishing removes it. If that step fails, the publish still succeeds, but the platform address doesn't resolve. Unpublish and publish again to retry it.
• The platform address is built from the slug at the moment you publish. If you change the slug of a published portal, the new address is not registered until you publish again.
• A custom domain serves traffic only once it is Verified. You can't mark a domain verified yourself. Only Refresh verification, run after the DNS records are confirmed, verifies it.
• A Portal custom domain keeps the slug it was added with. If you change the portal's slug later, the domain keeps pointing at the old slug and visitors get "not found". To fix it, add the same hostname again with the right portal.
• Adding a hostname that is already on your list replaces its row and sets it back to unverified. Click Refresh verification again afterwards. If your DNS records still match the row, it verifies again.
• A hostname registered by another organization is refused with "Domain '<hostname>' is already registered to another tenant."
• Removing a custom domain detaches it from the edge first. If that detach fails, the domain is kept and you see "Edge detach failed; domain not removed. Retry."
• Deleting a portal doesn't remove its custom domains. Remove them on Domains.

Example

A distributor runs a dealer portal with the slug dealers, and wants dealers to reach it at dealers.example.com.

1. The administrator opens the portal, checks that Active is on and Anonymous visitors is off, and clicks Publish. The header now reads State: Published, and the Address line shows the platform address, which starts with dealers- followed by the organization's slug.
2. On Setup → Feature Hub → Platform → Domains, they click Add domain, choose Portal (serves a portal site), enter dealers.example.com, pick the dealer portal and click Add. The row shows Portal: dealers, Pending DNS and two records.
3. They create the CNAME and the _dnsauth.dealers.example.com TXT record at their DNS provider. An hour later they click Refresh verification and see "dealers.example.com is verified and serving."
4. A dealer opens dealers.example.com, signs in and sees the same pages as on the platform address.

Training

Practice exercise

In a sandbox, publish a test portal that has at least one published page. Copy its address from the page header and open it in a private browser window. Then click Unpublish and reload the address.

Expected result: while the portal is published, the page loads, either straight away or after sign-in, depending on Anonymous visitors. After Unpublish, the same address answers "not found" within a few minutes. State shows Draft, and the portal's Platform row is gone from Setup → Feature Hub → Platform → Domains. Publish it again and the address comes back.

Quick reference

• Served = module enabled + Active + Published + the visitor passes the Anonymous visitors rule.
• Publish adds the platform address, and Unpublish removes it.
• Active off stops serving without unpublishing anything.
• Custom domains: Setup → Feature Hub → Platform → Domains → Add domain → type Portal.
• Create both the CNAME and the TXT record, then click Refresh verification.
• Status changes only when you click Refresh verification.
• Changed a portal's slug? Publish again, and add its custom domains again.
• Remove, then delete the DNS records at your provider.

Permissions

Without Manage portals, the Portals entry is hidden and the portal screens refuse access. See Security profiles.

Configuration

Common problems

"Unable to change publish state" with "The Portals module is disabled for this organization."

The Portals module is off. Turn on Enable Portals on Setup → Feature Hub → Portals → Settings, then publish again.

The address in the header returns "not found"

Check, in this order: State is Published, Active is Yes, and the module is enabled. If Anonymous reads Sign-in only, a visitor who isn't signed in also gets "not found". If you changed the slug after publishing, click Unpublish and then Publish to register the new address. Allow a few minutes after any change. More checks are in Troubleshooting portals.

"Domain recorded, edge attach pending"

The domain was saved, but it could not be attached to the platform edge yet. Click Refresh verification on the row, which retries the attach. If the message says the edge integration is not configured in this environment, custom domains can't be attached here. Contact support.

Verification never completes

Usually one of the two DNS records is missing, sits in the wrong zone, has a typo, or hasn't propagated yet. Check both records with an external DNS lookup tool, compare them character by character with the row, and click Refresh verification again. If the status is red, verification failed. Correct the records and refresh.

"Domain '…' is already registered to another tenant."

Another organization already holds this hostname, so you can't add it. Use a different hostname, or contact support if you believe the hostname is yours.

"Hosts under the platform portal zone are assigned automatically and cannot be registered as custom domains."

You entered a platform portal address. You don't need to add these, because publishing adds them.

The domain is Verified but the portal shows "not found"

A domain only routes traffic; it doesn't publish anything. Check that the portal is Published and Active. Also check that its slug still matches the slug in the domain's Type column (Portal: <slug>). If the slug has changed, add the hostname again with the right portal and click Refresh verification.

An apex domain (example.com, with no subdomain) won't verify

Standard DNS doesn't allow a CNAME record at the apex of a zone. If your DNS provider supports ALIAS or ANAME records, or CNAME flattening, use that. Otherwise serve the portal on a subdomain such as shop.example.com.

"Unable to refresh domain" on a Platform row

Refresh verification works only on custom domains. Platform rows are verified automatically when you publish.

Common questions

What is the difference between the Web and Portal domain types?

A Portal domain serves a portal directly on that hostname, so visitors see the portal with your name in the address bar. A Web domain is an entry hostname for the xMatix application itself: anyone who opens it is sent on to the app for your organization, where your own team signs in. Both types are verified in the same way, with a CNAME and a TXT record. When you are putting a portal on your own name, choose Portal and pick the portal in Portal site. To change the type, add the same hostname again with the other type. The row is replaced and becomes unverified. Make sure your CNAME matches the target shown, then click Refresh verification.

Does unpublishing the site break a verified custom domain?

No. Unpublishing removes only the platform address. Your custom domain stays on the Domains list and stays Verified. While the site is unpublished, requests to the custom domain get "not found". When you publish again, the custom domain serves the portal again with no DNS work. Turning Active off works the same way. Removing the domain on the Domains screen is the only action that detaches it from the platform, and you would then need to add it and verify it again.

Can visitors still use the platform address after I add a custom domain?

Yes. A custom domain is an extra name for the portal. It doesn't replace the platform address, and both serve the same published pages with the same audience rules. If you want visitors to use only your hostname, share only that one. The platform address keeps working for as long as the portal is published.

How do I move a custom domain to another portal?

Click Add domain, enter the same hostname and pick the new portal. This replaces the existing row and sets it back to unverified. Check that your CNAME still matches the target shown in the row, then click Refresh verification. If your records are still in place, the domain is verified again and starts serving the new portal within a few minutes.

Related topics

• Build and publish a portal
• Portal pages and data views
• Portal security
• Troubleshooting portals
• Security profiles
• Portals on the xMatix site