The Raygun APM Agent can be installed into an AWS Elastic Beanstalk environment using .ebextensions.

Note these instructions are tailored to a web server environment using the Node.js (Amazon Linux 2) preconfigured platform.

Installing the Raygun Agent

1. Add the extension

Add the following configuration file to your web application's source code to install the Raygun APM Agent service.

Save the following as .ebextensions/raygun-apm.config and add it to the root of your application zip file uploaded to AWS.

option_settings:
  aws:elasticbeanstalk:application:environment:
    Raygun_DefaultApiKey: <YOUR API KEY>

files:
  "/tmp/prep_agent_installation.sh" :
    mode: "000755"
    owner: root
    group: root
    content: |
      #! /bin/bash
      yum -y install unzip
      if curl -LOf "https://downloads.raygun.com/APM/latest/RaygunAgent-Linux-(x64).zip"; then
        unzip -d /agent -o "RaygunAgent-Linux-(x64).zip"
        rm "RaygunAgent-Linux-(x64).zip"

        mkdir -p /usr/share/Raygun
        mkdir -p /var/raygun

        chown -R webapp:webapp /usr/share/Raygun
        chown -R webapp:webapp /var/raygun

        chmod +x /agent/RaygunAgent
        chmod +x /agent/rgc
      else
        echo "Curl was unable to download RaygunAgent-Linux-(x64).zip. Exiting."
        exit 1
      fi      

commands:
  00_prep_for_agent_install:
    command: "sh /tmp/prep_agent_installation.sh"
    ignoreErrors: false

2. Configure the Procfile to run the agent

If your project does not already have a Procfile, create one in your application's root directory with the following contents:

web: npm start
agent: /agent/RaygunAgent

If your project has an existing Procfile already, add agent: /agent/RaygunAgent to the end of the Procfile.

3. Configure npm to allow building native extensions on Amazon Linux

Some tiers of AWS's Amazon Linux VMs are not correctly configured for building or installing native Node extensions out of the box. This can cause errors when attempting to install raygun-apm, as it relies on several native extensions to enable access to the v8 profiler and to manage memory mappings.

If you encounter issues building or installing these native dependencies, create an .npmrc in your project's root with the following contents:

unsafe-perm=true

Additionally, the node_modules/ directory must be included in your application's .gitignore or .ebignore file, as otherwise Elastic Beanstalk will fail to install binaries for raygun-apm's native dependencies.

4. Deploy your application

Open the Elastic Beanstalk console, upload your new application version with the embedded raygun-apm.config file and deploy it to your environment.

Read more on deploying your application in the AWS Elastic Beanstalk developer guide.

For more information on raygun-apm, please visit the module documentation on npm.