Table of Contents

Troubleshooting the Customer Portal

Mitchell Paul-Soumis Updated by Mitchell Paul-Soumis

Read Time: 5 mins

After installing the Customer Portal, there are a few things that can go wrong. In most cases, these issues will have simple fixes, and in this article, we'll review some common installation missteps, and how you can correct them.

Common Pre-Installation Issues

Let's Encrypt / Certbot is failing to install the SSL certificate on my portal

The Let's Encrypt certificate installation utility, also called "Certbot", automatically queries the domain name you supplied for ownership. You can read more about the specific process Certbot uses in Let's Encrypt documentation here, but at a baseline, it requires a DNS A Record pointed towards your server and firewall rules allowing access over port 80 (HTTP traffic) and port 443 (HTTPS traffic).

While Port 443 is not required to be open for Certbot verification, it will be required to allow customer traffic access to the Portal.

If the Let's Encrypt verification process is failing, this is likely due to the DNS settings, or firewall rules. For the DNS settings, repeat the steps highlighted in the "Update Your DNS Records" portion of the Customer Portal setup Knowledge Base article, while configuring the firewall rules should be detailed in the usage guide for your network hardware.

Certbot is saying my domain has hit the maximum number of requests

If you had issues with the automatic installation of the certificate, whether due to ownership or firewall issues, and you try to repeat the installation multiple times, you'll eventually encounter an error that states too many failed authorizations recently. If this happens, unfortunately, the only thing you can do is troubleshoot the reasons behind ownership verification and wait an hour before making any additional requests. You can read more about Let's Encrypt's various forms of Rate Limiting here.

You can test the domain independently against the Let's Encrypt staging environment in any Linux terminal by adding the --dry-run flag to a Certbot request.

My VM / terminal is telling me I have insufficient permissions

For the customer portal to install correctly, we recommend you run the commands using sudo. Should you get an error that there aren't sufficient privileges with sudo then you will either have to login as root or run sudo su if you don't have the credentials for root.

Be cautious when using sudo su as it provides an elevated permission level and can irreversibly affect your VM if the wrong commands are used.

Common Post-Installation Issues

I need to make changes to the portal install, but can't find the directory

The command find / -type d -name "customer_portal" -print 2>/dev/null will search the server and return the directory that the customer_portal directory is located. This will also bypass any permissions issues so you don't have to run it with root, but you may have to be in root to access the directory once you find out where it's located.

The installation completed successfully, but 401 errors pop up trying to access the portal

If this happens, there are a few possible causes. Either the portal user doesn't have the correct credentials/permissions or the password/username is incorrect when they were entered during the initial portal setup.

This can occur when the API password was not created following the correct guidelines, and did not contain at least 16 characters, and included special characters.

In either scenario, restart the customer portal installation process on your docker container and verify the credentials and permissions of the API user

Emails aren't sending from the portal's "Register" or "Reset" pages

Generally speaking, issues with emails sending from your portal will typically be caused by incorrect configuration on the settings page, or an issue with security settings from your email provider, although this is more common when using an email account hosted by Google. To correct this, please review the following troubleshooting steps:

  1. In the system settings page at https://[your portal URL]/settings, confirm that the mail username is the complete email address, along with verifying the password is correct.
  2. If using a Gmail domain, confirm the following:
    1. The password used for the email address in https://[your portal URL]/settings should be an app-specific password. See the Google documentation linked here.
    2. Google no longer supports the use of "Less secure apps" or devices which ask you to sign in to your Google Account using only your username and password. See the Google Documentation linked here.
  3. Once these settings changes have been made, you can add a contact and email to a test account, then enter that email into the form at https://[your portal URL]/register. If these settings are correct you should get a registration email sent successfully. Please ensure you use an email that is unique to a single account, or this process will fail.

The Customer Portal certificate isn't renewing automatically

This particular issue has an article dedicated to addressing it, available here.

The Customer Portal installation is having trouble performing updates

The most likely cause of this is the VM running out of storage space. In this case, the first thing to attempt is assigning more storage to your VM or your system, especially if the initial installation wasn't provided the recommended 25 GB.

I've forgotten the Settings Key generated for the Customer Portal

If you've forgotten your Settings key, you can perform a few simple commands to generate a new one:

  1. From the customer_portal directory, you can execute sudo docker-compose exec app /bin/bash to access the docker container the portal is running in
  2. The command php artisan sonar:settingskey will generate a new key for the "/settings" page of your Customer Portal to replace the forgotten key
    Other useful commands include php artisan sonar:test:smtp {email} to test your mail settings to some destination email address

I've made changes to the Customer Portal but they aren't showing

After changes are made to the customer portal, your docker container must be restarted to ensure the changes can be reflected. To do so, the following commands must be executed:

  1. The command customer_portal# docker-compose stop will stop running containers, but won't remove them.
    The portal will be unavailable for customers when this command is initiated and will not become accessible until the command below is issued.
  2. And customer_portal# docker-compose start will restart the containers stopped previously.

Once both commands have been executed successfully, the prior changes should be visible.

How did we do?

The New Sonar API

Upgrading your Ubuntu OS - Customer Portal Upgrades

Contact