Skip to main content

Configure Hostname Aliases

Learning Objectives

After completing this unit, you’ll be able to:
  • Describe the hostname alias file structure and syntax.
  • List three steps to take to set up and register the DNS and domain names.
  • Explain why you must configure a hostname alias for the current instance hostname.

Meaningful URLs

A hostname alias is a way to define alternative names for an existing website URL. Brandon Wilson, the Cloud Kicks merchandiser, uses Business Manager to create these aliases—short, meaningful URLs for external search engines to index. He also creates alias files so that when a shopper types a URL into their browser, Salesforce B2C Commerce can send them to localized or content-specific sites.

Alias files tell B2C Commerce how to process URL redirects, whether they are static or dynamic, and if they use patterned URL structures to direct shoppers from old (legacy) URLs to new ones. Both static and dynamic mappings do a 301 redirect (a permanent redirect from one URL to another).

Static mappings handle individual URLs, while dynamic mappings are for handling a set of URLs that match a specific pattern. For example, you might use a static mapping for a single Contact Us form page and a dynamic mapping for a set of product pages. To set up the dynamic mapping, you need an identifier such as the product ID from the legacy URL for the product pages. (Otherwise you need to create individual static mappings for each individual product page.)

Brandon starts by configuring a hostname alias for the current hostname on which the storefront runs. He configures www.cloudkicks.com in the alias list, for example, so shoppers get to his storefront without typing the entire URL.

http://www.cloudkicks.com/on/demandware.store/Sites-MY-Site/default/Home-Show

If he doesn’t configure the basic storefront URL, he’s actually restricting the number of shoppers who land on his site. Shoppers must enter the entire welcome or landing page URL, or get the dreaded 404 (page not found) error. Search engines only see this long URL if someone posts a link that contains it.

The SEO mapping could be https://www.cloudkicks.com/homepage.

With hostname aliases, a long, complicated URL converts to a simple search-friendly URL.

Domain Name Service (DNS) and Domain Names

Connection details matter. Brandon asks Vijay Lahiri, the developer, to help make the right ones. Vijay also helps Brandon create his hostname alias file.

Vijay Lahiri, Cloud Kicks developer

Vijay sets up and registers the DNS and domain names involved so he can use them in aliases.

Here are the steps to take.

  1. Purchase a domain.
  2. Configure the DNS for that domain to define a hostname.
  3. Obtain a transport layer security (TLS) certificate containing the name (or multiple names) from a certificate authority.
  4. Add the hostname to your hostname alias file as part of a rule.
  5. Include the host name alias settings parameters.
Tip

Tip

If your host is listed in Business Manager (site > Merchant Tools > SEO > Aliases), and the site has only one locale, create search-friendly links to the home page. It doesn’t require more information to determine the locale.

DNS and domain names are picky. Each certificate Vijay installs requires a unique IP address. The first certificate shares the IP address with the B2C Commerce hostname. For example, if the B2C Commerce hostname is production.realm.web.cloudkicks.net and the IP address is 100.100.100.1, the first certificate he installs gets the IP address 100.100.100.1. If he installs a second certificate, it gets 100.100.100.2 as its IP address.

Make sure your DNS is updated with the corresponding hostname IP addresses.

Embedded Content Delivery Network (CDN)

If you use the embedded CDN feature, don’t configure a fixed IP address for your DNS server. Instead, when you point your hostname DNS record to the embedded CDN in Business Manager, create a canonical name (CNAME) record. CNAME records are used to alias one name to another.

What’s in a Hostname Alias File?

The hostname alias file contains the hostnames/domains supported by a B2C Commerce storefront. It also contains the pipelines triggered (automatically run) for specific URLs. This file is required for a production instance launch. A production instance can have multiple IP addresses that provide different storefront content for multiple domains per site or multiple sites per realm.

Alias files use JavaScript object notation ( JSON) format. Vijay makes sure that Brandon’s alias file includes the proper https host, which reflects the host name. For example, Vijay maps www.cloudkicks.com like this.

{ "__version": "1",
 "settings": {
     "http-host": "www.cloudkicks.com",
     "https-host": "www.cloudkicks.com"
     }
}

Instance Specific

A B2C Commerce instance is an application infrastructure that includes web, application, and database servers. Merchants like Cloud Kicks typically receive staging, production, and development instances on the primary instance group (PIG), along with sandboxes for code development on the secondary instance group (SIG).

Each instance has its own alias file, so these files are not included in data replication. This ensures that a data replication containing site URL management data doesn’t overwrite production with the staging settings.

Tip

Tip

If you configure hostnames in your aliases file, do not configure the deprecated HTTP/HTTPS setting in Business Manager (Administration > Sites > site > Settings). This setting is replicated and can override the production hostname causing unexpected results.

Vijay edits the alias file on each instance to make them all the same.

