Self-Hosted Sentry

In addition to making its source code available publicly, Sentry offers and maintains a minimal setup that works out-of-the-box for simple use cases. This repository also serves as a blueprint for how various Sentry services connect for a complete setup, which is useful for folks willing to maintain larger installations. For the sake of simplicity, we have chosen to use Docker and Docker Compose for this, along with a bash-based install and upgrade script.

If you're self-hosting Sentry and want to know how to switch to Sentry SaaS, check out this live workshop on April 30th to learn more about our relocation tooling and ask any questions you might have.

Our recommendation is to download the latest release of the self-hosted repository, 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.

To have easy maintainability for future upgrades, it is recommended to use Git workflow by cloning the self-hosted repository and check out to a specific CalVer tag. More about this on Releases & Upgrading.

Copied
# Assuming current latest version is 24.1.0
# Current actual version can be acquired from the Releases page on GitHub
VERSION="24.1.0"
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
git checkout ${VERSION}
sudo ./install.sh

Depending on your usage, required system resource to run Sentry may varies. Minimum system specification for running Sentry looks like this:

  • 2 CPU cores
  • 4 GB RAM

Having a machine that have lower system specification than that will fail the installation script.

Current recommended system specification for running Sentry is:

  • 4 CPU cores
  • 16 GB RAM
  • 20 GB free disk storage space

Depending on your traffic volume, you may want to increase your system specification to handle increased load. If increasing the disk storage space isn't possible, you can migrate your storage to use external storage such as AWS S3 or Google Cloud Storage (GCS). Decreasing your SENTRY_RETENTION_DAYS environment variable to lower numbers will save some storage space from being full, at the cost of having shorter data retention period.

When you run ./install.sh, you have a choice to opt in or out of our monitoring. This monitoring is used for development and debugging purposes so that we're on top of issues you're facing, allowing us to provide a more seamless installation process. For more details please see the section in the self-hosted README.

Note that choosing whether to send errors or not will become mandatory beginning with the 22.11.0 release.

If you opt-in to it, self-hosted Sentry will periodically communicate with a remote beacon server. This is utilized for a couple of things, primarily:

  • Getting information about the current version of Sentry
  • Retrieving important system notices

The remote server is operated by the Sentry team (sentry.io), and the information reported follows the company's privacy policy.

The following information is reported:

  1. A unique installation ID
  2. The version of Sentry
  3. A technical contact email if opted in to sending contact info (system.admin-email)
  4. General anonymous statistics on the data pattern (such as the number of users and volume of errors)
  5. Names and version of the installed Python modules

Note: The contact email is utilized for security announcements, and will never be used outside of such. You can change your opt in/out settings for sending contact info at any time in the settings of the admin panel.

The data reported is minimal and it greatly helps the development team behind Sentry. With that said, you can disable the beacon with the following setting:

Copied
SENTRY_BEACON = False

In some enterprise setups there is no direct Internet connection, so you must use an HTTP proxy server. How do you install Sentry in this environment? Let us assume:

  1. Your Sentry installation is running on Linux.
  2. http://proxy:3128 is your proxy address.
  3. 127.0.0.0/8 is the only network that should be accessed without a proxy.

Here are the steps to follow:

  1. Set http_proxy, https_proxy and no_proxy variables in the /etc/environment file.
  2. To make the docker pull command respect your proxy settings, create a /etc/systemd/system/docker.service.d/http-proxy.conf file with these contents:
Copied
[Service]
Environment="HTTP_PROXY=http://proxy:3128"
Environment="HTTPS_PROXY=http://proxy:3128"
Environment="NO_PROXY=127.0.0.0/8"
  1. Run systemctl daemon-reload and restart Docker with systemctl restart docker.service.

From there you can run ./install.sh like usual.

