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

self-hosted: update upgrade path #1345

Merged
merged 2 commits into from
Aug 14, 2024
Merged

self-hosted: update upgrade path #1345

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
734b585
update
joshuarli Aug 13, 2024
2a78fbc
update
joshuarli Aug 13, 2024
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
56 changes: 20 additions & 36 deletions src/docs/self-hosted/releases.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,6 @@
title: 'Self-Hosted Releases & Upgrading'
---

![CalVer: YY.MM.MICRO](https://img.shields.io/badge/calver-YY.MM.MICRO-ad6caa.svg)

Sentry cuts regular releases for self-hosting to keep it as close to [sentry.io](https://sentry.io) as possible. We decided to follow a monthly release schedule using the [CalVer](https://calver.org/#scheme) versioning scheme, with a primary release on the [15th of each month](https://github.com/getsentry/self-hosted/blob/704e4c3b5b7360080f79bcfbe26583e5a95ae675/.github/workflows/release.yml#L20-L24). We don't patch old versions, but if a bug is bad enough we may cut an out-of-cycle point release, which, like our regular monthly releases, is a snapshot of the latest versions of all of our components. You can find the [latest release](https://github.com/getsentry/self-hosted/releases/latest) over at the [releases section of our self-hosted repository](https://github.com/getsentry/self-hosted/releases/).

<Alert title="Why CalVer?" level="info">
Expand All @@ -20,50 +18,36 @@ Sentry cuts regular releases for self-hosting to keep it as close to [sentry.io]

We encourage everyone to regularly update their Sentry installations to get the best and the most recent Sentry experience.

To upgrade, all you need to do is download or check out the version of self-hosted repository you want, replace your existing folder's contents with that, and then run `./install.sh`.
Before starting the upgrade, we shut down all the services and then run some data migrations, so expect to have some downtime. There is an *experimental* `--minimize-downtime` option to reduce the downtime during upgrades. Use this at your own risk and see [the pull request it was implemented in](https://github.com/getsentry/self-hosted/issues/607) for more information.

<Alert title="Configuration Updates" level="info">
We may have some updated configuration, especially for new features, so always check the example config files under the <Link to="https://github.com/getsentry/self-hosted/blob/master/sentry/">sentry directory</Link> and see if you need to update your existing configuration. We do our best to automate critical configuration updates, but you should always check your configs during upgrades.
</Alert>
We assume you've cloned the self-hosted repository, so checkout the version you want to upgrade to (23.11.0 as an example).

Before starting the upgrade, we shut down all the services and then run some data migrations, so expect to have some downtime. There is an *experimental* `--minimize-downtime` option to reduce the downtime during upgrades. Use this at your own risk and see [the pull request it was implemented in](https://github.com/getsentry/self-hosted/issues/607) for more information.
```bash
git fetch
git checkout 23.11.0
```

<Alert title="Warning" level="warning">
There are certain hard-stops you need to go through when upgrading from earlier versions. Please read the <Link to="#hard-stops">hard-stops</Link> section below for a list.
If you upgrade infrequently, it's less likely that upgrading to the latest version will work.
Please refer to <Link to="#hard-stops">Hard Stops</Link> for how to incrementally upgrade to more recent versions.
</Alert>

If you downloaded self-hosted repository using Git clone, the upgrade commands should look like this:
We may have some updated configuration, especially for new features, so always check the example config files under the <Link to="https://github.com/getsentry/self-hosted/blob/master/sentry/">sentry directory</Link> and see if you need to update your existing configuration. We do our best to automate critical configuration updates, but you should always check your configs during upgrades.

Finally, to upgrade, just run `./install.sh`.

```bash
# Assuming your destination upgrade version is 24.3.0
VERSION="24.3.0"
git fetch
git checkout ${VERSION}
sudo ./install.sh
```

### Hard Stops

We have three hards stops that you need to go through in order to pick up significant database changes:

1. If you are coming from a version prior to `9.1.2`, you first need to upgrade to `9.1.2` and follow the next steps:
```
<your.sentry.version> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> 23.6.2 -> latest
```
1. If you are coming from `9.1.2`, you first need to upgrade to `21.5.0` and follow the next steps:
```
<your.sentry.version> -> 21.5.0 -> 21.6.3 -> 23.6.2 -> latest
```
1. If you are coming from a version prior to `21.6.3`, you first need to upgrade to `21.6.3`:
```
<your.sentry.version> -> 21.6.3 -> 23.6.2 -> latest
```
1. If you are coming from a version prior to `23.6.2`, you first need to upgrade to `23.6.2`:
```
<your.sentry.version> -> 23.6.2 -> latest
```

Any other case (`23.6.2+`), you should be able to upgrade to the latest version directly. We'd recommend you skip `23.7.0` to avoid issues around database migrations and the django 3 upgrade.
These are the hard stops that you need to go through in order to pick up significant database changes:

```
<your.sentry.version> -> 9.1.2 -> 21.5.0 -> 21.6.3 -> 23.6.2 -> 23.11.0 -> latest
```

Versions to avoid upgrading to:
- `23.7.0` (issues around database migrations and the Django 3 upgrade)


## Nightly Builds

Expand Down
Loading