silverlinux-infra/docs/sentry.md

# Sentry

## Overview

Sentry is the centralized error tracking and observability platform for SilverLinux-hosted applications.

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.

---

## Runtime Stack

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

Domain:

```text
sentry.silveressence.net
```

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

Sentry is a distributed event processing pipeline.

```text
Applications
  -> Sentry SDK
  -> Relay
  -> Kafka
  -> Snuba
  -> ClickHouse
  -> Web UI and API
```

Core components:

* Web UI and API
* Relay
* Kafka
* Snuba
* ClickHouse
* PostgreSQL
* Redis
* SeaweedFS
* Task workers
* Cron and cleanup jobs
* Consumer and metrics processor services

---

## Networking

Internal network:

```text
sentry-self-hosted_default
```

Verified subnet:

```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

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

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

---

## Operations

Use the upstream Sentry self-hosted commands from the installation directory.

Typical command pattern:

```bash
cd /srv/docker/sentry
sudo docker compose ps
sudo docker compose logs --tail=200
sudo docker compose up -d
```

Do not operate Sentry with `slcompose` unless the deployment is intentionally converted away from the upstream installer model.

---

## Updates

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

* [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)