Installing your own Helpy Pro Private Cloud or On-Premises instance

BETA Documentation: 

This documentation is currently in BETA and may be incomplete, incorrect or subject to change.  Please contact Helpy if something is not working quite right.

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


Installation: Connect and setup the database


To configure your external postgresql database, 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.

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 will either need to create the database with

sudo helpy run rake db:create

or by using the web GUI from the DBAAS provider.


Once you have created the database, set up the database 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 Nginx and restart Helpy:

sudo service nginx start
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



Did this solve your problem?