Airgapped installation guide

Install BugSnag On-premise on a high availability cluster in an airgapped environment.

Before installation

To get started with your BugSnag On-premise installation, you’ll need the following 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.23 and at most version 1.29
  • kubectl command line tool
  • Docker registry
  • SMTP credentials are required for installation. These are used to invite collaborators and receive error notification emails.

If you are installing BugSnag On-premise on AWS you can follow our guide to provision AWS resources with CloudFormation which will provide an EKS kubernetes cluster, ECR docker registry, config server with management tooling installed and load balancers to access the BugSnag dashboard.

Install Replicated KOTS

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

  1. Download KOTS installation packages

    BugSnag will have provided you with a URL to download the offline installation packages. Download v1.109.3 of the following packages:

    • KOTS CLI (kots_linux_amd64.tar.gz)
    • KOTS Admin Console Bundle (kotsadm.tar.gz)
  2. Install Replicated KOTS CLI

    The Replicated KOTS CLI is a kubectl plugin that runs locally on the machine you will use to manage the cluster.

    Extract the installation package and move the plugin to a location in your path:

    tar xvf kots_linux_amd64.tar.gz
    sudo mv kots /usr/local/bin/kubectl-kots
    
  3. Push Replicated KOTS admin console images to registry

    Push KOTS admin console images to your registry:

    kubectl kots admin-console push-images ./kotsadm.tar.gz \
      "<REGISTRY_ADDRESS>" \
      --namespace bugsnag \
      --registry-username "<RW_USERNAME>" \
      --registry-password "<RW_PASSWORD>"
    
    Placeholder Description
    <REGISTRY_ADDRESS> Address of the private image registry including the namespace
    <RW_USERNAME> Username for an account that has read and write access to the private image registry
    <RW_PASSWORD> Password for the account with read and write access
  4. Install Replicated KOTS admin console

    The Replicated KOTS admin console provides a user interface for installing and managing BugSnag On-premise in your kubernetes cluster. Install the admin console by running the following command:

    kubectl kots install bugsnag-clustered-kots \
      --name Bugsnag \
      --namespace bugsnag \
      --kotsadm-registry "<REGISTRY_ADDRESS>" \
      --registry-username "<RO_USERNAME>" \
      --registry-password "<RO_PASSWORD>"
    
    Placeholder Description
    <REGISTRY_ADDRESS> Address of the private image registry including the namespace
    <RO_USERNAME> Username for an account that has read-only access to the private image registry
    <RO_USERNAME> Password for the account with read-only access

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

    You can change the namespace you wish to install Replicated KOTS to, however it must match the namespace you later provide in the BugSnag configuration.

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

  5. View KOTS admin console

    After installation, the Replicated KOTS admin console is available at http://localhost:8800.

    If you are disconnected you can re-establish the port forward:

    kubectl kots admin-console --namespace bugsnag
    

Install BugSnag

  1. Upload license

    In the Replicated KOTS admin console upload the BugSnag On-premise license file you received from BugSnag.

  2. Upload airgap package

    BugSnag will have provided you with a URL to download the offline installation package:

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

    Ensure the filename ends in .airgap and upload it to the admin console. This may take some time due to the size of the airgap package.

  3. BugSnag configuration

    You will be presented with the config page from which you can configure your BugSnag installation.

  4. Preflight checks

    Finally, you will be shown the preflight checks 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.

  5. Installation complete

    It can take several minutes for BugSnag On-premise to deploy and fully start up. Once complete the admin console will indicate that it is ‘Ready’.

Account & project creation

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 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.

Similarly, you will also need to configure your applications to send performance trace/span data to your BugSnag instance instead of otlp.bugsnag.com/v1/traces/. Follow our performance integration guides to get started.