Overview:

Helpy Pro makes it possible to run a single instance of Helpy on your own Private Cloud or On-Premises server.  Installation is simple and quick using the apt package manager to install and update the software.

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

• Requirements
• Installation
  • Installing the Package
  • Important Configurations
  • Use an external database
  • Use an external filestore
  • Install and configure Nginx
• Updating Helpy
  
  
  

Requirements

Helpy Pro currently only runs on Ubuntu 18.04. You should use a VM or bare metal server with this OS.

Other requirements are:

• Minimum of 2GB of RAM
• Postgres 10x- best to use a DBAAS or a dedicated server
• SMTP and IMAP or Sendgrid for email
• AWS S3 or compatible for File Storage (optional)
• For high availability you will need a load balancer and multiple VMs (optional)
  
  

Installing the Package

Helpy Pro is distributed as an APT package.  Optionally it can be run in a clustered mode, with load balancer and 2 or more app servers, a database backend (one or more db servers), and optionally one or more worker servers, and an external file store.

To install the Helpy Pro package, you will first need to add the APT repository, then install the package itself. To get started, use your preferred text editor to create the following file:

/etc/apt/sources.list.d/helpy.list

Adding the following line:

deb [trusted=yes] https://s3.amazonaws.com/helpypro-releases stable main

Next, update the system and install:

sudo apt-get update
sudo apt-get install -y helpy

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

sudo helpy

Start the Helpy service as a daemon using:

sudo helpy scale web=1 worker=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 PORT=6100 #port to listen to.  Helpy automatically reduces this by 100
sudo helpy config:set PWK_RAM=2048 # RAM available in VM
sudo helpy config:set PUMA_CONCURRENCY=4 # number of workers
sudo helpy config:set PUMA_THREADS=1 # number of threads per worker

For larger installations, it may be a good idea to run one or more dedicated job servers. To do this, you can combine commands like this:

sudo helpy scale web=0 worker=1

Create a local database for testing

Helpy Pro uses the PostgreSQL database, and you will need either a local DB server (good for testing) or a dedicated instance or DBAAS (best for production).  To set up a local server, follow these steps:  

First, install the required packages:

sudo apt-get -y install postgresql postgresql-contrib

Next, create a database user, and set the password for the user.  Make note of the username and password if you change them.

sudo -u postgres createuser -s helpy
sudo -u postgres psql -U postgres -d postgres -c "alter user helpy with password 'helpy';"

 Create an empty Helpy database with the following.  We will script the table setup in a later step.

sudo -u postgres createdb helpy_production

Create and use a dedicated database or DBAAS (for production use)

A dedicated PostgreSQL instance or DBAAS is recommended for production use.  You will need the connection settings for the next step.  Some DBAAS services require you to create databases in their GUI.  If this is the case, create an empty database.  We'll script the table creation in the next step.

helpy_production

Connect and set up the database

To configure your PostgreSQL database connection, you will need to set a handful of environment variables on your app instance(s). 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.  Note: if you set up a local database with the default username and password, you can skip this configuration for now.

sudo helpy config:set HELPY_POSTGRES_DB=helpy_production
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 may need to create the empty database if you didn't in a previous step

sudo helpy run rake db:create

Once you have created the database, set up the database tables from scratch:

sudo helpy run rake db:setup

Installation: Connecting to the External Filestore (optional)

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

Install and Configure Nginx

Helpy uses the Nginx web server, and going live means that you will need to install and configure it.  Begin by making sure it is installed:

sudo apt-get install -y nginx

Then change the default host file:

sudo nano /etc/nginx/sites-available/default

Delete the existing configuration and then add something like the following.  This is a super basic configuration and you will probably want to add to this:

server {
  listen          80;
  server_name     example.com;
  location / {
    proxy_pass      http://localhost:6000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
}

You still need to tell the Helpy service to listen on this port. Use this command:

After making this change, start or restart Nginx and restart Helpy:

sudo service nginx start #or sudo service nginx restart
sudo helpy restart

Important: if you didn't start the Helpy service above, restarting will not work until you have already started it.

Last, point your web browser to the IP address or subdomain of the server.  After a few seconds, the Helpy Pro interface onboarding should load up!

Updating Helpy

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

sudo apt-get update
sudo apt-get -y upgrade

After updating, you should run database migrations using:

sudo helpy run rake db:migrate