Skip to content

Latest commit

 

History

History
69 lines (40 loc) · 4.25 KB

Runbook.md

File metadata and controls

69 lines (40 loc) · 4.25 KB
Raw

System Overview

The Vonage API Developer Portal is a simple Rails application with a mounted Sinatra app that handles the rendering of the API References.

Deployment

ADP is hosted in Heroku and is automatically deployed every time a branch is merged into master via a GitHub integration. In case you want to force a deploy, you can always deploy ADP from Heroku's dashboard.

Required Resources

  • Heroku Redis: Used for caching view fragments and resources, its configuration can be found in production.rb.
  • Heroku Scheduler: Runs a scheduled job everyday at 5pm that refreshes Algolia's indexes.
  • Heroku Postgres: SQL Database service.
  • Algolia: In Production, the search form is enabled and it is powered by Algolia.

How to diagnose problems with ADP

Logs

We use Logz.io as a logging solution with a 3Gb daily volume and 3 days retention plan, as an alternative you can always check Heroku's logs which expire after one week.

Error Monitoring and Reporting

We use Bugsnag for monitoring errors both on the Backend and Frontend split into different Projects. Bear in mind that most of the errors are logged under Markdown#show so it might take a while to find a specific error.

Health checks

We use Pingdom to monitor ADP's health, and email notifications are sent when the site is Down/Up.

Caching

We currently cache the sidenav and the information we fetch from Greenhouse in order to render the careers page. The cache is cleared as part of the deploy process, so when facing a caching issue, just trigger a new deploy or run the following rake task in Heroku rake cache:clear.

Troubleshooting Production issues

In case ADP is Down:

  • Check if Heroku is having an outage. Unfortunately, if that is the case then there isn't much you can do about it (at least for now).
  • Otherwise, check the logs or Bugsnag to see if any issues show up and try to reproduce it locally. If the issue is related to the latest deploy, just revert the offending commits and the deploy again while you work on a fix. Once a fix is ready, open a Pull Request, make sure that it works in the corresponding Review App and finally after all the checks pass merge it into master.

Available configuration options

Configuration management

When running ADP locally, dotenv loads the corresponding environment variables from .env to ENV. However, when the app is deployed to Heroku the environment variables are set in Heroku's dashboard.

Enabling Search locally

To enable the Search form locally, the ALGOLIA_SEARCH_KEY environment variable needs to be set, the rest of the configuration is defined in config/algolia.yml

Common issues when running ADP locally

ADP can be run locally either directly or using Docker, for more information about how to run it see the Readme. When using docker, re-building the image should fix the following issues

  • Could not find definition '<insert_file_here>' in '<path>': set the right OAS_PATH in .env, check .env.example for the default value.

  • Error connecting to Redis on localhost:6379: you are seeing this error because the REDIS_URL env variable is set and the app couldn't connect to it. Make sure redis is up and running and re-start the app server.

  • Migration errors: run bundle exec rake db:migrate

  • While running bundle install:

    • ruby version '<version>' is not installed: try running rbenv install <version> && gem install bundler followed by bundle install

  • Webpacker errors:

    • The engine "node" is incompatible with this module. Expected version... We use nvm as node's version manage, check that the right version of node is installed (specified in .nvmrc) and run nvm use <version>.
    • Make sure that all the packages are installed by running yarn install