Self-Hosted Backup & Restore

Partial JSON backup

If you need a quick way to backup, view, examine, and restore data from your Sentry instance and don't need historical event data, you can use any of the following methods:

• A custom, scoped backup via sentry-admin.sh (on self-hosted versions >=23.11.1).
• Running the included backup and restore scripts in the self-hosted/scripts directory (on self-hosted versions >=23.3.1).
• Manually calling the export and import commands in the web docker container.

These commands should be run from your self-hosted directory, and will save and load "low-volume" data only.

What's included?

The partial JSON backup is just that - partial. Its purpose is to include "low-volume" data like users, organizations, and server configurations, while excluding "high-volume" data like events, issues, or anything that references external files.

Specifically, the following data is generally included in a partial JSON backup:

• Global configuration (options, admin accounts, API keys and authorizations, etc).
• Sentry apps, service hooks, and basic integrations.
• Users, their authenticators, notifications, and recent/saved searches.
• Organizations, their members, and their settings.
• Projects, their members, and their settings.
• Teams, their members, and their settings.
• Alert rules, incidents, and monitors.

Backup

Basic usage

Depending on which version of self-hosted you're running, you may perform a simple JSON backup as follows:

# If using self-hosted version <= 23.3.0:
docker compose run -v $(pwd)/sentry:/sentry-data/backup  --rm -T -e SENTRY_LOG_LEVEL=CRITICAL web export /sentry-data/backup/backup.json

# If using self-hosted version >= 23.3.1:
./scripts/backup.sh

# If using self-hosted version >= 24.1.0:
./scripts/backup.sh [user | organization | config | global]

Advanced usage

If you'd like more granular control over what gets backed up, and are using a self-hosted release greater than or equal to 23.11.1, you may use the sentry-admin export command instead. In particular, this command allows you export only a certain scope of data. There are four such scopes:

• User: Exports data associated with Sentry users only, like their emails, permissions, and login credentials. Exports in this scope can be filtered by username. Exports in this scope can be created using the sentry-admin.sh export users ... CLI command.
• Organization: Exports data owned by a set of Sentry organizations, and the users that are members of that set. Exports in this scope can be filtered by organization slug. Exports in this scope can be created using the sentry-admin.sh export organizations ... CLI command.
• Config: Exports all instance-wide configurations, like global options and admin credentials. Exports in this scope can be created using the sentry-admin.sh export config ... CLI command.
• Global: Exports all exportable data. Exports in this scope can be created using the sentry-admin.sh export global ... CLI command. This command is equivalent to running backup.sh.

For more detailed information, including how to encrypt a backup, see sentry-admin.sh export --help.

Restore

Once you have generated a backup, the easiest way to restore it is to place it under the sentry directory in your main self-hosted repo, next to the config files. This directory automatically gets mounted to /etc/sentry so you can run the following to restore your backup:

# If using self-hosted version <= 23.3.0:
docker compose run --rm -T web import /etc/sentry/backup.json

# If using self-hosted version >= 23.3.1:
./scripts/restore.sh

# If using self-hosted version >= 24.1.0:
./scripts/restore.sh [user | organization | config | global]

If you don't see any errors and the process exits with code 0, congratulations, you have just restored your backup.

Advanced usage

If you'd like more granular control over what gets restored from a given backup, and are using a self-hosted release greater than or equal to 23.11.1, you may use the sentry-admin import command instead. This command allows you to control the scope of data that gets imported, as well as how it interacts with data already loaded onto the instance.

For more detailed information, including how to decrypt an encrypted backup, see sentry-admin.sh export --help.

Full backup

The ideal way to backup and restore Sentry is to backup and restore all Docker volumes that it uses. All volumes that hold critical long-term data are already defined as global volumes at install time and are prefixed with sentry-:

• sentry-data
• sentry-postgres
• sentry-redis
• sentry-zookeeper
• sentry-kafka
• sentry-clickhouse
• sentry-symbolicator

Docker documents how to backup and restore volumes on their documentation. You may use different methods as long as the volumes can be read back without issues.