Table of Contents

Adding a Customer Portal to Your Sonar Instance

Mitchell Paul-Soumis Updated by Mitchell Paul-Soumis

The Sonar Customer Portal allows your customers to login to their own dedicated dashboard where they can do things like:

  • View their bill
  • Make payments
  • View data usage
  • View signed contracts
  • Open and reply to support tickets
  • And more

Before beginning installation and setup of the Sonar Customer Portal, there are a few prerequisites that need to be in place. If any of the below prerequisites are not met, the installation process will fail and the customer portal will not work.

Update Your DNS Records

Before starting installation of the Customer Portal, a DNS A Record must be created on a valid domain that you own. You'll also need to have a valid public facing IP Address for the server you'll be hosting the customer portal on.

For example, let's say you're the proud owner of example.com and want your customers to be able to access the customer portal by going to portal.example.com, you would use the following steps to set this up:

  1. Login to your domain name registrar's website (https://www.namecheap.com/ is being used in this example, but the process will be generally the same for all domain name registrars or web hosts).
  2. Find your domain example.com Advanced DNS Settings or DNS Zone Editor).
  3. Once within the DNS settings for your domain, you'll want to create a new DNS record of type A Record with your desired hostname (in this case since we're using portal.example.com, we'll set our hostname to say portal) and the IP Address of the server you're wanting your customer portal hosted on.

This should look something similar to the screenshot below:

Once you've created this new A Record and saved your changes, it'll take anywhere from a few minutes, up to 72 hours before the changes propagate throughout DNS servers worldwide.

After this process is completed, we can the move on to the next step listed below of ensuring your server has the necessary hardware requirements needed to run the Sonar Customer Portal.

Hardware Requirements

Before beginning the installation of the Sonar Customer Portal, it's important to make sure your server has the necessary hardware requirements needed to properly run the Sonar Customer Portal.

Detailed below are the minimum system requirements that every customer portal server will need in order to function properly:

OS: Debian-based OS running Ubuntu 16.04 x64 server or Ubuntu 18.04 x64 server

CPU Requirements: 2 CPU Cores (or 2vCPU)

RAM: 2GB RAM
The Sonar Customer Portal utilizes Docker based containerization technology.

Ubuntu 19 does not support Docker, thus the Sonar Customer Portal WILL NOT work on Ubuntu 19.xx

Preparing your Sonar Instance

Linking the Customer Portal URL to your instance

In order to link your new customer portal URL created previously to your Sonar instance, navigate to Settings -> Companies -> "Edit" on the applicable company.

From the Edit pane, enter the Customer Portal URL as created on your DNS record (A Record).

Creating your Customer Portal User and User Role

Within your Sonar instance, there needs to exist a special user account called customer_portal_api.

Technically the name you give this user doesn't matter, but we recommend naming this user customer_portal_api so that it's easily recognizable at a glance to both yourself as well as Sonar staff if troubleshooting ever needs to be done by us in the future.

This special user account acts a bridge that connects your Sonar Customer Portal server to your Sonar Instance via the Sonar API.

API User Permissions

In addition to there needing to be a special customer_portal_api user within your Sonar instance, there also needs to exist a special role called Customer Portal to accompany it.

The purpose of this role is to allow the Sonar API to provide the customer portal with the necessary permissions that allow your customers to do things like: view their account information, create support tickets, update their payment information, etc.

Run the following in GraphQL at your Sonar V2 instance (e.g., yourname.sonar.software/graphiql)

  1. First create a variable (drag the lower-left window upwards to reveal the screen)
{
"customer_portal"
:
{
"name": "Customer Portal",
"applied_permissions": [
"READ_DATA_USAGE_HISTORY",
"CREATE_TICKET",
"READ_TICKET",
"UPDATE_TICKET",
"CREATE_PAYMENT_METHOD",
"CREATE_PAYMENT",
"READ_ACCOUNT",
"READ_PAYMENT_METHOD",
"READ_ACCOUNT_TRANSACTIONS",
"READ_CONTRACT",
"UPDATE_PAYMENT_METHOD",
"UPDATE_ACCOUNT_TRANSACTIONS",
"UPDATE_CONTACT",
"UPDATE_CONTRACT",
"DELETE_PAYMENT_METHOD",
"CREATE_ACCOUNT_TRANSACTIONS",
"READ_INVOICE_ATTACHMENT",
"READ_INVOICE_MESSAGE",
"READ_SERVICE",
"CREATE_DATA_USAGE_TOP_OFF",
"READ_PACKAGE",
"MODIFY_ACCOUNT_SERVICES",
"READ_PAYMENT_PROCESSOR",
"UPDATE_ACCOUNT",
"READ_INBOUND_MAILBOX"
],
"note": {
"message": "Customer Portal",
"priority": "NORMAL"
}
}
}
  1. Then run this mutation in the top-left panel:
mutation createRole($customer_portal: CreateRoleMutationInput) {
createRole(input: $customer_portal) {
name
}
}

Building the Portal

Install the Customer Portal Image on your VM

  1. SSH into your VM
  2. Install required packages:
sudo apt-get -y update && sudo apt-get -y upgrade && sudo apt-get -y install git unzip
  1. Clone the repository:
git clone https://github.com/SonarSoftwareInc/customer_portal.git
  1. Now change directory into the repository that we've just cloned:
