Installation guide

Install clustered On-premise version of BugSnag.

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.
• A Kubernetes cluster running at least version 1.19 and at most version 1.24
• kubectl command line tool
• Docker registry
• SMTP credentials are required for installation. These are used to invite collaborators and receive error notification emails.

Installation

BugSnag On-premise uses Replicated KOTS to perform and manage installations.

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

Download BugSnag airgap package

BugSnag will have provided you with a URL to download the offline installation package. You should download this and ensure the filename ends in .airgap.

curl -sSL -o bugsnag.airgap "<URL provided>"

Push Replicated KOTS admin console images to registry

1. Get KOTS plugin version

kubectl kots version

1. Download kotsadm.tar.gz from the kots release page on GitHub. See Releases in the kots GitHub repository. Ensure that the version matches the KOTS plugin version from step 1.

2. Push KOTS admin console images to your registry:

kubectl kots admin-console push-images ./kotsadm.tar.gz REGISTRY_ADDRESS \
  --registry-username RW_USERNAME \
  --registry-password RW_PASSWORD

Where:

• REGISTRY_ADDRESS is the address of the private image registry including the namespace for images to be pushed to.
• RW_USERNAME is the username for an account that has read and write access to the private image registry.
• RW_PASSWORD is the password for the account with read and write access.

Install Replicated KOTS admin console

kubectl kots install bugsnag-clustered-kots/stable \
  --name Bugsnag \
  --namespace bugsnag \
  --kotsadm-registry REGISTRY_ADDRESS \
  --registry-username RO_USERNAME \
  --registry-password RO_PASSWORD

Where:

• REGISTRY_ADDRESS is the address of the private image registry including the namespace.
• RO_USERNAME is the username for an account that has read-only access to the private image registry.
• RO_PASSWORD is the password for the account with read-only access.

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 the BugSnag On-premise license key you received from BugSnag to continue to the next step.

Upload airgap package

On the next step you can upload the BugSnag airgap package previously downloaded. This may take some time due to the size of the airgap package.

BugSnag configuration

Once the airgap package has been uploaded you will then be presented with the settings page. Here you can configure your BugSnag installation.

Preflight checks

You will then be presented with 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 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 error and session 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.