On-premise legacy

Install, maintain, and manage your older on-premise version of BugSnag.

This page refers to BugSnag On-premise version 2.1711.2 and earlier. For the latest information please see BugSnag On-premise.

About On-premise

BugSnag On-premise offers a self-hosted version of BugSnag for organizations that need or want to manage their own data. It can be run in your existing PCI or HIPAA compliant environments.

BugSnag On-premise has most of the features of SaaS BugSnag and regular releases ensure you are kept up to date. All notifier libraries can easily be configured to send error reports to your BugSnag On-premise instance.

To find out more or discuss your requirements please contact enterprise@bugsnag.com.

Before installation

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

  • If this is your first time installing BugSnag, you’ll need to contact us to schedule a guided installation. We’ll get you set up with a license key, and walk you through the installation process.
  • A server with Docker 1.10+ and Docker compose 1.7+ installed and running. See the Linux installation guides for Docker and Docker compose for more details.
  • A data volume, typically mounted as /data, with at least 200GB of space. Ext4 or XFS filesystems are preferred.
  • SSD data volume is heavily recommended.
  • SMTP credentials are required for installation. These are used to invite collaborators and receive error notification emails.
  • DNS access to configure hostnames.

Volume-dependent specifications

Instances storing up to 100 million BugSnag events require a dual core CPU and 16GB of memory. If you are running on AWS we recommend an r4.large.

Instances storing more than 100 million BugSnag events require a quad core CPU with 32GB of memory. In AWS an r4.xlarge is recommended.

Installation

Confirm Docker is running

Confirm Docker is installed correctly and running on your machine. If successful, this command should report information about your running Docker instance.

sudo docker info

Download the installation script

Download the bugsnag installation and management script and install it into your PATH.

curl -L -O https://www.bugsnag.com/enterprise-v2/bugsnag
chmod +x bugsnag
sudo mv bugsnag /usr/bin

Install BugSnag

Downloading and installing BugSnag can take between 15-30 minutes.

sudo bugsnag install

During installation you’ll be prompted to select a data directory. This should be on a large volume (at least 200GB) with an Ext4 or XFS filesystem. This is the directory that will contain your BugSnag data, and will need to be backed up.

Installing offline

Installing BugSnag offline can be done by prefetching packages required for install on an internet connected machine.

sudo bugsnag prefetch

This outputs an archive in the current directory. This archive needs to be copied to a machine for offline install as well as the bugsnag installation script. The bugsnag installation script has to be installed before offline install can be run. See Download the installation script for how to do this.

The archive needs to be supplied when installing offline.

sudo bugsnag install --offline=/path/to/bugsnag-offline-archive.tar.gz

Non interactive install

Installing bugsnag without interaction during installation can be done by providing the following parameters to the bugsnag installation script:

sudo bugsnag install --accept-eula --license-file=/path/to/license_file --data-dir=/path/to/data/dir

--accept-eula If you are required to accept a EULA as part of your installation, supplying this option will bypass the prompt. Using this option implies that you have read and agree to the terms of the EULA.

--license-file parameter needs the location to the license key file

--data-dir parameter needs the location to store bugsnag data. A data volume, typically mounted as /data, with at least 200GB of space. Ext4 or XFS filesystems are preferred.

Set the following environment variables whilst running the install command to configure bugsnag non interactively:

See Configure your hostname for more information

BUGSNAG_WEBSITE_HOST

WEBHOOK_HOST

See Configure SMTP for more information

SMTP_ADDRESS

SMTP_PORT

SMTP_DOMAIN

SMTP_FROM

SMTP_USERNAME

SMTP_PASSWORD

SMTP_AUTHENTICATION

SMTP_TLS

SMTP_ENABLE_STARTTLS_AUTO

Other options

EVENT_SERVER_COUNT Scale the number of event servers. Increasing this count should give greater capacity and reliability when traffic is very high.

EVENT_WORKER_COUNT Scale the number of event workers. Increasing this count should allow the system to process events faster when traffic is very high.

BUGSNAG_HTTPS_REDIRECT See Configure HTTP to HTTPS redirection for more information.

Installing behind a proxy

Set the http_proxy environment variable whilst running the install command.

sudo http_proxy=http://example.com bugsnag install

Configuration

BugSnag is configured by editing /etc/bugsnag/env.sh. Changes will be applied when BugSnag is next restarted (by running sudo bugsnag restart).

Configure SMTP

In order to send notification emails when crashes occur, BugSnag needs to have SMTP access configured.

You’ll need to edit the SMTP settings in /etc/bugsnag/env.sh:

