Document Sentry self-hosted deployment
This commit is contained in:
+236
-119
@@ -1,176 +1,293 @@
|
||||
# Sentry (Self-Hosted)
|
||||
# Sentry
|
||||
|
||||
## Overview
|
||||
|
||||
Sentry is the centralized error tracking and observability platform used across the SilverLinux infrastructure. It is deployed as a full self-hosted distributed system composed of multiple interconnected services.
|
||||
Sentry is the centralized error tracking and observability platform for SilverLinux-hosted applications.
|
||||
|
||||
This deployment is production-ready and runs as an isolated Docker Compose stack.
|
||||
Status:
|
||||
|
||||
```text
|
||||
Operational
|
||||
```
|
||||
|
||||
Public URL:
|
||||
|
||||
```text
|
||||
https://sentry.silveressence.net
|
||||
```
|
||||
|
||||
Deployment model:
|
||||
|
||||
```text
|
||||
Upstream Sentry self-hosted install.sh
|
||||
```
|
||||
|
||||
Sentry is intentionally documented as an exception to the standard SilverLinux `slcompose` and Infisical pattern. It is a much larger upstream self-hosted application and should be maintained according to the Sentry self-hosted project workflow.
|
||||
|
||||
---
|
||||
|
||||
## Service Status
|
||||
## Runtime Stack
|
||||
|
||||
- Status: Running
|
||||
- Compose Project: sentry-self-hosted
|
||||
- Container Count: 70+ services
|
||||
Compose project:
|
||||
|
||||
```text
|
||||
sentry-self-hosted
|
||||
```
|
||||
|
||||
Install directory:
|
||||
|
||||
```text
|
||||
/srv/docker/sentry
|
||||
```
|
||||
|
||||
Deployment method:
|
||||
|
||||
* Installed with Sentry self-hosted `install.sh`.
|
||||
* Managed as one upstream Sentry self-hosted deployment unit.
|
||||
* Not managed as a normal SilverLinux `slcompose` service.
|
||||
* Not expected to use the standard per-service Infisical path pattern used by smaller SilverLinux services.
|
||||
|
||||
Runtime shape:
|
||||
|
||||
* 70+ containers
|
||||
* Multiple internal queues, stores, workers and processing services
|
||||
* One public web entry path through Nginx Proxy Manager
|
||||
|
||||
Key runtime containers from the 2026-07-08 snapshot:
|
||||
|
||||
| Container | Image | Role | Exposure |
|
||||
| --- | --- | --- | --- |
|
||||
| `sentry-self-hosted-nginx-1` | `nginx:1.31.0-alpine` | Public Sentry entry proxy | Publishes `0.0.0.0:9000 -> 80/tcp`; NPM forwards to `80` |
|
||||
| `sentry-self-hosted-web-1` | `sentry-self-hosted-local` | Sentry web UI and API | Internal `9000/tcp` |
|
||||
| `sentry-self-hosted-relay-1` | `ghcr.io/getsentry/relay:nightly` | Event ingestion relay | Internal `3000/tcp` |
|
||||
| `sentry-self-hosted-postgres-1` | `postgres:14.23-bookworm` | Metadata database | Internal `5432/tcp` |
|
||||
| `sentry-self-hosted-clickhouse-1` | `clickhouse-self-hosted-local` | Event storage | Internal `8123/tcp`, `9000/tcp`, `9009/tcp` |
|
||||
| `sentry-self-hosted-redis-1` | `redis:6.2.20-alpine` | Cache and coordination | Internal `6379/tcp` |
|
||||
| `sentry-self-hosted-kafka-1` | `confluentinc/cp-kafka:7.6.6` | Event stream buffer | Internal `9092/tcp` |
|
||||
| `sentry-self-hosted-seaweedfs-1` | `chrislusf/seaweedfs:4.17_large_disk` | Object and attachment storage | Internal ports only |
|
||||
|
||||
---
|
||||
|
||||
## Public Access
|
||||
|
||||
Sentry is exposed via Nginx Proxy Manager:
|
||||
Domain:
|
||||
|
||||
- Domain: https://sentry.silveressence.net
|
||||
- Internal proxy container: sentry-self-hosted-nginx-1
|
||||
- Port: 9000 → 80 (internal nginx proxy mapping)
|
||||
```text
|
||||
sentry.silveressence.net
|
||||
```
|
||||
|
||||
Only the Nginx entry container is exposed externally. All other services are internal-only.
|
||||
Public route:
|
||||
|
||||
```text
|
||||
Internet
|
||||
-> Nginx Proxy Manager
|
||||
-> sentry-self-hosted-nginx-1
|
||||
-> Sentry web/API services
|
||||
```
|
||||
|
||||
Nginx Proxy Manager host:
|
||||
|
||||
| Setting | Value |
|
||||
| --- | --- |
|
||||
| Proxy host ID | `12` |
|
||||
| Forward scheme | `http` |
|
||||
| Forward host | `sentry-self-hosted-nginx-1` |
|
||||
| Forward port | `80` |
|
||||
| SSL Force | enabled |
|
||||
| HTTP/2 | enabled |
|
||||
| HSTS | disabled |
|
||||
| HSTS subdomains | disabled |
|
||||
| Block Exploits | enabled |
|
||||
| WebSocket | enabled |
|
||||
| Access List | none |
|
||||
| Status | enabled |
|
||||
|
||||
Only the Sentry web or nginx entry layer should be public. Internal services such as PostgreSQL, ClickHouse, Redis, Kafka, Snuba and workers must stay internal to the Sentry deployment.
|
||||
|
||||
---
|
||||
|
||||
## Architecture Overview
|
||||
## Architecture
|
||||
|
||||
Sentry is a distributed event processing pipeline:
|
||||
Sentry is a distributed event processing pipeline.
|
||||
|
||||
```
|
||||
Client Applications
|
||||
→ Relay
|
||||
→ Kafka
|
||||
→ Snuba
|
||||
→ ClickHouse
|
||||
→ Web API (UI + Query Layer)
|
||||
```text
|
||||
Applications
|
||||
-> Sentry SDK
|
||||
-> Relay
|
||||
-> Kafka
|
||||
-> Snuba
|
||||
-> ClickHouse
|
||||
-> Web UI and API
|
||||
```
|
||||
|
||||
---
|
||||
Core components:
|
||||
|
||||
## Core Components
|
||||
|
||||
### Web Interface
|
||||
- Container: sentry-self-hosted-web-1
|
||||
- Purpose: UI + API layer
|
||||
|
||||
### Relay
|
||||
- Container: sentry-self-hosted-relay-1
|
||||
- Purpose: event ingestion gateway
|
||||
|
||||
### Kafka
|
||||
- Container: sentry-self-hosted-kafka-1
|
||||
- Purpose: event streaming backbone
|
||||
|
||||
### Snuba
|
||||
- Multiple consumer containers
|
||||
- Purpose: event processing and query engine
|
||||
|
||||
### ClickHouse
|
||||
- Container: sentry-self-hosted-clickhouse-1
|
||||
- Purpose: high-performance event storage
|
||||
|
||||
### PostgreSQL
|
||||
- Container: sentry-self-hosted-postgres-1
|
||||
- Purpose: metadata storage
|
||||
|
||||
### Redis
|
||||
- Container: sentry-self-hosted-redis-1
|
||||
- Purpose: caching and coordination
|
||||
|
||||
### Workers
|
||||
Multiple background services:
|
||||
- taskworker
|
||||
- cron
|
||||
- cleanup
|
||||
- subscription consumers
|
||||
- metrics processors
|
||||
- ingestion pipelines
|
||||
|
||||
### Storage
|
||||
- SeaweedFS used for object/file storage
|
||||
* Web UI and API
|
||||
* Relay
|
||||
* Kafka
|
||||
* Snuba
|
||||
* ClickHouse
|
||||
* PostgreSQL
|
||||
* Redis
|
||||
* SeaweedFS
|
||||
* Task workers
|
||||
* Cron and cleanup jobs
|
||||
* Consumer and metrics processor services
|
||||
|
||||
---
|
||||
|
||||
## Networking
|
||||
|
||||
- Docker network: sentry-self-hosted_default
|
||||
- External exposure: ONLY nginx container via proxy network
|
||||
- All processing services remain isolated internally
|
||||
Internal network:
|
||||
|
||||
---
|
||||
```text
|
||||
sentry-self-hosted_default
|
||||
```
|
||||
|
||||
## Data Flow
|
||||
Verified subnet:
|
||||
|
||||
1. Application sends events to Sentry SDK
|
||||
2. Relay receives and validates events
|
||||
3. Kafka buffers event streams
|
||||
4. Snuba processes and transforms events
|
||||
5. ClickHouse stores event data
|
||||
6. Web service queries and displays results
|
||||
```text
|
||||
172.25.0.0/16
|
||||
```
|
||||
|
||||
Public proxy attachment:
|
||||
|
||||
* Sentry is reachable at `https://sentry.silveressence.net` through Nginx Proxy Manager.
|
||||
* The public route should terminate at the Sentry nginx or web entry container.
|
||||
* Internal Sentry infrastructure containers must not be exposed directly.
|
||||
|
||||
Security boundary:
|
||||
|
||||
* Treat Sentry as its own upstream-managed application cluster.
|
||||
* Do not attach Sentry databases or queues to shared application database networks unless there is a documented operational need.
|
||||
* Keep Sentry credentials, generated secrets and upstream `.env` files out of this repository.
|
||||
|
||||
---
|
||||
|
||||
## Data Storage
|
||||
|
||||
- PostgreSQL → metadata
|
||||
- ClickHouse → event storage
|
||||
- Kafka → event streaming buffer
|
||||
- Redis → caching/coordination
|
||||
- SeaweedFS → attachments and file objects
|
||||
Sentry stores data across multiple backing services:
|
||||
|
||||
| Component | Data role |
|
||||
| --- | --- |
|
||||
| PostgreSQL | Sentry metadata and relational state |
|
||||
| ClickHouse | Event and analytics storage |
|
||||
| Kafka | Event stream buffer |
|
||||
| Redis | Cache and coordination |
|
||||
| SeaweedFS | Attachments, files and object storage |
|
||||
|
||||
The upstream self-hosted installation directory and its Docker volumes are part of the recovery surface.
|
||||
|
||||
Verified configuration files:
|
||||
|
||||
```text
|
||||
/srv/docker/sentry/.env
|
||||
/srv/docker/sentry/docker-compose.yml
|
||||
/srv/docker/sentry/sentry/sentry.conf.py
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Backup Requirements
|
||||
|
||||
The following must be backed up:
|
||||
- PostgreSQL database volume
|
||||
- ClickHouse data volume
|
||||
- Sentry configuration files
|
||||
- Any persistent Kafka data (if enabled)
|
||||
Back up:
|
||||
|
||||
* `/srv/docker/sentry`
|
||||
* Sentry `.env` and generated configuration files
|
||||
* PostgreSQL volume
|
||||
* ClickHouse volume
|
||||
* Redis volume if persistence is enabled
|
||||
* Kafka data if persistence is enabled
|
||||
* SeaweedFS data
|
||||
* Nginx Proxy Manager route and certificate state for `sentry.silveressence.net`
|
||||
|
||||
Secrets:
|
||||
|
||||
* Sentry generated secrets must stay out of Git.
|
||||
* Do not move Sentry into the normal Infisical pattern unless the upstream deployment is intentionally redesigned.
|
||||
* Preserve the upstream Sentry secret files through secure server backup and restore procedures.
|
||||
|
||||
Restore validation:
|
||||
|
||||
```text
|
||||
Pending
|
||||
```
|
||||
|
||||
Restore validation should include:
|
||||
|
||||
* Web UI login
|
||||
* Project list visibility
|
||||
* DSN availability
|
||||
* Ingesting a test event
|
||||
* Viewing the test event in the UI
|
||||
* Confirming background consumers are healthy
|
||||
|
||||
---
|
||||
|
||||
## Management with slcompose
|
||||
## Operations
|
||||
|
||||
Use the upstream Sentry self-hosted commands from the installation directory.
|
||||
|
||||
Typical command pattern:
|
||||
|
||||
### Start Sentry
|
||||
```bash
|
||||
slcompose up sentry
|
||||
cd /srv/docker/sentry
|
||||
sudo docker compose ps
|
||||
sudo docker compose logs --tail=200
|
||||
sudo docker compose up -d
|
||||
```
|
||||
|
||||
### Stop Sentry
|
||||
```bash
|
||||
slcompose down sentry
|
||||
```
|
||||
|
||||
### Restart Sentry
|
||||
```bash
|
||||
slcompose restart sentry
|
||||
```
|
||||
|
||||
### View Live Logs
|
||||
```bash
|
||||
slcompose logs sentry
|
||||
```
|
||||
|
||||
### View Recent Logs
|
||||
```bash
|
||||
slcompose logs-tail sentry 500
|
||||
```
|
||||
|
||||
### View Injected Environment Variables
|
||||
```bash
|
||||
slcompose env sentry
|
||||
```
|
||||
Do not operate Sentry with `slcompose` unless the deployment is intentionally converted away from the upstream installer model.
|
||||
|
||||
---
|
||||
|
||||
## Important Notes
|
||||
## Updates
|
||||
|
||||
- This is a distributed system; services must not be split or partially deployed.
|
||||
- Updates must preserve service group integrity.
|
||||
- Only the web/nginx layer should be exposed publicly.
|
||||
- All 70+ containers are managed as a single atomic unit via slcompose.
|
||||
Use the upstream Sentry self-hosted update workflow.
|
||||
|
||||
Before updating:
|
||||
|
||||
* Back up configuration and volumes.
|
||||
* Review upstream release notes.
|
||||
* Confirm available disk space.
|
||||
* Verify the current deployment is healthy.
|
||||
|
||||
After updating:
|
||||
|
||||
* Confirm all containers are healthy.
|
||||
* Verify `https://sentry.silveressence.net`.
|
||||
* Send a test event from an application or SDK test client.
|
||||
* Review worker, consumer, Kafka, Snuba and ClickHouse logs.
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
Known verified facts:
|
||||
|
||||
* Sentry was installed using the upstream self-hosted `install.sh`.
|
||||
* Sentry is available at `https://sentry.silveressence.net`.
|
||||
* Sentry install directory is `/srv/docker/sentry`.
|
||||
* Sentry nginx entry container is `sentry-self-hosted-nginx-1`.
|
||||
* Nginx Proxy Manager forwards `sentry.silveressence.net` to `http://sentry-self-hosted-nginx-1:80`.
|
||||
* `sentry-self-hosted-nginx-1` publishes `0.0.0.0:9000 -> 80/tcp`.
|
||||
* `sentry-self-hosted_default` subnet is `172.25.0.0/16`.
|
||||
* Sentry is treated as the exception to the standard SilverLinux `slcompose` and Infisical service pattern.
|
||||
|
||||
Recommended next runtime capture:
|
||||
|
||||
```bash
|
||||
docker ps --filter "name=sentry" --format "table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}"
|
||||
docker network inspect proxy sentry-self-hosted_default --format 'network={{.Name}} containers={{range $id,$c := .Containers}}{{$c.Name}} {{end}}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [orchestration.md](orchestration.md) — Service orchestration with slcompose
|
||||
- [AI_CONTEXT.md](AI_CONTEXT.md) — Infrastructure overview
|
||||
- [services.md](services.md) — All services on SilverLinux
|
||||
* [docs/services.md](services.md)
|
||||
* [docs/domains.md](domains.md)
|
||||
* [docs/network.md](network.md)
|
||||
* [docs/security.md](security.md)
|
||||
* [docs/backups.md](backups.md)
|
||||
* [docs/secrets.md](secrets.md)
|
||||
|
||||
Reference in New Issue
Block a user