Skip to content
This repository was archived by the owner on Aug 14, 2024. It is now read-only.
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
2 changes: 1 addition & 1 deletion src/docs/continuous-integration.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ If you've deployed something bad, you'll need to do the following:

## Docker images

We use Google Cloud Build to build our Docker containers. Every single commit (including from PRs) gets built, tested and becomes available at `us.gcr.io/sentryio/sentry:<sha>` with no retention guarantees. Every push to `master` gets built, tested and [pushed to Docker Hub](https://hub.docker.com/r/getsentry/sentry/tags) permanently. You can set `SENTRY_IMAGE` to the following, when working with [getsentry/onpremise](https://github.com/getsentry/onpremise):
We use Google Cloud Build to build our Docker containers. Every single commit (including from PRs) gets built, tested and becomes available at `us.gcr.io/sentryio/sentry:<sha>` with no retention guarantees. Every push to `master` gets built, tested and [pushed to Docker Hub](https://hub.docker.com/r/getsentry/sentry/tags) permanently. You can set `SENTRY_IMAGE` to the following, when working with [getsentry/self-hosted](https://github.com/getsentry/self-hosted):

* `getsentry/sentry:<sha>`, `getsentry/sentry:<short_sha>`, or `getsentry/sentry:latest` to pull from a commit in [getsentry/sentry](https://github.com/getsentry/sentry) `master`
* `us.gcr.io/sentryio/sentry:<sha>` to pull from a commit in any other branch or PR
Expand Down
2 changes: 1 addition & 1 deletion src/docs/feature-flags.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -388,7 +388,7 @@ sentry.io, you have a few potential paths:
- If the feature cannot be disabled, or you don't need to conditionally disable
the feature, remove the feature flag and all related checks from the Sentry
code base. If necessary, also remove references to the feature from the
[onpremise](https://github.com/getsentry/onpremise) and getsentry
[self-hosted](https://github.com/getsentry/self-hosted) and getsentry
repositories.
- If the feature will only be available to SaaS customers on specific plans, you
need to add your feature flag to the appropriate plans and update feature
Expand Down
4 changes: 2 additions & 2 deletions src/docs/self-hosted/backup.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ If you omit the `-T` or `-e SENTRY_LOG_LEVEL=CRITICAL` parts, your backup file w

### Restore

Once you have a backup by using the `export` command, the easiest way to restore it is to place it under the `sentry` directory in your main `onpremise` repo, next to the config files. This directory automatically gets mounted to `/etc/sentry` so you can run the following to restore your backup:
Once you have a backup by using the `export` command, 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
docker-compose run --rm -T web import /etc/sentry/backup.json
Expand All @@ -43,7 +43,7 @@ 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_onpremise_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.
2 changes: 1 addition & 1 deletion src/docs/self-hosted/custom-ca-roots.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ The container's logs will have the output from `update-ca-certificates` right at

## Dependencies With Bundled Roots

Some dependencies have opted to bundle their own CA roots and ignore the system CA roots. Where known, they have been configured to use the system roots. If something seems to ignore the system roots, [create an issue](https://github.com/getsentry/onpremise/issues/new?template=bug.yml) so it can be tracked down and fixed.
Some dependencies have opted to bundle their own CA roots and ignore the system CA roots. Where known, they have been configured to use the system roots. If something seems to ignore the system roots, [create an issue](https://github.com/getsentry/self-hosted/issues/new?template=problem-report.yml) so it can be tracked down and fixed.
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also picked off bug.ymlproblem-report.yml to keep up with getsentry/self-hosted#1159.


### Overridden Bundled Roots

Expand Down
6 changes: 3 additions & 3 deletions src/docs/self-hosted/geolocation.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,20 +22,20 @@ With this configuration file in place, subsequent runs of Sentry's `install.sh`

1. For the `web` service: **User Settings > Security > Session History** should display country code and region (for example, "US (CA)") underneath the IP addresses in the table.

It's normal to see the `sentry_onpremise_geoipupdate_1` container exit soon after startup, since updating the geolocation database is a one-off batch process and not a long-running job.
It's normal to see the `sentry_self_hosted_geoipupdate_1` container exit soon after startup, since updating the geolocation database is a one-off batch process and not a long-running job.

## Upgrading

The services that consume the `GeoLite2-City.mmdb` file need to know where to find it. New installs will have this set automatically, but if you are upgrading you will need to manually set the following before restarting Sentry.

In `relay/config.yml` ([example](https://github.com/getsentry/onpremise/blob/master/relay/config.example.yml)):
In `relay/config.yml` ([example](https://github.com/getsentry/self-hosted/blob/master/relay/config.example.yml)):

```yaml
processing:
geoip_path: "/geoip/GeoLite2-City.mmdb"
```

In `sentry/sentry.conf.py` ([example](https://github.com/getsentry/onpremise/blob/master/sentry/sentry.conf.example.py)):
In `sentry/sentry.conf.py` ([example](https://github.com/getsentry/self-hosted/blob/master/sentry/sentry.conf.example.py)):

```py
GEOIP_PATH_MMDB = '/geoip/GeoLite2-City.mmdb'
Expand Down
10 changes: 5 additions & 5 deletions src/docs/self-hosted/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,23 @@ In addition to making its source code available publicly, Sentry offers and main

## Getting Started

Our recommendation is to download the [latest release of the onpremise repository](https://github.com/getsentry/onpremise/releases/latest), and then run `./install.sh` inside this directory. This script will take care of all the things you need to get started, including a base-line configuration, and then will tell you to run `docker-compose up -d` to start Sentry. Sentry binds to port `9000` by default. You should be able to reach the login page at [http://127.0.0.1:9000](http://127.0.0.1:9000/).
Our recommendation is to download the [latest release of the self-hosted repository](https://github.com/getsentry/self-hosted/releases/latest), and then run `./install.sh` inside this directory. This script will take care of all the things you need to get started, including a base-line configuration, and then will tell you to run `docker-compose up -d` to start Sentry. Sentry binds to port `9000` by default. You should be able to reach the login page at [http://127.0.0.1:9000](http://127.0.0.1:9000/).

## Configuration

You very likely will want to adjust the default configuration for Sentry. These facilities are available for that purpose:

1. **`sentry/config.yml`**—Contains most, if not all, configuration options to adjust. This file is generated from [`sentry/config.example.yml`](https://github.com/getsentry/onpremise/blob/master/sentry/config.example.yml) at the time of installation. The file itself documents the most common configuration options as code comments. Some popular settings in this file include:
1. **`sentry/config.yml`**—Contains most, if not all, configuration options to adjust. This file is generated from [`sentry/config.example.yml`](https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml) at the time of installation. The file itself documents the most common configuration options as code comments. Some popular settings in this file include:

1. `system.url-prefix` (we prompt you to set this at the welcome screen, right after the installation)

1. `mail.*` (though we do ship with a basic SMTP server)

1. integrations for GitHub, Slack, etc.

1. **`sentry/sentry.conf.py`**—Contains more advanced configuration. This file is generated from [`sentry/sentry.conf.example.py`](https://github.com/getsentry/onpremise/blob/master/sentry/sentry.conf.example.py) during installation.
1. **`sentry/sentry.conf.py`**—Contains more advanced configuration. This file is generated from [`sentry/sentry.conf.example.py`](https://github.com/getsentry/self-hosted/blob/master/sentry/sentry.conf.example.py) during installation.

1. **Environment variables**—The available keys are defined in [.env](https://github.com/getsentry/onpremise/blob/master/.env). Use some system-dependent means of setting environment variables if you need to override any of them.
1. **Environment variables**—The available keys are defined in [.env](https://github.com/getsentry/self-hosted/blob/master/.env). Use some system-dependent means of setting environment variables if you need to override any of them.

1. [Geolocation](/self-hosted/geolocation/) uses **a custom configuration file** to conform to the underlying technology.

Expand All @@ -43,6 +43,6 @@ Here is further information on specific configuration topics related to self-hos

## Productionalizing

We strongly recommend using a dedicated load balancer in front of your Sentry setup bound to a dedicated domain or subdomain. A dedicated load balancer that does SSL/TLS termination that also forwards the client IP address as Docker Compose internal network (as this is [close to impossible to get otherwise)](https://github.com/getsentry/onpremise/issues/554) would give you the best Sentry experience. As part of this setup we recommend configuring a load balancer health check against the `/_health/` endpoint using HTTP protocol. This will return a 200 if Sentry is up or a 500 with the list of problems.
We strongly recommend using a dedicated load balancer in front of your Sentry setup bound to a dedicated domain or subdomain. A dedicated load balancer that does SSL/TLS termination that also forwards the client IP address as Docker Compose internal network (as this is [close to impossible to get otherwise)](https://github.com/getsentry/self-hosted/issues/554) would give you the best Sentry experience. As part of this setup we recommend configuring a load balancer health check against the `/_health/` endpoint using HTTP protocol. This will return a 200 if Sentry is up or a 500 with the list of problems.

Keep in mind that all this setup uses single-nodes for all services, including Kafka. For larger loads, you'd need a beefy machine with lots of RAM and disk storage. To scale up even further, you are very likely to use clusters with a more complex tool, such as Kubernetes. Due to self-hosted installations' very custom nature, we do not offer any recommendations or guidance around scaling up. We do what works for us for our thousands of customers over at [sentry.io](https://sentry.io/) and would love to have you over when you feel your local install's maintenance becomes a burden instead of a joy.
10 changes: 5 additions & 5 deletions src/docs/self-hosted/releases.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ 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. A new version is released on the [15th of each month](https://github.com/getsentry/onpremise/blob/704e4c3b5b7360080f79bcfbe26583e5a95ae675/.github/workflows/release.yml#L20-L24), and follow-up releases are done when necessary in between. You can find the [latest release](https://github.com/getsentry/onpremise/releases/latest) over at the [releases section of our onpremise repository](https://github.com/getsentry/onpremise/releases/).
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. A new version is released on the [15th of each month](https://github.com/getsentry/self-hosted/blob/704e4c3b5b7360080f79bcfbe26583e5a95ae675/.github/workflows/release.yml#L20-L24), and follow-up releases are done when necessary in between. 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">
In short, this is to keep the self-hosted Sentry as close to the live version
Expand All @@ -20,13 +20,13 @@ 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 onpremise repository you want, replace your existing folder's contents with that, and then run `./install.sh`.
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`.

<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/onpremise/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.
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>

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/onpremise/issues/607) for more information.
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="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.
Expand All @@ -53,7 +53,7 @@ Any other case (`21.6.3+`), you should be able to upgrade to the latest version

## Nightly Builds

We provide nightly builds from the [master branch of the onpremise repository](https://github.com/getsentry/onpremise/) for each new commit for [Sentry](https://github.com/getsentry/sentry), and all of the supporting projects:
We provide nightly builds from the [master branch of the self-hosted repository](https://github.com/getsentry/self-hosted/) for each new commit for [Sentry](https://github.com/getsentry/sentry), and all of the supporting projects:

- [Snuba](https://github.com/getsentry/snuba)
- [Relay](https://github.com/getsentry/relay)
Expand Down
10 changes: 5 additions & 5 deletions src/docs/self-hosted/sso.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ SSO in Sentry is handled in one of two ways:

## Using a middleware proxy (SAML2)

As of Sentry 20.6.0, self-hosted Sentry comes with built-in support for SAML2 and certain auth providers. For older versions you will need to add the following line into [`sentry/requirements.txt`](https://github.com/getsentry/onpremise/blob/10.0.1/sentry/requirements.example.txt) before running `./install.sh`:
As of Sentry 20.6.0, self-hosted Sentry comes with built-in support for SAML2 and certain auth providers. For older versions you will need to add the following line into [`sentry/requirements.txt`](https://github.com/getsentry/self-hosted/blob/10.0.1/sentry/requirements.example.txt) before running `./install.sh`:

```
sentry-auth-saml2@https://github.com/getsentry/sentry-auth-saml2/archive/master.zip#egg=sentry-auth-saml2
Expand All @@ -28,7 +28,7 @@ Please refer to our [main SAML documentation](https://docs.sentry.io/accounts/ss

### Google Auth

As of [Sentry 9.1](https://github.com/getsentry/onpremise/releases/tag/9.1.2), self-hosted Sentry comes with built-in Google Auth support. To enable, you'll need to [create a client ID and secret for your Google App](https://developers.google.com/identity/sign-in/web/server-side-flow#step_1_create_a_client_id_and_client_secret) and then enter these values into your [`sentry/config.yaml`](https://github.com/getsentry/onpremise/blob/master/sentry/config.example.yml) file respectively:
As of [Sentry 9.1](https://github.com/getsentry/self-hosted/releases/tag/9.1.2), self-hosted Sentry comes with built-in Google Auth support. To enable, you'll need to [create a client ID and secret for your Google App](https://developers.google.com/identity/sign-in/web/server-side-flow#step_1_create_a_client_id_and_client_secret) and then enter these values into your [`sentry/config.yaml`](https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml) file respectively:

```yaml
auth-google.client-id: '<client id>'
Expand All @@ -41,7 +41,7 @@ auth-google.client-secret: '<client secret>'

### GitHub Auth

As of [Sentry 10](https://github.com/getsentry/onpremise/releases/tag/10.0.1), self-hosted Sentry comes with built-in GitHub Auth support. To enable, you'll need to create a new GitHub App under your organization and install it.
As of [Sentry 10](https://github.com/getsentry/self-hosted/releases/tag/10.0.1), self-hosted Sentry comes with built-in GitHub Auth support. To enable, you'll need to create a new GitHub App under your organization and install it.

#### Create GitHub App for SSO & integration

Expand Down Expand Up @@ -82,7 +82,7 @@ When prompted for permissions, choose the following:

You will then need to set the following configuration values:

In [`sentry/sentry.conf.py`](https://github.com/getsentry/onpremise/blob/master/sentry/sentry.conf.example.py)
In [`sentry/sentry.conf.py`](https://github.com/getsentry/self-hosted/blob/master/sentry/sentry.conf.example.py)

```python
GITHUB_APP_ID="<App ID>"
Expand All @@ -93,7 +93,7 @@ GITHUB_REQUIRE_VERIFIED_EMAIL = True # Optional but recommended
#GITHUB_BASE_DOMAIN = "git.example.com"
#GITHUB_API_DOMAIN = "api.git.example.com"
```
In [`sentry/config.yaml`](https://github.com/getsentry/onpremise/blob/master/sentry/config.example.yml)
In [`sentry/config.yaml`](https://github.com/getsentry/self-hosted/blob/master/sentry/config.example.yml)

```yaml
# github-app.id: <App ID>
Expand Down
Loading