Configuration - SonarSoftware/customer_portal GitHub Wiki

Initial Configuration

The entirety of the configuration of the customer portal is performed by editing a single text file. You can edit this text file in the editor of your choice, for simplicities sake we will use nano in this example.

To begin, type nano /usr/share/portal/.env. This will open the Sonar customer portal .env file where all the configuration takes place.

To edit a value, modify the section after the = sign. Any text with a space or any special characters in it must be wrapped in double quotes ("). For example, if you want to change the FROM_NAME option from ISP to My Awesome ISP, you would change the line from FROM_NAME="ISP" to FROM_NAME="My Awesome ISP". Each option is documented below. It's a good rule of thumb to wrap everything in double quotes if it's a string.

Any time you make a change to this file, it is imperative that you run php /usr/share/portal/artisan config:cache - if you do not run this command, any changes you make will not be applied!

Application Configuration

The top section of the .env file deals with the configuration of the basic application. The portal is built on top of Laravel and most of these options deal with the Laravel framework. The only one you need to change is APP_URL.

  1. APP_ENV - This is the environment that Laravel (the framework used to build the portal) is running in. Unless you understand the function of this option, leave it as production.
  2. APP_DEBUG - As above, this is a Laravel function. Leave it set to false unless you know why to change it!
  3. APP_KEY - This is the key used for any encryption in the customer portal. It is automatically set to a random string during portal installation - don't change it.
  4. APP_URL - This must be set to the full URL of your customer portal, including https (e.g. https://portal.myisp.com)

Mail Configuration

This section deals with outbound mail from your customer portal. It is very important that this is configured correctly, or users will not be able to create accounts or reset passwords. We will be able to test these settings later.

If you need an outbound mail service (e.g. you don't have your own SMTP server to use) you should sign up for a reputable one, for example, Mailgun. Mailgun will allow you to send 10,000 emails a month for free, which is plenty for most portals. You should not try to use something like a personal GMail account, as you will certainly run into throttling problems over time, and you will be forced to send outbound email from a personal email address.

  1. MAIL_DRIVER - Leave this as smtp if you plan to use an external SMTP server. Laravel has some other drivers but I recommend sticking with SMTP for simplicity.
  2. MAIL_HOST - The hostname or IP address of your SMTP server.
  3. MAIL_PORT - The SMTP port of your mail server.
  4. MAIL_USERNAME - The username to use when authenticating to the remote server, if it requires authentication. Leave as null if it does not.
  5. MAIL_PASSWORD - The password to use when authenticating to the remote server, if it requires authentication. Leave as null if it does not.
  6. MAIL_ENCRYPTION - Set this to tls to use TLS encryption, if your mail server supports it. Set it to null otherwise.
  7. FROM_ADDRESS - The email address to use on outbound emails (e.g. [email protected])
  8. FROM_NAME - The name to use on outbound emails (e.g. My ISP)

General Configuration

This section deals with general configuration of the customer portal.

  1. ISP_NAME - The name of your ISP. This is shown in the title bar and various other parts of the portal.
  2. DECIMAL_SEPARATOR - Set this to the character you use for separating decimals in your language (do you write 100.01 or 100,01?)
  3. THOUSANDS_SEPARATOR - Set this to the character you use for separating thousands in your language (do you write 1,000 or 1.000?)
  4. CURRENCY_SYMBOL - Set this to your currency symbol (e.g. $)
  5. COUNTRY - Set this to the two character code for your country. E.g. US, CA, GB. You can see a list here.
  6. STATE - Set this to the two character code for your state if you're in the USA or Canada (e.g. WI, AB) or the full name of your default state/province if you're in any other country.
  7. LOGIN_PAGE_MESSAGE - Set this to null if you don't want a custom message displayed on the login page. Otherwise, you can set this to a short message you'd like displayed to users on the login page.

Billing configuration

  1. SHOW_DETAILED_TRANSACTIONS - Set this to true if you'd like to show your customers a detailed transaction list in the portal. If this is false, they will only see a list of invoices and credit cards. I recommend setting this to false unless you have a good reason to show a detailed transaction list.
  2. ENABLE_CREDIT_CARD_PAYMENTS - Set this to true if yoou'd like to allow customers to add and modify credit cards via the portal, as well as make payments via credit card.
  3. ENABLE_BANK_PAYMENTS - Set this to true if you'd like to allow customers to add and modify eCheck or ACH accounts via the portal, as well as making payments via eCheck or ACH via the portal. Please note that there is the potential for abuse when this is enabled. Unlike credit card payments, ACH/eCheck bank account numbers cannot be validated in real time, so even if a customer inserts an invalid bank account number, the transaction will process successfully until the ACH/eCheck batch is processed. Due to this, an unscrupulous customer could make multiple invalid payments to bring their account balance to zero, and you would have to reconcile the bounced transactions once they have been batched.

GoCardless.com integration

  1. ENABLE_GOCARDLESS - Set this to true to enable GoCardless integration. Please see the Sonar Casts for more details on this integration.
  2. GOCARDLESS_ACCESS_TOKEN - If you're using GoCardless, this is the access token for your account.
  3. GOCARDLESS_ENVIRONMENT - Set this to live if your access token is a live token, or sandbox if you're testing.
  4. GOCARDLESS_CURRENCY_CODE - Should be set to one of GBP for Pounds Sterling, SEK for the Swedish Krona, or EUR for the Euro.

PayPal configuration

If you wish to accept PayPal payments through the customer portal, your PayPal API information must be configured here. We will be able to test this later. If you are using PayPal here, you should also enable PayPal in your Sonar instance using exactly the same credentials. If you don't, you will not be able to refund PayPal payments through Sonar!

  1. PAYPAL_ENABLED - Set this to true to enable PayPal payments in the portal, or false to disable.
  2. PAYPAL_API_CLIENT_ID - If PAYPAL_ENABLED is true, this must be set to valid, live, REST API credentials. These can be generated at https://developer.paypal.com under 'My Apps and Credentials' by clicking 'Create App'. Be sure to create LIVE credentials and not SANDBOX!
  3. PAYPAL_API_CLIENT_SECRET - If PAYPAL_ENABLED is true, this must be set to valid, live, REST API credentials. These can be generated at https://developer.paypal.com under 'My Apps and Credentials' by clicking 'Create App'. Be sure to create LIVE credentials and not SANDBOX!
  4. PAYPAL_CURRENCY_CODE - Currency code from https://developer.paypal.com/docs/classic/api/currency_codes/

Ticketing Configuration

If you wish to allow users to create new public tickets through the portal (as well as view their existing public tickets), then this section must be configured.

  1. TICKETING_ENABLED - Set this to true if you wish to allow ticketing in the portal, false if not.
  2. INBOUND_EMAIL_ACCOUNT_ID - If TICKETING_ENABLED is true, you must configure the inbound email account you wish to use in Sonar to create the public ticket. The easiest way to find this ID is to navigate to Ticketing > Inbound Email in Sonar, and edit the inbound email account you wish to use. The number at the end of the URL is the inbound email account ID (e.g. if your address bar shows https://myisp.sonar.software/system/tickets/inbound_email_accounts/6, then your inbound_email_account_id is 6.)
  3. TICKET_GROUP_ID - The ID of the ticket group you want tickets created in the customer portal to be placed into. Either this or TICKET_USER_ID must be set. You can find the ticket group ID in the same way as the inbound email account ID - just edit a ticket group and check the URL.
  4. TICKET_USER_ID - As above, but the responsible user.
  5. TICKET_PRIORITY - A number from 1-4 that specifices the priority of tickets created via the portal. 1 is critical, 2 is high, 3 is medium, and 4 is low.

Data Usage Configuration

If you wish to allow users to view their data usage (and purchase top off services, if applicable) then this section must be configured.

  1. DATA_USAGE_ENABLED - If this is true, then the data usage section will be enabled. If false, it will be disabled.

Contract Configuration

If you utilize the contract signing features of Sonar, and you would like your users to be able to view unsigned contracts, and download signed contracts, from within the customer portal, then this section must be configured.

  1. CONTRACTS_ENABLED - If this is true, then the contract section will be enabled. This section allows users to sign and download contracts associated with their account.

Password Strength

You can provide helpful hints about whether or not a password is valid during account creation by setting PASSWORD_STRENGTH_REQUIRED to the same value you have set under System > Configuration > Customer Portal inside your Sonar instance. This will evaluate passwords in real time during account creation and offer more specific feedback as to how the password can be improved to pass the requirements. This generally only works well below strength 4 - at strength 4, the user will generally need to use a password manager to generate a password that will pass the requirements.

Completing Configuration Changes

To exit the file and save it in nano, press CTRL+X, answer y to save changes, and hit enter to overwrite the .env file.

Any time you make a change to this file, it is imperative that you run php /usr/share/portal/artisan config:cache - if you do not run this command, any changes you make will not be applied!

After configuring your portal for the first time, run php /usr/share/portal/artisan optimize for a quick speed up.

We can now move on to testing our configuration.