By default Sentry sends anonymous usage statistics to the Sentry team. It helps to improve the product. Also there can be different external integrations with third party services like Slack or Twilio. To make these features work it's required to allow Docker containers to access the Internet. To add your proxy environment variables into Sentry's Docker containers, create ~/.docker/config.json with these contents:

Copied
{
  "proxies": {
    "default": {
      "httpProxy": "http://proxy:3128",
      "httpsProxy": "http://proxy:3128",
      "noProxy": "relay,web,sentry,127.0.0.0/8"
    }
  }
}

You can disable this feature by adding SENTRY_BEACON = False into sentry.conf.py file.

This is an experimental beta feature. This means that features and workflows are not completely tested, so use at your own risk!

Starting from 24.8.0+, users will have the ability to choose between two distinct types of self-hosted Sentry deployments: errors only or feature complete..

Errors Only

Errors Only self-hosted offers a small subset of features with an emphasis on minimizing system resources. This lightweight option includes only the following features:

  1. Issues
  2. Alerts
  3. Integrations
  4. Dashboards
  5. Releases
  6. Discover

In order to enable errors only self-hosted, you'll need to update your .env file to include COMPOSE_PROFILES=errors-only.

Feature Complete

This is our default version of self-hosted Sentry. It includes most of the features that are available on our SaaS product, which is everything offered in the Errors Only version, plus the following::

  1. Traces
  2. Profiles
  3. Replays
  4. Insights (Requests, Queries, Assets, etc)
  5. User Feedback
  6. Performance
  7. Crons

This version of Sentry is enabled by default upon installation. Ensure that your .env file includes COMPOSE_PROFILES=feature-complete.

You very likely will want to adjust the default configuration for your Sentry installation as well. 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 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)

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

    3. integrations for GitHub, Slack, etc.

  2. sentry/sentry.conf.py—Contains more advanced configuration. This file is generated from sentry/sentry.conf.example.py during installation.

  3. sentry/enhance-image.sh—To install plugins and their dependencies or make other modifications to the Sentry base image, copy sentry/enhance-image.example.sh to sentry/enhance-image.sh and add necessary steps there. For example, you can use apt-get to install dependencies and use pip to install plugins. After making modifications to sentry/enhance-image.sh, run ./install.sh again to apply them.

  4. Environment variables—The available keys are defined in .env. Use some system-dependent means of setting environment variables if you need to override any of them. To avoid Git changes, simply create a file called .env.custom and insert your system-dependent environment variables there. In order to use this, please use docker compose --env-file /path/to/.env.custom up -d.

  5. Geolocation uses a custom configuration file to conform to the underlying technology.

You can find more about configuring Sentry at the configuration section of our developer documentation.

Only features that have reached General Availability (GA) status will be enabled by default for self-hosted. As users, you can try new features before it reaches GA by adding required infrastructure components and feature flags. Preview features are tracked and documented through GitHub issues with Type: Pre-release Feature labels.

Here is further information on specific configuration topics related to self-hosting:

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) 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.

Once you have setup a load balancer or reverse proxy to your Sentry instance, you should modify the system.url-prefix in the config.yml file to match your new URL and protocol. You should also update the SSL/TLS section in the sentry/sentry.conf.py script, otherwise you may get CSRF-related errors when performing certain actions such as configuring integrations.

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 and would love to have you over when you feel your local install's maintenance becomes a burden instead of a joy.

Sentry is using FSL (Functional Source License). Although it's not an OSI-approved license, the source code of Sentry and its' surrounding service & libraries for self-hosted deployment are open and available on GitHub. For self-hosted, this license means that users can use Sentry and deploy it anywhere (even inside an enterprise ecosystem), but users are prohibited to sell deployed self-hosted Sentry as any kind of offering (SaaS or any kind of business model) and users are prohibited to be a direct competitor of Sentry by using Sentry's code that is FSL-licensed. After two years, the license converts to Apache 2.0 or MIT.

For further information on the FSL License, you can visit the fsl.software website or read the announcement blog post.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").