Congratulations on creating your new one-click image.  This document will serve to guide you through some initial setup steps and provide assistance with some common tasks.  In this article, you will learn:

• Introduction to the Marketplace Image
• Essential first steps to complete immediately
• Ongoing maintenance of the image and Helpy
• Advanced configuration
• How to buy and install Helpy Cloud to superpower your instance
  
  

Note: Helpy is available from several Cloud providers, and there may be slight variations in terminology or functionality to comply with the requirements the individual provider.

Introduction to the Marketplace Image

The marketplace image is a 30 second install of a complete VM running the latest version of either the Helpy open source edition or cloud edition.  The open source edition can easily upgrade to a full cloud private instance (covered below.)

The image runs the following software:

- Helpy (recent version) open source edition
- Postgres 10
- RVM with Ruby (recent stable version)
- Nginx and Passenger

The image includes a startup user which varies by provider (root for DigitalOcean, ubuntu for AWS and your username for Google Cloud Platform) and is how you access the instance the first time you log in. Another user,  'deploy' is used to run ruby, nginx and how you should access the server under normal circumstances.

The following are some general guidelines on instance size:

1gb - Testing only.  Not for production use, you will run into memory issues.
2gb - Suitable for a small helpdesk with a couple hundred issues per month.
4gb - Good for Helpy Cloud version and up to 1000 tickets per month.
8gb - Suitable for a larger installation.
16gb - Suitable for 1000s of tickets per month.

HA Cluster - You've hit the big time and can't afford downtime.  Cluster multiple servers and do rolling updates with Capistrano.

What to do immediately

The first things you do will help to further secure your image and provide for future access.

1. Copy your SSH key to the deploy user.

Logging in and doing operations as the root user is not a good idea.  Instead, the image includes the user 'deploy' with sudo privileges which is what you should use to log in and administer the server.

This tutorial assumes that you added a SSH public key to your instance when you creating it.  If you didn't, use this guide to get setup: https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-1804  

Now log in as the start up user with:

ssh root@your.ip.address # DigitalOcean

ssh ubuntu@your.ip.address # AWS

ssh <your user>@your.ip.address # GCP

Then, copy your SSH key to deploy so that you will be able to connect as deploy in the future:

sudo rsync --archive --chown=deploy:deploy ~/.ssh /home/deploy

Open a new terminal and type the following to verify that you can SSH as the deploy user before proceeding:

ssh deploy@your.ip.address

Worked?  Now close your original window (where you logged in as root) and proceed with the deploy user from now on.

2. Lock down root login

Disabling root logins is a standard security practice and can be done by editing the /etc/ssh/sshd_config file.  Open this file with nano sshd_config and then changing the line "PermitRootLogin" to "no."  When you log out, you will no longer be able to log into the server as root.

3. Add some swap space

Adding swap space is a good idea to help prevent your droplet from running out of memory.  This is particularly useful when updating or if your Helpy gets busy suddenly.  To add some swap space, issue the following commands:

sudo dd if=/dev/zero of=/swap bs=1M count=1024
sudo mkswap /swap 
sudo swapon /swap

4. Update server packages and reboot

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade
sudo reboot

Regular Server maintenance

The following steps will help you keep the server image and Helpy itself up to date.  Keeping both up to date will ensure you have the latest features and patch any security flaws.  Note: It is assumed you are logged in as 'deploy' when completing the next steps.

1. Update packages

You should establish a weekly or monthly routine to install any updates to the underlying packages used by your droplet.

sudo apt-get update
sudo apt-get upgrade
sudo apt-get dist-upgrade

2. Update Helpy

Updating Helpy is pretty easy if you have not made any changes to the underlying software.  First, switch to the Helpy directory and using git, pull the latest changes:

cd ~/helpy
git pull

Update your bundled gems with:

bundle install

Next you need to run any new database migrations and update the assets:

RAILS_ENV=production bundle exec rake db:migrate
RAILS_ENV=production bundle exec rake assets:precompile

Finally restart the webserver

sudo service nginx restart

This process is simple enough but not automated and also somewhat error prone.  To do these updates in a more automated way, it is recommended to use a tool like Capistrano to script many of the steps.

Advanced Configuration

In this section we will take a look at setting up IMAP or POP3 integration, or using an S3 compatible file server like DigitalOcean Spaces or Amazon AWS S3.

Configuring IMAP Email

Helpy can either receive email through a gateway like Sendgrid, Mandril or Postmark, or via IMAP or POP3 by periodically fetching any new messages.  First, add the correct server configuration in the settings control panel.  When complete, it should look something like the following:

The mail fetch needs to run a process to periodically check your IMAP or POP3 for new messages.  Run the following script to start this:

RAILS_ENV=production nohup bundle exec /home/deploy/.rvm/gems/ruby-2.4.5/bin/rake helpy:mailman mail_interval=60 > rake.out 2>&1 &

Next, you will need to add a cron job to periodically fetch new messages from your mail server.  Once you have added the correct server configs, log in to the server as the deploy user and set up the following cronjob.

First load the crontab in an editor with:

crontab -e

Cut and paste the following, doing any editing you need to:

0,5,10,15,20,25,30,35,40,45,50,55 * * * * /bin/bash -l -c 'cd /home/deploy/helpy && RAILS_ENV=production bundle exec rake helpy:mailman --silent'

Once live, the Helpy script will automatically pull any new messages from your IMAP server for you, every few minutes.

Note: Getting this working with gmail takes some extra steps.  You may have to allow less secure apps access in your account settings, and even still Google will likely block your initial attempts at sending.  After a few minutes you will receive a message "Critical security alert".  Once you authorize that you were blocked from logging in, everything should start working.

Using an external file store

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 prefered and provides instant durability by automatically backing up your files to the cloud. Helpy has built in support for configuring an external file store with environment variables. Any S3 compatible file storage can be used by setting environment vars.

Note: To use Amazon S3, you will need to use an IAM role and grant access to the S3 bucket of your choice. Then create and access key and secret to use below.  See https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

Your Helpy instance sets environment variables through the Nginx host file.  Start out by opening this and then modify it to uncomment the passenger_env_var lines:

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

then change the env vars here:

server {    
    listen 80;    
    server_name yourserver.com;    

    # Tell Nginx and Passenger where your app's 'public' directory is    
    root /home/deploy/helpy/public;    

    # Turn on Passenger    
    passenger_enabled on;    
    passenger_ruby /home/deploy/.rvm/gems/ruby-2.4.5@helpy/wrappers/ruby;

    # Configure ENV vars to turn on remote filestore (optional)    
    # REQUIRES HELPY 2.3+ 
   
    #passenger_env_var REMOTE_STORAGE true;    
    #passenger_env_var S3_KEY change_key;    
    #passenger_env_var S3_SECRET change_secret;    
    #passenger_env_var S3_REGION change_region;    
    #passenger_env_var S3_ENDPOINT change_endpoint;    
    #passenger_env_var S3_BUCKET_NAME change_bucket_name;
}

Make sure you restart nginx after making any changes.

Configuring SSH with Letsencrypt Certbot

Setting up Letsencrypt will allow you to easily install a SSL cert for your Helpy site.  First, make sure you have LetsEncrypt installed:

sudo apt-get update
sudo add-apt-repository ppa:certbot/certbot
sudo apt install python-certbot-nginx

Next run the certbot to fetch your SSL cert for your domain name

sudo certbot --nginx -d example.com

Proceed through the dialogues and when you are done, restart nginx and confirm you are able to connect via SSH!