Overview:

Congratulations on installing your own private instance of Helpy Pro. This document contains important information on how to administer and customize your instance, as well as keep it up to date. The following topics are covered below:

• Introduction to your Helpy server
• Updating Helpy
• Configure using environment variables
• Use an external database
• Use an external filestore
• Helpful command line tools

Note:  The instructions here only apply to Helpy Pro Marketplace images created using the APT package manager.

Introduction to your server

Helpy Pro is distributed as a package and by default is set to run as a “monolith”, meaning that the same server is used to store files as well as the database. This is great for testing and also suitable for production use for a small implementation. If you have larger needs, you should consider moving the database and file storage to improve reliability and durability.

Your installation includes a command line utility (CLI) for performing a number of common tasks. To see a brief overview, type:

sudo helpy

You can start helpy as a daemon using:

sudo helpy scale web=1

Restart helpy with:

sudo helpy restart

The number of workers and threads per worker are configured using environment variables.  This can be used to tune performance based on the number of CPUs and how much memory your server(s) have:

sudo helpy config:set PUMA_CONCURRENCY=8 # number of workers

sudo helpy config:set PUMA_THREADS=5 # number of threads per worker

You should refer to https://support.helpy.io/en/docs/162-tuning-your-helpy-instance to learn more about tuning these and other variables.

Updating Helpy

Updating Helpy is easy. Simply use the apt package manager on your Ubuntu server:

sudo apt-get update
sudo apt-get upgrade

After updating, you should run database migrations using:

sudo helpy run rake db:migrate

Configurations using ENV variables

Nearly every aspect of Helpy operation can be configured using environment variables on your server. To see a current snapshot of the environment configuration, type

sudo helpy config

You can change the configuration using the set and unset commands as follows:

sudo helpy config:set SOME_ENV_VAR=123abc
sudo helpy config:unset SOME_ENV_VAR

Using a remote database

Running a separate database node will free your app server to focus on serving requests, and moving to a Database as a Service (dbaas) such as AWS RDS or Digital Ocean’s Postgres service will add instant reliability. Furthermore, separating the database makes adding new app server or worker instances trivial.

To further improve resilience, consider clustering your database with at least one slave configured as a hot standby, in case of failure of the primary node.

To configure an external postgresql database, you will need to configure a handful of environment variables on your instance(s). Once this is done, you can optionally uninstall Postgres on your instance to free up the resources it uses.

sudo helpy config:set HELPY_POSTGRES_DB=postgres_database_name
sudo helpy config:set HELPY_POSTGRES_USER=postgres_db_user
sudo helpy config:set HELPY_POSTGRES_PASSWORD=postgres_db_pw
sudo helpy config:set HELPY_POSTGRES_HOST=postgres_db_host
sudo helpy config:set HELPY_POSTGRES_PORT=postgres_db_port

Once the database configuration is set, you will either need to create your new remote database or copy your current database to the remote service.

To set up the database from scratch:

sudo helpy run rake db:setup

To remove Postgres from your initial server:

sudo apt-get --purge remove postgresql\*

Use an external filestore

The Helpy core stores all uploads and attachments in the application by default. This means if the app server is compromised or goes away, your attachment files and images will go away too. Further, your app server will run out of disk space at some point.

Using an external file store like AWS S3 is much preferred and provides instant durability by automatically backing up your files to the cloud. Starting with version 2.3, Helpy has built in support for configuring an external file store with environment variables. Any S3 compatible file storage can be used by setting the following environment vars.

sudo helpy config:set REMOTE_STORAGE=true
sudo helpy config:set S3_KEY=your-key
sudo helpy config:set S3_SECRET=your-secret
sudo helpy config:set S3_REGION=your-region
sudo helpy config:set S3_ENDPOINT=your-end-point
sudo helpy config:set S3_BUCKET_NAME=your-bucket-name

If you are using S3, please refer to https://docs.aws.amazon.com/general/latest/gr/rande.html to lookup the region name shorthand and endpoint URL for the region of your S3 bucket.  For other providers, consult their documentation.

Important- as with all configuration changes, make sure you restart Helpy for the changes to take effect.

sudo helpy restart

Helpful command line tools

Reset the master admin password:

sudo helpy run rake admin:set_password password=

Every setting in Helpy Pro can be configured by using environment variables, making it possible to set some variables in a way that users of the system will not be able to modify.

