Migration guide

Migrating from version 2 of BugSnag On-premise

<%= partial “on-premise/legacy-single-machine/legacy-warning” %>

Whats new in version 3

For version 3 of BugSnag On-premise we have moved to using Replicated to manage installations and upgrades. With Replicated we can offer the following features and improvements:

  • A management dashboard for performing installations and upgrades at the click of a button.
  • Configuration updated via the management dashboard rather than the env.sh file.
  • One click generation of support bundles to help us give you first class support.
  • A better installation and upgrade experience for customers with airgapped/offline installations.
  • The ability to scale across multiple hosts to increase the performance and reliability of larger installations. Please get in contact with us if you are interested in this feature.

Upgrading will also get you access to the latest BugSnag features, such as the Releases dashboard. Features available are subject to your plan.

Before migrating

To ensure you have the best experience migrating, we ask that you give us the following information prior to attempting an upgrade:

  • Operating system with exact version. Finding the exact version will depend on your OS, e.g:
    • Red Hat: cat /etc/redhat-release
    • CentOS: cat /etc/centos-release
    • Fedora: cat /etc/fedora-release
    • Debian: cat /etc/debian_version
    • Ubuntu/Mint: lsb_release -a
  • The output of running uname -a on your server.
  • The output of running docker version on your server.
  • The output of running docker info on your server.

Running the migration

Before running the migration, we recommend backing up your data and configuration. Please follow the Backup guide below if you don’t have an established process for backing up your installation.

Migrating on a machine with an internet connection

Upgrade the bugsnag script:

$ sudo bugsnag upgrade_script

Run the migrate command. Running this command will shut down your BugSnag On-premise instance. The dashboard will no longer be available and errors reported will no longer be processed, until the migration is complete. This process could take up to 30 minutes.

$ sudo bugsnag migrate

This command will migrate your existing data and settings to v3 of BugSnag On-premise and will begin the process of installing the Replicated management console. You can then follow the instructions from the Online Installation guide.

Migrating on a machine without an internet connection

On an internet connected machine download the new bugsnag control script

$ curl -L -O https://www.bugsnag.com/enterprise-v2/bugsnag

Copy the bugsnag migration script to the offline machine.

Run the migrate command. Running this command will shut down your BugSnag On-premise instance. The dashboard will no longer be available and errors reported will no longer be processed, until the migration is complete. This process could take up to 30 minutes.

sudo ./bugsnag migrate --offline

This command will migrate your existing data and settings to v3 of BugSnag On-premise and will begin the process of installing the Replicated management console. You can then follow the instructions from the Airgapped Installation guide.

Backup

Data Directory

The data volume contains all the database files that BugSnag On-premise uses. Backing up this directory requires a consistent backup of the entire directory, so you need to either stop the running BugSnag On-premise instance, or use a point in time file system snapshot.

If you are using Amazon EC2 (or another cloud provider) and your data directory is stored on EBS, you can use the EBS snapshot function to take a point in time snapshot of the data directory. If you are not using EC2, but you are using an LVM or some other file system that supports snapshots (ZFS) then it is possible that you can still take a point in time snapshot. This is the recommended way of backing up your data directory as there is no downtime for your installation.

Data directory

Stop the running BugSnag instance you can use the unix command cp to copy the data directory into a resilient backup area. For example,

sudo bugsnag stop
cp -r /data /backups/

It is important to stop the running instance so that the files in the data directory are consistent when making this backup.

Configuration directory

You should also make a copy of your configuration directory, as it has randomly generated encryption keys which are used to secure data in your installation. If you do not back this information up, then your installation will be rendered useless if these keys are lost.

To backup the directory, simply use the cp command to copy the directory to a safe place away from the machine BugSnag is being run on.

cp -r /etc/bugsnag /backups/