# The hostname of your SMTP server
SMTP_ADDRESS=smtpserver.internal.example.com

# The port of your SMTP server (default: 25)
SMTP_PORT=25

# Specify a valid HELO domain (a valid, resolvable domain name)
# See http://bit.ly/1kbCMCo for details
SMTP_DOMAIN=example.com

# Specify a sender address for BugSnag emails
SMTP_FROM=bugsnag@example.com

# If your mail server requires authentication, set the username here
SMTP_USERNAME=your-smtp-username

# If your mail server requires authentication, set the password here
SMTP_PASSWORD=your-smtp-password

# If your mail server requires authentication, you need to specify the
# authentication type here. This can be either plain, login or cram_md5.
SMTP_AUTHENTICATION=login

# This setting is only required for SMTP servers that require TLS only (e.g. Rackspace).
SMTP_TLS=true

Configure your hostname

BugSnag On-premise exposes various services, which you may wish to map to user-friendly hostnames and ports. See Services, hostnames & ports for more information.

Once you have chosen where you’ll expose the BugSnag dashboard, you’ll need to let your BugSnag On-premise instance know the hostname you’ve chosen by editing the BUGSNAG_WEBSITE_HOST setting in /etc/bugsnag/env.sh:

BUGSNAG_WEBSITE_HOST=http://bugsnag.internal.example.com

If you are using two-way issue tracker integrations, you’ll need to let your BugSnag On-premise instance know the webhook hostname you’ve chosen by editing the WEBHOOK_HOST setting in /etc/bugsnag/env.sh:

WEBHOOK_HOST=http://bugsnag-hooks.internal.example.com

Configure HTTP to HTTPS redirection

The BugSnag dashboard on your BugSnag On-premise instance by default is available via HTTP. You can make the dashboard automatically redirect to HTTPS by adding the following setting to /etc/bugsnag/env.sh:

BUGSNAG_HTTPS_REDIRECT=true

If you are running an external load balancer to proxy your BugSnag On-premise instance with SSL make sure the X-Forwarded-Proto header is set to https by the load balancer.

You can also setup your own proxy using Nginx.

Other configuration

By default, the admin email address is available from the login page so that new users can request an account. If you don’t want this to be displayed, add the following setting to /etc/bugsnag/env.sh:

HIDE_LOGIN_PAGE_CONTACT_EMAIL=true

If you want to use a different email address for new users to request an account from, add the following setting to /etc/bugsnag/env.sh:

BUGSNAG_ADMIN_EMAIL=admin@example.com

By default we limit event processing to just over 100 events per minute per project. Anything above that rate in a minute is throttled and not saved. You can adjust that rate by adding the following setting to /etc/bugsnag/env.sh:

BUGSNAG_SAMPLE_ALLOWANCE=500

First boot

Now you’ve installed and configured BugSnag, you’ll need to start the BugSnag apps. This may take around 5 minutes the first time:

sudo bugsnag start

To check BugSnag’s status as it boots, you can run the following command:

sudo bugsnag status

When all services are marked as up, your BugSnag installation is complete.

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 x.x.x.x:49080) to set up your account and create projects for each of the applications you wish to monitor.

Endpoint configuration

Error reporting libraries

By default, BugSnag reporting libraries will send errors to notify.bugsnag.com, so you’ll need to configure your applications to send errors to your On-premise installation, at the hostname/port you configured for the BugSnag Event Server endpoint above.

For example, in Ruby apps:

Bugsnag.configure do |config|
  config.api_key = "your-api-key"
  config.endpoint = "notify.bugsnag.internal.example.com"
end

For Browser JavaScript reporting the endpoint must have a /js suffix:

<script src="//d2wy8f7a9ursnm.cloudfront.net/bugsnag-3.min.js"
      data-apikey="YOUR-API-KEY-HERE"
      data-endpoint="https://notify.bugsnag.internal.example.com/js"></script>

Check the documentation for your library for details.

Uploading iOS/macOS dSYM files

If you’re developing iOS/macOS applications, you’ll need to configure Xcode to send debug symbols to your On-premise installation, at the hostname/port you configured for the BugSnag Upload Server endpoint above.

See the dSYM Upload API for how to configure this.

Uploading ProGuard mapping files

If you’re developing Android applications which are obfuscated using ProGuard, you’ll need to configure the BugSnag Gradle Plugin to upload ProGuard mapping files to your On-premise installation, at the hostname/port you configured above for the BugSnag Upload Server endpoint above.

See the custom endpoints for details.