BRANDING_TICKETING_COLOR = "#245566"
BRANDING_TICKETING_BG_COLOR = "#F6F7E8"
BRANDING_TICKETING_BG_IMAGE = ""
BRANDING_DISPLAY_BRANDING = "1"
SETTINGS_ENFORCE_SSL = "0"
SETTINGS_PARENT_SITE = SETTINGS_PARENT_SITE
SETTINGS_PARENT_COMPANY = SETTINGS_PARENT_COMPANY
SETTINGS_SITE_URL = SETTINGS_SITE_URL
SETTINGS_SITE_NAME = SETTINGS_SITE_NAME
SETTINGS_SITE_TAGLINE = SETTINGS_SITE_TAGLINE
SETTINGS_PRODUCT_NAME = SETTINGS_PRODUCT_NAME
SETTINGS_SUPPORT_PHONE = SETTINGS_SUPPORT_PHONE
SETTINGS_GOOGLE_ANALYTICS_ID = SETTINGS_GOOGLE_ANALYTICS_ID
SETTINGS_GOOGLE_ANALYTICS_ENABLED = '0'
SETTINGS_RECAPTCHA_SITE_KEY = SETTINGS_RECAPTCHA_SITE_KEY
SETTINGS_RECAPTCHA_API_KEY = SETTINGS_RECAPTCHA_API_KEY
SETTINGS_RECAPTCHA_ENABLED = '0'
SETTINGS_FORUMS = SETTINGS_FORUMS
SETTINGS_TICKETS = SETTINGS_TICKETS
SETTINGS_KNOWLEDGEBASE = SETTINGS_KNOWLEDGEBASE
SETTINGS_TEAMS = SETTINGS_TEAMS
SETTINGS_WELCOME_EMAIL = SETTINGS_WELCOME_EMAIL
SETTINGS_GLOBAL_BCC'] = []
SETTINGS_DEFAULT_CHANNEL'] = 'EMAIL'
SETTINGS_INCLUDE_TICKET_HISTORY'] = '1'
SETTINGS_INCLUDE_TICKET_BODY'] = '1'
SETTINGS_DEFAULT_PRIVATE'] = '0'
SETTINGS_ANONYMOUS_ACCESS'] = '0'
SETTINGS_ANONYMOUS_SALT'] = 'SALT'
# WEBHOOK INTEGRATIONS
WEBHOOK_FORM_ENABLED = "0"
WEBHOOK_FORM_KEY = ""
# DESIGN: (COLORS ETC.)
DESIGN_FAVICON = SETTINGS_APP_FAVICON
DESIGN_HEADER_LOGO = SETTINGS_APP_MINI_LOGO
# NOTE: THE CONTRIBUTER ACCIDENTALLY REVERSED THESE IN THE CODE
DESIGN_FOOTER_MINI_LOGO = SETTINGS_APP_LARGE_LOGO
DESIGN_CSS = ""
DESIGN_HEADER_JS = ""
DESIGN_FOOTER_JS = ""
CSS_SEARCH_BACKGROUND = ""
CSS_TOP_BAR = ""
CSS_LINK_COLOR = ""
CSS_FORM_BACKGROUND = ""
CSS_STILL_NEED_HELP = ""
CSS_MAIN_COLOR = ""
CSS_ACCENT_COLOR = ""
CSS_FORM_COLOR = ""
# THEME:
THEME_ACTIVE = "SINGULAR"
# I18N:
I18N_DEFAULT_LOCALE = "EN"
I18N_AVAILABLE_LOCALES = ["EN","ES","FR","DE","FI
# WIDGET:
WIDGET_SHOW_ON_SUPPORT_SITE = "TRUE"
WIDGET_SHOW_ON_SUPPORT_SITE = "TRUE"
WIDGET_CSS_STYLES = ""
WIDGET_BACKGROUND_COLOR = ""
WIDGET_BUTTON_COLOR = ""
WIDGET_BUTTON_TEXT_COLOR = ""
# EMAIL SPECIFIC:
EMAIL_ADMIN_EMAIL = SETTINGS_ADMIN_EMAIL
EMAIL_FROM_EMAIL = SETTINGS_FROM_EMAIL
EMAIL_SEND_EMAIL = SETTINGS_SEND_EMAIL
EMAIL_MAIL_SERVICE = SETTINGS_MAIL_SERVICE
EMAIL_SMTP_MAIL_USERNAME = SETTINGS_SMTP_MAIL_USERNAME
EMAIL_SMTP_MAIL_PASSWORD = SETTINGS_SMTP_MAIL_PASSWORD
EMAIL_MAIL_SMTP = SETTINGS_MAIL_SMTP
EMAIL_MAIL_PORT = SETTINGS_MAIL_PORT
EMAIL_MAIL_DOMAIN= SETTINGS_MAIL_DOMAIN
EMAIL_SPAM_ASSASSIN_REJECT= 4
EMAIL_SPAM_ASSASSIN_FILTER= 2
# NOTIFICATIONS
NOTIFY_ON_PRIVATE = "1"
NOTIFY_ON_PUBLIC = "1"
NOTIFY_ON_REPLY = "1"
# CLOUDINARY:
CLOUDINARY_ENABLED'] = '0'
CLOUDINARY_CLOUD_NAME'] = ''
CLOUDINARY_API_KEY'] = ''
CLOUDINARY_API_SECRET'] = ''