You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
description: Learn how to configure your own self-hosted Sentry
6
+
---
7
+
8
+
## Updating basic configuration
9
+
10
+
You very likely will want to adjust the default configuration for your Sentry installation as well. These facilities are available for that purpose:
11
+
12
+
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:
13
+
14
+
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.
15
+
16
+
1.`mail.*` (though we do ship with a basic SMTP server)
17
+
18
+
1. integrations for GitHub, Slack, etc.
19
+
20
+
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.
21
+
22
+
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.
23
+
24
+
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`.
25
+
26
+
1.[Geolocation](/self-hosted/geolocation/) uses **a custom configuration file** to conform to the underlying technology.
27
+
28
+
You can find more about configuring Sentry at [the configuration section of our developer documentation](/config/).
29
+
30
+
<Alerttitle="Note">
31
+
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.
32
+
</Alert>
33
+
34
+
### Event Retention
35
+
36
+
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.
37
+
38
+
### Installing a specific SHA
39
+
40
+
If you want to install a specific release of Sentry, use the tags/releases on the self-hosted repository.
41
+
42
+
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`:
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.
49
+
50
+
### Enabling Preview Features
51
+
52
+
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).
53
+
54
+
### Customize DotEnv (.env) file
55
+
56
+
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.
57
+
58
+
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.
59
+
60
+
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.
61
+
62
+
For all Docker Compose commands, you should specify your `.env.custom`, otherwise the default `.env` file will be used. Some examples are:
63
+
64
+
```bash
65
+
docker compose --env-file .env.custom up --wait
66
+
67
+
# You can also specify the original `.env` file as a fallback if the
68
+
# environment variable doesn't exists on the `.env.custom` file.
69
+
docker compose --env-file .env --env-file .env.custom up --wait
70
+
```
71
+
72
+
### Configuration Topics
73
+
74
+
Here is further information on specific configuration topics related to self-hosting:
Copy file name to clipboardExpand all lines: develop-docs/self-hosted/index.mdx
+27-98
Original file line number
Diff line number
Diff line change
@@ -10,7 +10,7 @@ For the sake of simplicity and ubiquity, we have chosen to use [Docker](https://
10
10
11
11
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.
12
12
13
-
###Differences between self-hosted and SaaS
13
+
## Differences between self-hosted and SaaS
14
14
15
15
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):
16
16
@@ -23,32 +23,42 @@ The difference only resides on a few things that are impossible to be hosted by
23
23
24
24
To put things simply, consider self-hosted as the Business plan without any software limitations and no paid tier.
25
25
26
+
## Required Minimum System Resources
27
+
28
+
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/).
29
+
30
+
These are the minimum requirements:
31
+
- 4 CPU Cores
32
+
- 16 GB RAM
33
+
- 20 GB Free Disk Space
34
+
35
+
We also recommend using a swapfile whenever applicable.
36
+
37
+
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.
38
+
39
+
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.
40
+
41
+
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)!
42
+
26
43
## Getting Started
27
44
28
-
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/).
45
+
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/).
29
46
30
-
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/).
47
+
It is recommended to upgrade your self-hosted Sentry regularly. More about this on [Releases & Upgrading](/self-hosted/releases/).
31
48
49
+
{/* Credits due to Chuckame: https://gist.github.com/steinwaywhw/a4cd19cda655b8249d908261a62687f8?permalink_comment_id=4843419#gistcomment-4843419 */}
32
50
```bash
33
-
# Assuming current latest version is 24.1.0
34
-
# Current actual version can be acquired from the Releases page on GitHub
# After installation, run the following to start Sentry:
58
+
docker compose up --wait
40
59
```
41
60
42
-
## Required Minimum System Resources
43
-
44
-
We require at least Docker 19.03.6 and Compose 2.32.2.
45
-
46
-
These are the minimum requirements:
47
-
- 4 CPU Cores
48
-
- 16 GB RAM
49
-
- 20 GB Free Disk Space
50
-
51
-
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.
61
+
Learn more on how you can configure your self-hosted Sentry on the [Configuration section](/self-hosted/configuration/).
52
62
53
63
### Self-Hosted Monitoring
54
64
@@ -126,87 +136,6 @@ To apply new Docker daemon configuration, restart your Docker service with `syst
126
136
Further information regarding Docker default IP pools can be found on the [Troubleshooting guide](/self-hosted/troubleshooting/docker/#docker-network-conflicting-ip-address).
127
137
</Alert>
128
138
129
-
## Configuration
130
-
131
-
You very likely will want to adjust the default configuration for your Sentry installation as well. These facilities are available for that purpose:
132
-
133
-
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:
134
-
135
-
1.`system.url-prefix` (we prompt you to set this at the welcome screen, right after the installation)
136
-
137
-
1.`mail.*` (though we do ship with a basic SMTP server)
138
-
139
-
1. integrations for GitHub, Slack, etc.
140
-
141
-
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.
142
-
143
-
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.
144
-
145
-
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`.
146
-
147
-
1.[Geolocation](/self-hosted/geolocation/) uses **a custom configuration file** to conform to the underlying technology.
148
-
149
-
You can find more about configuring Sentry at [the configuration section of our developer documentation](/config/).
150
-
151
-
<Alerttitle="Note">
152
-
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.
153
-
</Alert>
154
-
155
-
### Event Retention
156
-
157
-
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.
158
-
159
-
### Installing a specific SHA
160
-
161
-
If you want to install a specific release of Sentry, use the tags/releases on the self-hosted repository.
162
-
163
-
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`:
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.
170
-
171
-
### Enabling Preview Features
172
-
173
-
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).
174
-
175
-
### Customize DotEnv (.env) file
176
-
177
-
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.
178
-
179
-
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.
180
-
181
-
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.
182
-
183
-
For all Docker Compose commands, you should specify your `.env.custom`, otherwise the default `.env` file will be used. Some examples are:
184
-
185
-
```bash
186
-
docker compose --env-file .env.custom up --wait
187
-
188
-
# You can also specify the original `.env` file as a fallback if the
189
-
# environment variable doesn't exists on the `.env.custom` file.
190
-
docker compose --env-file .env --env-file .env.custom up --wait
191
-
```
192
-
193
-
### Enhance Sentry image
194
-
195
-
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.
196
-
197
-
After making modifications to `sentry/enhance-image.sh`, run `./install.sh` again to apply them.
198
-
199
-
### Configuration Topics
200
-
201
-
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)](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.
0 commit comments