cd customer_portal
  1. Run the Install Script:
sudo ./install.sh | tee customerportal-install.log
  1. Follow the instructions as prompted by the installation script, providing the following:
    1. Portal Domain Name (e.g. portal.example.com)
    2. The API Username
    3. The API password
    4. Your instance URL (e.g. https://example.sonar.software)
    5. Your email address (for SSL Certificate)
  2. Once completed, the installation script will automatically reach out to Let's Encrypt to generate an SSL certificate for your customer portal
If the DNS record is not pointing to the correct IP address at this point, the certificate install and the portal install will fail
  1. Once the SSL Certificate is generated, and the installation completes, the Settings Key is generated. Please note this Settings Key in a secure location, as it provides you access to managing the Customer Portal settings, such as mail server settings, payment settings, and appearance customization.

Commands you can use after setup

From the customer_portal directory, you can execute sudo docker-compose exec app /bin/bash to access the docker container that the portal is running in. After doing this, you can execute the commands below.

  • php artisan sonar:settingskey will generate a new key for the /settings page if you forget the one you had.
  • php artisan sonar:test:smtp {email} will test your email configuration. Replace {email} with your email address, and the portal will attempt to send you a test email.
  • php artisan sonar:test:paypal will test your PayPal configuration, if it is enabled

Managing Settings & Using the Settings Key

After you've successfully completed installation of the Sonar Customer Portal, the installation script will provide you with a Settings Key.

The Settings Key (also referred to as Authentication Key) is a special 32 character long string that allows you to access and modify the configuration settings for your customer portal through your web browser. Your customer portal's settings page contains critical customization options that need to be in place for your portal to function properly.

If we continue to follow our example from earlier, you would access the settings page for your customer portal by navigating to https://portal.example.com/settings

Make sure to take note of your Settings Key. Not having your settings key securely saved for easy access will delay the customer portal configuration process.

After navigating to the settings page for your customer portal, you'll be prompted to enter your Settings Key in order to authenticate and gain access to the configuration settings for your customer portal.

After successfully authenticating with the settings key, you'll then be presented with the various configuration options for the Sonar Customer Portal.

From here you can fill in the fine details of what information you want displayed to customers via the portal. This includes configuration options for billing and your outbound mail server.

Mail Settings Configuration

The Mail Settings configuration section on your customer portal pertains to the outbound mail server that you plan to use. The outbound mail server is what allows the customer portal server to send mail to your customers when they do things like:

  • Registering for the Customer Portal - the outbound mail server will send them a registration email which will give them instructions on how to register for a new customer portal account.
  • Initiating Password Resets - the outbound mail server will send them a password reset email with instructions on how to reset the password for their customer portal login.
Make sure you have access to a mail server and its settings before giving customers access to the customer portal. You will not be able to complete the configuration of your customer portal without this.

If you don't have a dedicated mail server in-house that you'd like to use, or if you're unsure about which service is best for this, we highly recommend going with SendGrid.

It is recommended to NOT use a personal Gmail account (or other free, similar email service) as you will almost certainly run into significant issues due to GMail throttling messages and perceiving the automated, identical emails as spam.

Billing Configuration

The General Billing section of the customer portal's configuration page allows you to determine what customers are able to see and do in regards to:

  • Viewing a detailed breakdown of their billing transactions
  • Making payments using a credit card
  • Making payments via eCheck or ACH
  • Making one-time Paypal payments
If you choose to let customers manage payments (via Credit Card, ACH, or Paypal) within the customer portal, you'll need to make sure you've setup the correct Payment Processor Integrations within your Sonar instance first.

Ticket Configuration

If you'd like to allow customers to open, view, and respond to support tickets via the customer portal, you'll need to make sure that the Enable Ticketing option is toggled on within this page.

This will not work until you've properly setup your Outbound and Inbound Email within your Sonar instance. Make sure you've also created at least 1 Ticket Group in your Sonar instance as well.

Testing Customer Portal Configuration

Before notifying customers about your new customer portal, it's a good idea to test your portal's configuration first to make sure everything is working properly.

As best practice, we recommend creating a test account within your Sonar instance that's dedicated to testing and experimentation.

With this test account, you can create a new contact on there where you can then test things like:

  • Registering this new contact for the customer portal access
  • Manually setting portal credentials for this contact (allows you to skip the portal registration process as well as perform manual password resets)

By doing one of the above options, you can then use this contact to login to the customer portal and ensure everything works as expected before giving real customers access.

Customizing the Portal

While Sonar provides a pre-built Customer Portal (using Laravel) which can be tied to your instance and used to provide more control to your customers, we don't want to limit your creativity, branding, or control how your customers access their information. The Sonar Customer Portal code repository is available on https://github.com/SonarSoftwareInc/customer_portal, and you're welcome to fork or clone this repository in order to modify the underlying code to suit your needs.

Don't modify the files inside the existing Docker Container without redirecting the GitHub link, as updates will overwrite all changes during an update

You can view our article which provides some basic commands to get you started with customizing the portal here | Customizing your Customer Portal

Troubleshooting Customer Portal installation

Troubleshooting Docker Instance Not Starting

Customer Portal - Manual Certificate Renewal

How did we do?

Contact