Publishing the Shelf Self-Service Portal on a Custom Domain



1 Prerequisites

Before proceeding to publish the Self-service library you created on Shelf on your company’s domain, make sure you have access to the following:
  1. Access to the domain’s DNS settings on which you want to publish the Self-service portal.
  2. Access to the webserver or a CDN to set up a reverse proxy
  3. TLS Certificate for the domain on which you want to publish the portal

This guide is applicable when you don’t want to host your SSP on a custom domain, but rather want to re-use your root domain and host the portal on a sub-path (for example, company.com/help vs help.company.com). The preferred way is to setup an SSP via DNS which is described in a different guide.


2 Getting Started

When you turn on your Self-Service Portal, your content is available through the Default Self-Service Portal domain by default. Your URL will look like this: https://xxxxxx-yyyyyy-zzzzzz.shelf-ssp.com/

If you’d like to use a different URL, you can create one by setting up a custom domain. You can do so by:
  1. Entering your custom domain in the Self-Service Configurator
  2. Creating a DNS record
  3. Configuring your CDN or a reverse proxy to point to Shelf’s SSP default domain


3 Entering your custom domain in the Self-Service Configurator

Enter the custom domain you want to use in the Basic Settings section. Let’s use help.comapny.com as an example.
You can also provide relative URLs such as comapny.com/help.



4 Create DNS Records

You should skip this step if you choose to configure SSL via Amazon CloudFront (see some section below).

If you have a web server such as Nginx, point a DNS record to your web server and follow the instructions in the section below to configure the reverse proxy with Nginx.

Below on the screenshot, you’ll find a hostname to be used as a destination for your web server or CDN.



5 Option A: Create a CDN on AWS



This option suits you if you have your SSL certificate uploaded on AWS or already use AWS CloudFront for other websites.


  1. Create a CloudFront Distribution

  2. Point to Shelf Self-Service domain (e.g. https://xxxxxx-yyyyyy-zzzzzz.shelf-ssp.com/)

  3. Create a Route53 Alias record to the CloudFront distribution



6 Option B: Setup a reverse proxy using nginx


6.1 Sample nginx.conf

This is an example file if you host your SSP on a subdomain such as help.comapny.com

If you don’t use nginx, the configuration will look different, but you should be able to derive the meaning of the setup regardless and apply to your load balancer in use.


# Prerequisites: ngx_http_ssl_module and ngx_http_proxy_module should be enabled


# Step 1: set up a normal server with HTTPS https://letsencrypt.org/

# Step 2: set up proxy settings as shown below

# Step 3: set custom domain in Shelf Self-Service Configurator

# Step 4: make sure your DNS record is configured to IP of your Nginx server


resolver 8.8.8.8; # use own DNS server if you have one

server {

    listen 443 ssl;

    server_name your-site.custom-domain.com; # replace this with your domain


    ssl_certificate /path/to/your/fullchain.pem;

    ssl_certificate_key /path/to/your/privatekey.pem;


    location / {

        # using "set" is important as IP addresses of Shelf servers

        # changes dynamically. "set" enables nginx to follow dynamic IPs

        set $shelf "https://your-default-shelf-self-service-portal-domain.shelf-ssp.com:443/";

        proxy_set_header Host “your-default-shelf-self-service-portal-domain.shelf-ssp.com”;

        proxy_pass $shelf;

        proxy_ssl_session_reuse on;

        proxy_ssl_server_name on;

        proxy_ssl_protocols TLSv1.2;

    }

}



6.1 Hosting your portal on a sub-path of a domain

These are some changes is an example file needed if you host your SSP on a custom domain with some path append such as comapny.com/help.


Change location / to location ~* ^/help/(.*)$


Change set $shelf "https://your-default-shelf-self-service-portal-domain.shelf-ssp.com:443/";

 to set $shelf "https:/your-default-shelf-self-service-portal-domain.shelf-ssp.com/:443/$1$is_args$args";


In essence, you need to proxy requests form a sub-path of your root domain to the default Shelf’s SSP default domain.



7 Mapping multiple domains to 1 Self-Service Portal

This feature is still in development, but you can already setup your reverse proxy like Nginx to serve 1 Self-Service portal under different domains. No specific changes on Shelf are required to make it work.