docs(self-hosted): move configuration guide outside of index (#12891)

--------- Co-authored-by: Amin Vakil <[email protected]>
getsentry · Mar 5, 2025 · 85eb422 · 85eb422
1 parent 4a55365
commit 85eb422
Show file tree

Hide file tree

Showing 3 changed files with 109 additions and 99 deletions.
diff --git a/develop-docs/self-hosted/configuration.mdx b/develop-docs/self-hosted/configuration.mdx
@@ -0,0 +1,81 @@
+---
+title: Self-Hosted Configuration
+sidebar_title: Configuration
+sidebar_order: 1
+description: Learn how to configure your own self-hosted Sentry
+---
+
+## Updating basic configuration
+
+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`](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). But it is recommended to uncomment this and set this to the accessible URL of your self-hosted Sentry installation. If you can't click to the link on emails or your DSN domains are empty, you almost certainly need to fill this out.
+
+    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/self-hosted/blob/master/sentry/sentry.conf.example.py) during installation.
+
+1. **`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.
+
+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. 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 --wait`.
+
+1. [Geolocation](/self-hosted/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](/config/).
+
+<Alert title="Note">
+  Once you change your configuration, it's highly recommended to re-run <code>./install.sh</code> script rather than restarting all services using <code>docker compose restart</code>. This ensures no other configuration or migrations that might be missing when something is toggled on.
+</Alert>
+
+### Event Retention
+
+Sentry comes with a cleanup cron job that prunes events older than `90 days` by default. If you want to change that, you can edit the `SENTRY_EVENT_RETENTION_DAYS` environment variable in `.env` or simply override it in your environment.
+
+### Installing a specific SHA
+
+If you want to install a specific release of Sentry, use the tags/releases on the self-hosted repository.
+
+We continuously push the Docker image for each commit made into [Sentry](https://github.com/getsentry/sentry), and other services such as [Snuba](https://github.com/getsentry/snuba) or [Symbolicator](https://github.com/getsentry/symbolicator) to [our Docker Hub](https://hub.docker.com/u/getsentry) and tag the latest version on master as `:nightly`. This is also usually what we have on sentry.io and what the install script uses. You can use a custom Sentry image, such as a modified version that you have built on your own, or refer a specific commit hash as the image tag by setting the `SENTRY_IMAGE` environment variable to that image name before running `./install.sh`:
+
+```bash
+SENTRY_IMAGE=getsentry/sentry:83b138090a3078352e3f733de7209fb02ef4f98a ./install.sh
+```
+
+Note that this may not work for all commit SHAs as this repository evolves with Sentry and its satellite projects. It is highly recommended to check out a version of this repository that is close to the timestamp of the Sentry commit you are installing.
+
+### Enabling Preview Features
+
+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](https://github.com/getsentry/self-hosted/labels/Type%3A%20Pre-release%20Feature).
+
+### Customize DotEnv (.env) file
+
+Environment specific configurations can be done in the `.env.custom` file. It will be located in the root directory of the Sentry installation, and if it exists then `.env` will be ignored entirely.
+
+By default, there exists no `.env.custom` file. In this case, you can manually add this file by copying the `.env` file to a new `.env.custom` file and adjust your settings in the `.env.custom` file.
+
+Please keep in mind to check the `.env` file for changes, when you perform an upgrade of Sentry, so that you can adjust your `.env.custom` accordingly, if required, as `.env` is ignored entirely if `.env.custom` is present.
+
+For all Docker Compose commands, you should specify your `.env.custom`, otherwise the default `.env` file will be used. Some examples are:
+
+```bash
+docker compose --env-file .env.custom up --wait
+
+# You can also specify the original `.env` file as a fallback if the
+# environment variable doesn't exists on the `.env.custom` file.
+docker compose --env-file .env --env-file .env.custom up --wait
+```
+
+### Configuration Topics
+
+Here is further information on specific configuration topics related to self-hosting:
+
+- [Custom CA Roots](/self-hosted/custom-ca-roots/)
+- [Email](/self-hosted/email/)
+- [Geolocation](/self-hosted/geolocation/)
+- [Single Sign-On (SSO)](/self-hosted/sso/)
+- [Content Security Policy](/self-hosted/experimental/csp/)
+- [Errors Only](/self-hosted/experimental/errors-only/)
diff --git a/develop-docs/self-hosted/index.mdx b/develop-docs/self-hosted/index.mdx
@@ -10,7 +10,7 @@ For the sake of simplicity and ubiquity, we have chosen to use [Docker](https://
 
 If you're self-hosting Sentry and want to know how to switch to Sentry SaaS, check out this [live workshop](https://sentry.io/resources/migrate-to-sentry-saas-workshop/) to learn more about our relocation tooling.
 
-### Differences between self-hosted and SaaS
+## Differences between self-hosted and SaaS
 
 The difference only resides on a few things that are impossible to be hosted by most people and billing/payment-related. These are some of the things that are not available on self-hosted (due to previous reasons):
 
@@ -23,32 +23,42 @@ The difference only resides on a few things that are impossible to be hosted by
 
 To put things simply, consider self-hosted as the Business plan without any software limitations and no paid tier.
 
+## Required Minimum System Resources
+
+We require at least **Docker 19.03.6** and **Docker Compose 2.32.2**. It is recommended to install by following the [Docker Engine installation guide](https://docs.docker.com/engine/install/).
+
+These are the minimum requirements:
+- 4 CPU Cores
+- 16 GB RAM
+- 20 GB Free Disk Space
+
+We also recommend using a swapfile whenever applicable.
+
+Depending on your traffic volume, you may want to increase your system specification to handle increased load. Although most of the times, this is not the case for self-hosted Sentry, since no matter how small or big the traffic is, you will most likely hover around the same used resources.
+
+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. See [Event Retention](/self-hosted/configuration#event-retention) section.
+
+There are known issues on installing self-hosted Sentry on RHEL-based Linux distros, such as CentOS, Rocky Linux, and Alma Linux. It is also not possible to install on an Alpine Linux distro. Most people succeed with Debian/Ubuntu-based distros. If you successfully install on another distro, please let us know on the [Sentry's Discord](https://discord.gg/sentry)!
+
 ## Getting Started
 
-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 --wait` 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 do a Git clone of 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 --wait` 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/).
 
-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](/self-hosted/releases/).
+It is recommended to upgrade your self-hosted Sentry regularly. More about this on [Releases & Upgrading](/self-hosted/releases/).
 
+{/* Credits due to Chuckame: https://gist.github.com/steinwaywhw/a4cd19cda655b8249d908261a62687f8?permalink_comment_id=4843419#gistcomment-4843419 */}
 ```bash
-# Assuming current latest version is 24.1.0
-# Current actual version can be acquired from the Releases page on GitHub
-VERSION="24.1.0"
+VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/getsentry/self-hosted/releases/latest)
+VERSION=${VERSION##*/}
 git clone https://github.com/getsentry/self-hosted.git
 cd self-hosted
 git checkout ${VERSION}
-sudo ./install.sh
+./install.sh
+# After installation, run the following to start Sentry:
+docker compose up --wait
 ```
 
-## Required Minimum System Resources
-
-We require at least Docker 19.03.6 and Compose 2.32.2.
-
-These are the minimum requirements:
-- 4 CPU Cores
-- 16 GB RAM
-- 20 GB Free Disk Space
-
-We'd recommend using a swapfile whenever applicable. 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. See [Event Retention](#event-retention) section below.
+Learn more on how you can configure your self-hosted Sentry on the [Configuration section](/self-hosted/configuration/).
 
 ### Self-Hosted Monitoring
 
@@ -126,87 +136,6 @@ To apply new Docker daemon configuration, restart your Docker service with `syst
   Further information regarding Docker default IP pools can be found on the [Troubleshooting guide](/self-hosted/troubleshooting/docker/#docker-network-conflicting-ip-address).
 </Alert>
 
-## Configuration
-
-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`](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/self-hosted/blob/master/sentry/sentry.conf.example.py) during installation.
-
-1. **`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.
-
-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. 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 --wait`.
-
-1. [Geolocation](/self-hosted/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](/config/).
-
-<Alert title="Note">
-  Once you change your configuration, it's highly recommended to re-run <code>./install.sh</code> script rather than restarting all services using <code>docker compose restart</code>. This ensures no other configuration or migrations that might be missing when something is toggled on.
-</Alert>
-
-### Event Retention
-
-Sentry comes with a cleanup cron job that prunes events older than `90 days` by default. If you want to change that, you can edit the `SENTRY_EVENT_RETENTION_DAYS` environment variable in `.env` or simply override it in your environment. If you do not want the cleanup cron, you can remove the `sentry-cleanup` service from the `docker-compose.yml` file.
-
-### Installing a specific SHA
-
-If you want to install a specific release of Sentry, use the tags/releases on the self-hosted repository.
-
-We continuously push the Docker image for each commit made into [Sentry](https://github.com/getsentry/sentry), and other services such as [Snuba](https://github.com/getsentry/snuba) or [Symbolicator](https://github.com/getsentry/symbolicator) to [our Docker Hub](https://hub.docker.com/u/getsentry) and tag the latest version on master as `:nightly`. This is also usually what we have on sentry.io and what the install script uses. You can use a custom Sentry image, such as a modified version that you have built on your own, or simply a specific commit hash by setting the `SENTRY_IMAGE` environment variable to that image name before running `./install.sh`:
-
-```bash
-SENTRY_IMAGE=getsentry/sentry:83b1380 ./install.sh
-```
-
-Note that this may not work for all commit SHAs as this repository evolves with Sentry and its' satellite projects. It is highly recommended to check out a version of this repository that is close to the timestamp of the Sentry commit you are installing.
-
-### Enabling Preview Features
-
-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](https://github.com/getsentry/self-hosted/labels/Type%3A%20Pre-release%20Feature).
-
-### Customize DotEnv (.env) file
-
-Environment specific configurations can be done in the `.env.custom` file. It will be located in the root directory of the Sentry installation, and if it exists then `.env` will be ignored entirely.
-
-By default, there exists no `.env.custom` file. In this case, you can manually add this file by copying the `.env` file to a new `.env.custom` file and adjust your settings in the `.env.custom` file.
-
-Please keep in mind to check the `.env` file for changes, when you perform an upgrade of Sentry, so that you can adjust your `.env.custom` accordingly, if required, as `.env` is ignored entirely if `.env.custom` is present.
-
-For all Docker Compose commands, you should specify your `.env.custom`, otherwise the default `.env` file will be used. Some examples are:
-
-```bash
-docker compose --env-file .env.custom up --wait
-
-# You can also specify the original `.env` file as a fallback if the
-# environment variable doesn't exists on the `.env.custom` file.
-docker compose --env-file .env --env-file .env.custom up --wait
-```
-
-### Enhance Sentry image
-
-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.
-
-### Configuration Topics
-
-Here is further information on specific configuration topics related to self-hosting:
-
-- [Custom CA Roots](/self-hosted/custom-ca-roots/)
-- [Email](/self-hosted/email/)
-- [Geolocation](/self-hosted/geolocation/)
-- [Single Sign-On (SSO)](/self-hosted/sso/)
-- [Content Security Policy](/self-hosted/experimental/csp/)
-- [Errors Only](/self-hosted/experimental/errors-only/)
-
 ## 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/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.

diff --git a/develop-docs/self-hosted/releases.mdx b/develop-docs/self-hosted/releases.mdx
@@ -1,7 +1,7 @@
 ---
 title: Self-Hosted Releases & Upgrading
 sidebar_title: Releases & Upgrading
-sidebar_order: 1
+sidebar_order: 2
 description: Learn how to upgrade your self-hosted Sentry installation and stay up to date with the latest releases
 ---