Website channel management

Website channels encapsulate websites managed by Xperience. Each channel is an independent entity with its own domain name configuration and content management.

Channels store content in pages and linked content items. See the content modeling guide to learn more about the recommended ways to store and display content in Xperience. 

Create website channels

To create a new website channel:

1. Open the Channel management application in the Xperience administration.
2. Select New channel.
3. Fill in:
   • Channel name – the name of the channel displayed in the administration. Also sets the name of the channel application where users manage the website’s pages and edit content.
   • (Optional) Identifiers – specify the code name if you wish to use a code name different than the pre-filled value.
     • Channel code names must be unique across all channels (of any type).
     • In projects intended for SaaS deployment, use code names with only alphanumeric characters.
   • Channel type – select Website as the channel type.
   • Channel size – channels are available in two sizes: Standard and Micro. Standard channels may contain an unlimited number of content items. Microchannels are limited to 20 items (pages, folders). Each page can link an unlimited number of reusable content items.
   • Website domain – the domain name on which the website will be accessible. See Website channels in self-managed environments to learn about the expected format and limitations when setting website domains.
   • Primary language – a language configured in the Languages application. In multilingual content, the primary language is not displayed in URLs, as opposed to other languages. For example: If the primary language is set to English, and content is also in French, the URLs are in the format:
     • ~/page for English
     • ~/fr-fr/page for French
4. Save the changes.

The website channel is now ready. After you add a channel, the system automatically creates a new application matching the channel’s name in the Channels category of the administration’s application list. This is the application where users can create and edit the channel’s pages.

Configure website channels

If you need to configure an existing channel, open the channel again via the Channel management application and edit the values on the General and Channel settings tabs.

Changing the Primary language affects the live URLs of the website’s pages in the given languages, and breaks page links added in the Rich text editor.

Website channels in self-managed environments

Each website channel must have a unique domain assigned. The domain determines where the live website is accessible. The system also uses the domain when displaying previews of live content, resolving hyperlinks in text, and other cases.

Domain name format

Use the following format for the domain name:

• include the port number if the application is running under a different port than 80
• do not include the URL scheme (protocol) – both http and https are included automatically
• include the path in the URL if your site is running under a specific path, for example, mysite.com/path

Incorrect domain name:

• https://mysite.com

Correct domain names:

• mysite.com
• partners.mysite.com
• mysite.com:8080
• mysite.com/path

Configure a domain name in the Xperience administration

1. Use a domain name conforming to the domain name format.

   To run Xperience in your local development environment, for example on the localhost domain, set Website domain to localhost.

   You can configure the system to use a different set of domains according to the project environment. See Domain aliases and environment-specific domains.

2. Open the Channel management application in the Xperience administration.

3. Select the website channel.

4. Switch to the General tab.

5. Edit the Website domain field.

6. Select Save.

The domain name is now registered in the Xperience administration.

Domain aliases and environment-specific domains

Domain aliases are alternative domain names that point to the same website. You can add any number of domain aliases to the main domain name.

Channel domain aliases can be configured programmatically using the WebsiteChannelDomainOptions options class and ASP.NET Core configuration providers.

For example, when configured via appsettings.json:

{
  "WebsiteChannelDomains": {
    "DomainOverrides": {
      "DancingGoatPages": {
        "Domains": [ "dancinggoat.com", "dancingllama.com" ]
      }
    }
  },
  ...   
}

Where DancingGoatPages is the code name of the website channel to configure.

The system uses the first domain specified in the Domains array as the main domain (dancinggoat.com in the example above). This configuration takes priority over the channel options set via the General tab in the Xperience user interface. The domain gets used, for example, when resolving relative links (in rich text content, email body). All additional domains are treated as domain aliases – they can be used to access the website, but are not reflected in URLs.

using CMS.Websites;

var builder = WebApplication.CreateBuilder(args);

// Apply the configuration from appsettings.json
builder.Services.Configure<WebsiteChannelDomainOptions>(builder.Configuration.GetSection("WebsiteChannelDomains"));

For channels not configured via application settings, the values specified via the administration interface are used.

You can also make use of the options pattern to set different domains per environment by introducing corresponding appsettings.environment.json files. The following example sets the primary domain to localhost when the project is run under the Development environment.

{
  "WebsiteChannelDomains": {
    "DomainOverrides": {
      "DancingGoatPages": {
        "Domains": [ "localhost", "localdev.com" ]
      }
    }
  }
}

