Deploying your Volunteer Portal

• Getting started
  • Create a Heroku account
  • Decide on your Volunteer Portal’s name and URL
  • Set up user authorization
• Deploying your first Volunteer portal
• Configuring optional features
  • Rollbar
  • Zendesk Web Widget
• Redeploying your portal

Getting started

Create a Heroku account

If you already have a Heroku account, you can skip directly to Deploying your first Volunteer Portal.

1. Go to the Heroku website
2. Click sign up and follow the on screen steps
3. Make sure your account is verified by following up with the verification email

Decide on your Volunteer Portal’s name and URL

You’ll need them in the steps to come. The portal’s name should be concise and descriptive. For the URL there are two major options.

1. Use Heroku’s automatically generated URL.

It will look like this: [name of your app].herokuapp.com. While this is convenient and easy, it needs to be unique among other Heroku apps and it may not be the easiest for your volunteers to remember.

1. Use a custom domain name.

You can connect any custom domain name you own to your Heroku deployment. We’ll go over how to link the two later in the setup, but make sure you know what it is!

Set up User Authorization

Volunteer Portal currently supports two forms of user authentication: Google Oauth and SAML. Choose whichever one makes most sense for you, and follow the instructions below to get started. If you have requests for more authentication methods, feel free to let us know by joining our Slack channel (the link is in our main README), or follow our developer documentation to add it yourself!

Set up Google OAuth

Follow Google’s Setting up OAuth 2.0 page documentation through the process of configuring a Google OAuth account. Please keep the following things in mind:

• Make sure you have an account that has permissions to create projects. You may need to create a new google account. Make sure you’re logged in as this account the whole process.
• Your Application type should be “Web Application”
• Under the “Authorized redirect URIs” list your Volunteer Portal’s URL with the appended /auth/google_oauth2/callback.
  • Ex. If your URL is https://volunteer_portal.herokuapp.com, you would list https://volunteer_portal.herokuapp.com/auth/google_oauth2/callback.
• If you have a custom domain name, also list it under “Authorized redirect URIs” with /auth/google_oauth2/callback appended.
• Keep your Client ID and Client secret handy. You’ll need them later.

Once you have setup your OAuth application, you will need to enable the Google+ API. We use this additional API to get some extra user information like their language.

Set up SAML Auth

SAML authentication can be provided through a number of third party services. We won’t go into the details of fully provisioning a SAML provider, but if you have one you’ll need the following information for later:

• Saml Issuer
• IDP SSO Target URL
• IDP Certificate

In your SAML application configuration, you will also need to set up your Single sign on URL. The URL will be the URL for your Volunteer Portal appended with /auth/saml/callback.

• Ex. If your URL is https://volunteer_portal.herokuapp.com, you would list https://volunteer_portal.herokuapp.com/auth/saml/callback.

SAML authentication allows you to sync additional metadata from your Identity Provider to your Volunteer Portal. In order to function, the portal requires attribute statements for first_name, last_name, and email. Any additional fields passed along will be stored in each user’s metadata field for your use in reporting.

Generate a secure encryption key

Some user information that gets saved will be encrypted before being added to the database. To do this, you need to generate a 32-byte secure key and keep track of it. If you ever change this key, those encrypted user properties will become inaccessible without the original key. Here is a quick way to generate a key using ruby:

ruby -rsecurerandom -e 'puts SecureRandom.hex(16)'

Deploying your first Volunteer Portal

1. Click the Deploy to Heroku button above.

2. Fill out the form. The following inputs are required:

   • application name - you should have chosen above
   • ATTR_ENCRYPTION_KEY - the secure key generated above
   • HOST - the absolute URL using the name you chose or custom domain, for example: https://volunteer_portal.herokuapp.com
3. Depending on which user authentication method you chose above, you will need your auth secrets.

4. For Google Auth

   • GOOGLE_CLIENT_ID - acquired above during google oauth setup
   • GOOGLE_CLIENT_SECRET - acquired above during google oauth setup

5. For SAML Auth

   • SAML_ISSUER - acquired above during SAML auth setup
   • SAML_IDP_SSO_TARGET_URL - acquired above during SAML auth setup
   • SAML_IDP_CERT- acquired above during SAML auth setup
6. Click Deploy app!

Configuring optional features

Rollbar

Rollbar provides real-time error alerting and debugging tools for web applications. If you’d like to setup this for your hosted application you can put in your Rollbar URL and Access token in the fields provided. Read more about it on Rollbar’s website here.

Zendesk Web Widget

Zendesk’s Web Widget is embedded at the bottom of pages in case your volunteers need help. If you have a Zendesk account, simply input your domain ZENDESK_DOMAIN field and the widget will appear. For more about the web widget, read the Zendesk Web Widget documentation here.

Redeploying your Portal

If you’ve made any updates to your Volunteer Portal following our Development documentation, you’ll want to redeploy your Portal so it reflects the changes you’ve made.

The easiest way to see your changes is to deploy using git. The following instructions are cherry-picked from the official Heroku documentation, so feel free to browse them directly for more in depth instructions or troubleshooting.

1. The first step is to download the Heroku CLI. Follow the instructions for installation for the appropriate platform.
2. Log in to with the Heroku CLI by running heroku login.
3. Find your app name, and make sure your shell’s current directory is in your portal with your desired changes on a git branch.
4. Add your Heroku app to git’s remote origin by running heroku git:remote -a [APP NAME HERE].
5. Deploy the changes with git push heroku [BRANCH NAME].
6. If everything worked you should see your changes live!