Table of Contents

Troubleshooting the Customer Portal

Mitchell Paul-Soumis Updated by Mitchell Paul-Soumis

Read Time: 4 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.

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

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

How did we do?

My Info: Your Personal User Settings

Customizing Your Customer Portal