Skip to content
This repository has been archived by the owner on Aug 14, 2024. It is now read-only.

doc(backup): Update relocation docs #1097

Merged
merged 1 commit into from
Dec 1, 2023
Merged

doc(backup): Update relocation docs #1097

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 106 additions & 25 deletions src/docs/self-hosted/backup.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,54 +2,128 @@
title: "Self-Hosted Backup & Restore"
---

## Quick Backup
## Partial JSON backup

If you need a quick way to backup and restore your Sentry instance and you don't need historical event data, you can use the included backup and restore scripts in the `self-hosted/scripts` directory. These commands will save and load all project and user data, but will not contain any event data. Run these from your `self-hosted` directory.
As of 23.3.1, we're enabling users to opt in/out of error reporting for these scripts.
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

This script creates a `backup.json` file in the `sentry` directory in your main `self-hosted` repo.
#### Basic usage

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

```shell
# 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
```

<Alert title="Note" level="info">
<markdown>

If you choose to backup using the `docker compose run ...` command, omitting the `-T` or `-e
SENTRY_LOG_LEVEL=CRITICAL` arguments will cause your backup file to have logging lines mixed in,
which you will then need to manually remove.

</markdown>
</Alert>

#### 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 a backup by using the backup script, 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:
<Alert level="warning">

Restoring a partial backup using this method will cause existing data in these tables to be deleted!

</Alert>

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:

```shell
# 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 you don't see any errors and the process exits with code `0`, congratulations, you have just restored your backup.
If you don't see any errors and the process exits with code `0`, congratulations, you have just
restored your backup.

<Alert level="warning">
We strongly recommended that you restore your backup on the <strong>same version of Sentry</strong> on a fresh install (empty database but migrations are run). Otherwise, you are very likely to hit errors and may corrupt your database.
</Alert>

### Legacy Backup and Restore
We strongly recommended that you restore your backup on the <strong>same version of Sentry</strong>
on a fresh install (empty database but migrations are run). Otherwise, you are very likely to hit
errors and may corrupt your database.

If you're running on a version of self-hosted Sentry that is below 23.3.1, you'll need to use the built in `import` and `export` commands instead.
</Alert>

#### Backup
```shell
docker compose run -v $(pwd)/sentry:/sentry-data/backup --rm -T -e SENTRY_LOG_LEVEL=CRITICAL web export /sentry-data/backup/backup.json
```
#### Advanced usage

<Alert title="Note" level="info"><markdown>
If you omit the `-T` or `-e SENTRY_LOG_LEVEL=CRITICAL` parts, your backup file will have logging lines mixed in and you'll have to remove them somehow.
</markdown></Alert>
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.

#### Restore
```shell
docker compose run --rm -T web import /etc/sentry/backup.json
```
For more detailed information, including how to decrypt an encrypted backup, see `sentry-admin.sh
export --help`.

## Full Backup
## 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-`:
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`
Expand All @@ -60,7 +134,14 @@ The ideal way to backup and restore Sentry is to backup and restore all Docker v
- `sentry-symbolicator`

<Alert title="Note" level="info">
Only backing up and restoring these volumes should bring back all persisted data. If you also need to back up in-flight data, we recommend backing up any project-specific volumes that <code>docker compose</code> automatically creates, typically with the <code>sentry_self_hosted_sentry-</code> prefix.

Only backing up and restoring these volumes should bring back all persisted data. If you also need
to back up in-flight data, we recommend backing up any project-specific volumes that <code>docker
compose</code> automatically creates, typically with the <code>sentry_self_hosted_sentry-</code>
prefix.

</Alert>

Docker documents [how to backup and restore volumes](https://docs.docker.com/storage/volumes/#backup-restore-or-migrate-data-volumes) on their documentation. You may use different methods as long as the volumes can be read back without issues.
Docker documents [how to backup and restore
volumes](https://docs.docker.com/storage/volumes/#backup-restore-or-migrate-data-volumes) on their
documentation. You may use different methods as long as the volumes can be read back without issues.
Loading