Install using CloudFormation

Install clustered On-premise version of BugSnag using CloudFormation.

Before installation

To get started with your BugSnag On-premise installation, you’ll need the following things prepared in advance:

  • If this is your first time installing BugSnag On-premise, you’ll need to contact us to schedule a guided installation. We’ll get you set up with a license, and walk you through the installation process.
  • SMTP credentials are required for installation. These are used to invite collaborators and receive error notification emails.
  • AWS SSH key pair
  • IAM role for CloudFormation and a Lambda function to assume; the role will need a managed policy described here
  • A Route 53 hosted zone (if you want the template to create DNS records with given names for load balancers)
  • SSL/TLS certificates in AWS ACM (for load balancers)

Installation

Installation can be done either through the CloudFormation UI or through the AWS CLI, see below for more information.

Installation will take some time to apply, usually around 20-25 minutes as this sets up a Kubernetes cluster, nodes, load balancers, ECR repositories, and an EC2 instance. so everything is ready for running BugSnag.

Installing using CloudFormation UI

Apply the CloudFormation template through the AWS console using the following template URL:

https://s3.amazonaws.com/bugsnag-onprem-public/cloudformation/latest/bugsnag-onprem-eks.yaml

and enter the parameters listed on the page.

Installing using AWS cli

Run the following:

aws cloudformation create-stack \
  --stack-name bugsnag-onprem \
  --capabilities CAPABILITY_IAM \
  --template-url https://bugsnag-onprem-public.s3.amazonaws.com/cloudformation/latest/bugsnag-onprem-eks.yaml \
  --role-arn arn:aws:iam::90000:role/bugsnag-onprem-execution-role \
  --parameters \
    ParameterKey=ExecutionRole,ParameterValue=arn:aws:iam::90000:role/bugsnag-onprem-execution-role \
    ParameterKey=ClusterName,ParameterValue=bugsnag-onprem-1 \
    ParameterKey=NodeImageId,ParameterValue=ami-1234567890abcdef1 \
    ParameterKey=KeyName,ParameterValue=bugsnag-onprem-key \
    ParameterKey=HostedZoneId,ParameterValue=ABC123DEF456 \
    ParameterKey=EventServerHostname,ParameterValue=bugsnag-notify.example.com \
    ParameterKey=EventServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=GrafanaHostname,ParameterValue=bugsnag-grafana.example.com \
    ParameterKey=GrafanaCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=HooksServerHostname,ParameterValue=bugsnag-hooks.example.com \
    ParameterKey=HooksServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=DashboardHostname,ParameterValue=bugsnag-dashboard.example.com \
    ParameterKey=DashboardCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=ReleaseServerHostname,ParameterValue=bugsnag-build.example.com \
    ParameterKey=ReleaseServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=SessionServerHostname,ParameterValue=bugsnag-sessions.example.com \
    ParameterKey=SessionServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=UploadServerHostname,ParameterValue=bugsnag-upload.example.com \
    ParameterKey=UploadServerCertificateArn,ParameterValue=arn:aws:acm:us-west-1:90000:certificate/00000000-cccc-5555-9999-dddddddddddd \
    ParameterKey=ConfigServerSecurityGroup,ParameterValue=sg-12ab34cd \
    ParameterKey=ConfigServerSubnetID,ParameterValue=subnet-12ab34cd \
    ParameterKey=ConfigServerKeyName,ParameterValue=config-server-key \
    ParameterKey=ConfigServerImageId,ParameterValue=ami-1234567890abcdef1 \
    ParameterKey=ECRRepositoryNamespace,ParameterValue=namespace

For NodeImageId, see https://docs.aws.amazon.com/eks/latest/userguide/eks-optimized-ami.html for more information about the AMI to use.

For ConfigServerImageId see https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html for more information about the AMI to use.

Initialize BugSnag

Once the stack has finished creating, the template will create a dedicated Config Server for managing installations and upgrades that has all the tools required for getting BugSnag setup. Connect to that instance for the next steps.

Before you can initialize BugSnag, you will need to do the following steps.

First you will need to configure the AWS CLI to have access to the ECR repository and EKS Kubernetes cluster, you can do this by running:

aws configure

You will also need to configure kubectl to have the correct config to interact with the Kubernetes cluster, this can be done by running:

aws eks --region region update-kubeconfig --name cluster_name --role-arn role_arn

The cluster name and role ARN (execution role ARN in the template) is something you specified in the template.

To get the credentials required by the installer for pushing the images to your ECR docker registry, you should also run

aws ecr get-login-password

Install Replicated KOTS kubectl plugin

Run the install script to download and install the Replicated KOTS kubectl plugin.

curl https://kots.io/install | bash

Install BugSnag On-premise

Install Replicated KOTS admin console

kubectl kots install bugsnag-clustered-kots/stable \
  --name Bugsnag \
  --namespace bugsnag

See install reference for all of the options available for the install command.

You can change the namespace you wish to install Replicated KOTS to, however ensure that the namespace matches the namespace in the configuration for BugSnag.

You will be asked to create a password for accessing the admin console.

After installation, the Replicated admin console will be available at http://localhost:8800.

Upload license

In the Replicated admin console you will be prompted for the password you created in the previous step. You can then upload your BugSnag On-premise license key you received from BugSnag to continue to the next step.

BugSnag configuration

You will then be presented with the settings page from which you can configure your BugSnag installation. When configuring the registry you can use the registry set up by the CloudFormation template; the registry address will be an output of the CloudFormation stack.

Preflight checks

Finally you will be shown the preflight check page, where the system will be analyzed to determine whether the environment meets the minimum requirements. These checks are done to ensure that your installation is successful.

Once complete BugSnag will be deployed to the cluster. It can take several minutes for BugSnag On-premise to fully start up; when it is ready the admin console will indicate that it is Ready.

Account & project creation

Now BugSnag is running, you should be able to access the BugSnag dashboard, where you’ll need to create your account and first project.

Visit your BugSnag dashboard in a web browser (available by default at the address you specified in the CloudFormation template) to set up your account and create projects for each of the applications you wish to monitor.

Notifier configuration

Once you have created your account and first project you will need to configure your applications to send errors and sessions information to your BugSnag instance instead of notify.bugsnag.com and sessions.bugsnag.com respectively. Follow the instructions on configuring platform notifiers for how to do this.