For his cloudkicks.net hosts, he uses the "-" URL in the alias, like this.

{ "__version": "1",
 "settings": {
     "http-host": "development-realm-cloudkicks.demandware.net",
     "https-host": "development-realm-cloudkicks.demandware.net"
     }
} 

The Production Instance

The production instance hostname is unique in that it’s similar to production-realm-cloudkicks.demandware.net, with an IP address such as 100.100.100.1. This hostname is a fully qualified domain name (FQDN). It has a site-paths feature with /s/siteID/ behavior that enables this hostname to browse each storefront site without alias configurations, for example, >production-realm-cloudkicks.demandware.net/s/CKSite/mens.

Vijay uses this hostname to access Business Manager and connect to Visual Studio Code, WebDav, and other development connections. While he can use this hostname to view the storefront, his shoppers must not use it because it isn't best practice for SEO and doesn’t promote brand marketing.

Here’s an example of an alias file on a production instance.

{
    "__version": "1",
    "www.cloudkicks.com" : [{"pipeline": "Home-Show" }],
    "production-realm-cloudkicks.demandware.net" : [{"pipeline": "Home-Show" }],
    "cloudkicks.com": [{"host": "www.cloudkicks.com", "path":"/"}]
} 

Each production alias file must include the production.cloudkicks.demandware.net address for the production instance and the DNS hostname address. The production.cloudkicks address can also include the realm or name of the partner who's implementing the site.

Alias File Format

Here’s what an alias file looks like.

{"__version": "1",
"settings": {
    "http-host": "httphostname",
    "https-host": "httpshostname",
    "job-hostnames":
    {
       "default":"www.my-default-host.com",
       "de":"www.my-de-host.com",
       "en":"www.my-en-host.com"
        },
    "site-path": "sitepath",
    "default" : "defaultValue",
    "site-path-trailing-slash" : "yes", }
"hostName1": [
    { mappingRule1 },
    { mappingRuleN }
],
"hostNameN": [
    { mappingRule1 },
    { mappingRuleN }
]
}

Vijay and Brandon are now ready to look at the version, settings, and hostName parameters.

Version

The version parameter is required and must be 1. It indicates the file’s syntax version, not the file version. If you change it to another number, B2C Commerce ignores all entries.

Settings

Vijay and Brandon decide to use the job-hostnames settings only within the B2C Commerce job context. This way a job running on the staging instance can generate URLs using the hostnames used for the production instance. The mapping can be locale-specific and follow a country/language/default locale fallback. They can use the hostname in either the settings section or the rules section, and not both. Brandon decides to use it in the rules section, so he can map multiple locales on a granular level.

hostName

The hostName parameter is the hostname of the named URL. Brandon configures multiple host names, enabling the site to handle requests for all of them.

Configure Hostname Aliases

Brandon wants to steer traffic from the old legacy site to the new site like this.

From To
eu.cloudkicks.com/fr/ cloudkicks.com/ck_fr/

In this module, we assume you are a B2C Commerce merchandiser with the proper permissions to perform these tasks. If you’re not a B2C Commerce merchandiser, that’s OK. Read along to learn how your merchandiser would take these steps in a sandbox instance. Don’t try to follow our steps in your Trailhead Playground. B2C Commerce isn’t available in the Trailhead Playground.

If you have a sandbox instance of B2C Commerce, you can try out these steps in your sandbox. If you don’t have a sandbox, ask your manager if there is a sandbox that you can use.

Here’s how to configure hostname aliases.

  1. Open Business Manager.
  2. Select site > Merchant Tools > SEO > Site URLs > Aliases. Business Manager Alias Configuration page.
  3. On the Aliases page, specify the cloudkicks.com and eu.cloudkicks.com domain names.
    {
        "__version": "1",
        "cloudkicks.com": [{
            "locale": "fr_FR",
            "if-site-path": "ck-fr"
           }
        ],
        "eu.cloudkicks.com": [{
            "locale": "fr_FR",
            "if-site-path": "fr"
           },
           {
            "host": "cloudkicks.com"
           }
        ]
    }
  4. Test that your rules are valid JSON by testing them in a debugging tool such as the JSONlint validator.
  5. When you are satisfied that your rules are valid, copy the text into the editor and click Apply.

Now when a shopper navigates to eu.cloudkicks.com/fr/, B2C Commerce automatically routes them to cloudkicks.com/ck-fr/.

Next Steps

In this unit, you learned what’s in an alias file and how to configure one. In the next unit, you learn why duplicate entry points are a problem and how to avoid them. You also learn about URL mapping rules.

Keep learning for
free!
Sign up for an account to continue.
What’s in it for you?
  • Get personalized recommendations for your career goals
  • Practice your skills with hands-on challenges and quizzes
  • Track and share your progress with employers
  • Connect to mentorship and career opportunities