Website channels in the SaaS environment

Add website channels in Xperience Portal

For applications deployed in the SaaS environment, you need to add your channels in Xperience Portal after you create them in the Xperience administration:

1. Open the Channels and Domains → Channels application in Xperience Portal.
2. Select Add channel.
3. Set the channel properties:
   • Display name – enter a name for the channel that will be displayed in Xperience Portal.
   • Code name – copy the exact code name of the website channel from the Channel management application in the Xperience administration.
   • Channel type – Website
   • Channel size - select the same channel size as in the Channel management application in the Xperience administration.
4. Select Add channel.

After you add a channel, the system automatically starts configuring channel domain settings for the deployed applications. This process may take up to several minutes. You do not need to (and cannot) configure the channel’s domain in the Xperience administration.

Once the domain configuration is complete, the content of the website channel becomes available under an automatically generated Default domain. For production environments, you need to add suitable custom domains for the channel.

Manage channel domains in Xperience Portal

Website channels in Xperience Portal use the following types of domain names:

• Default – a default domain is generated for every website channel and environment. Default domains cannot be removed or altered.

• Custom – a custom domain added for the PROD environment. This can be either an apex domain (example.com) or a subdomain (www.example.com, sub.example.com, …).

  The apex domain and every subdomain are considered as individual custom domains and need to be added separately.

  The number of available custom domains depends on your service plan. Plans up to Level 3 allow 2 custom domains by default (one for the apex domain and one for the www subdomain). Should you need additional custom domains, contact Kentico sales.

• Main domain – the primary domain set for the website channel, for example used in links to the site’s pages. Each channel can only have one main domain, typically a custom domain name suitable for the production environment.

Add custom website channel domains

To set a custom domain for a website channel you need to add the domain in Xperience Portal and set the corresponding DNS records in the DNS registry of your domain provider:

1. Choose a domain name conforming to the following rules:
   • The website cannot run under a specific path, for example: mysite.com/path
   • The domain name cannot include a port number or URL scheme.
2. As a user with the Tenant administrator or DevOps Engineer role, open the Channels and Domains → Channels application in Xperience Portal.
3. Select the Domains () action for the chosen website channel.
4. Select Add domain.
5. Enter the custom Domain name and select Next.
6. Copy the displayed DNS records from Xperience Portal to your DNS registrar.
7. After the records are successfully registered with your DNS registrar, confirm the DNS configuration and select Create. This triggers a DNS validation process that takes a few minutes to finish.
   • If the DNS validation fails, double-check your DNS settings, wait a few minutes, and select Validate () to restart the validation. See Revalidate custom domain DNS settings.
8. Use the Home () action to set the newly added custom domain as the website channel’s main domain.

The system automatically configures the new domain settings for the deployed production application. This process may take up to several minutes. You do not need to (and cannot) configure the channel’s domain in the Xperience administration.

Your application is now available under the configured domain name.

You can see the main domain configured for each environment and website channel in the Deployments application in Xperience Portal.

Domain status

You can check the status of a channel’s domains in the Channels and Domains → Channels application in Xperience Portal. Select the Domains () action for a specific channel.

• Active – The domain is active and working.
• DNS validation failed – The DNS records are configured incorrectly, or the configuration has not yet been propagated through the DNS servers. See Revalidate custom domain DNS settings.
• Error – A system configuration issue with the domain. Contact Kentico support.
• Transient error – There was a temporary error while creating, validating, or deleting the domain. To recover from this status, use the Revalidate () action to resubmit the domain.
• Creating – The domain is being created.
• Deleting – The domain is being deleted.

Revalidate custom domain DNS settings

If you add a custom domain for a channel and its DNS validation fails, you need to revalidate the DNS settings in Xperience Portal.

1. Open the Channels and Domains → Channels application in Xperience Portal with a Tenant administrator or DevOps Engineer role.
2. Select the Domains () action for the related channel.
3. Select Revalidate () to restart the domain validation for a domain.
4. Xperience Portal displays DNS settings. Apply these settings with your DNS registrar.
5. After the settings are successfully registered with your DNS registrar, select the checkbox confirming the DNS configuration and select Validate. This triggers a DNS validation process.
6. Allow a few minutes for the DNS validation to finish.
7. Check the domain status.

Your custom domains are now revalidated. If the issues persist, contact Kentico support.