Instalación de Sentry Self-

Instalación de software — paso a paso

Sentry self-hosted utiliza Docker y Docker Compose para la orquestación de sus numerosos componentes, incluyendo PostgreSQL, Redis, ClickHouse, Kafka y otros. Instalaremos Docker Engine y Docker Compose, y luego utilizaremos el instalador oficial de Sentry para desplegar toda la infraestructura.

Todos los comandos se ejecutan como un usuario con privilegios sudo (en nuestro caso, sentryuser).

1. Instalación de Docker Engine (válido para 2026)

Instalaremos Docker desde el repositorio oficial de Docker, lo que garantiza la obtención de las versiones más recientes y estables. Para 2026, las versiones actuales serán Docker Engine 25.x o 26.x.

# Paso 1: Eliminamos versiones antiguas de Docker (si existen)
sudo apt remove docker docker-engine docker.io containerd runc -y

# Paso 2: Instalamos los paquetes necesarios para la instalación por HTTPS
sudo apt install ca-certificates curl gnupg lsb-release -y

# Paso 3: Añadimos la clave GPG oficial de Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Paso 4: Añadimos el repositorio de Docker a las fuentes de APT
echo \
  "deb [arch="$(dpkg --print-architecture)" signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  "$(. /etc/os-release && echo "$VERSION_CODENAME")" stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Paso 5: Actualizamos la lista de paquetes después de añadir el repositorio
sudo apt update

# Paso 6: Instalamos Docker Engine, containerd y Docker Compose (cli)
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

• Elimina instalaciones anteriores de Docker.
• Instala los paquetes necesarios para trabajar con repositorios HTTPS.
• Añade la clave GPG de Docker para verificar la autenticidad de los paquetes.
• Añade el repositorio oficial de Docker para Ubuntu.
• Actualiza la caché de paquetes.
• Instala Docker Engine (docker-ce), el cliente Docker (docker-ce-cli), el entorno de ejecución de contenedores (containerd.io) y los plugins para build y compose (docker-buildx-plugin, docker-compose-plugin).

2. Adición del usuario al grupo docker

Para evitar usar sudo cada vez que trabaje con Docker, añada su usuario al grupo docker.

sudo usermod -aG docker sentryuser
newgrp docker

• Añade sentryuser al grupo docker.
• Aplica los cambios de grupo sin necesidad de reiniciar la sesión.

3. Verificación de la instalación de Docker

Asegúrese de que Docker esté instalado y funcionando correctamente.

docker run hello-world

Ejecuta el contenedor de prueba hello-world. Si ve el mensaje de bienvenida, Docker está instalado correctamente.

4. Instalación de Sentry (válido para 2026)

Sentry proporciona un script conveniente para desplegar la versión self-hosted. Este genera automáticamente todos los archivos necesarios de Docker Compose y configuración, e instala PostgreSQL y Redis como parte de su infraestructura.

# Paso 1: Creamos el directorio para Sentry
mkdir ~/sentry && cd ~/sentry

# Paso 2: Descargamos el script de instalación de Sentry (la versión 24.x/25.x será la actual para 2026)
# Siempre verifique la versión actual en GitHub Sentry self-hosted
curl -sL https://install.sentry.io/ | bash

• Crea el directorio sentry en la carpeta de inicio del usuario y se mueve a él.
• Descarga y ejecuta el script oficial de instalación de Sentry. El script le guiará a través del proceso, le hará preguntas sobre el nombre de dominio y generará todos los archivos.

Durante la ejecución del script, se le pedirá que introduzca un nombre de dominio para Sentry (por ejemplo, sentry.yourdomain.com) y que acepte la instalación. El script descargará las imágenes Docker necesarias (incluyendo PostgreSQL, Redis, ClickHouse, Kafka, Zookeeper) y generará los archivos docker-compose.yml y .env.

5. Inicio de Sentry

Después de ejecutar con éxito el script de instalación de Sentry, puede iniciar todos sus componentes utilizando Docker Compose.

# Iniciamos todos los servicios de Sentry en segundo plano
docker compose up -d

Inicia todos los contenedores definidos en docker-compose.yml en segundo plano (modo detached). Esto puede tardar un tiempo en el primer inicio, ya que Docker descargará todas las imágenes necesarias.

6. Creación de un administrador de Sentry

Una vez que todos los contenedores de Sentry estén en funcionamiento, deberá crear el primer usuario administrativo para acceder a la interfaz web.

docker compose run --rm web createuser

Ejecuta el comando createuser dentro del contenedor web de Sentry, lo que permite crear un nuevo usuario de Sentry. Se le pedirá que introduzca un correo electrónico, una contraseña y que confirme si es un superusuario.

7. Verificación del estado de los contenedores

Asegúrese de que todos los contenedores de Sentry estén funcionando.

docker compose ps

Muestra una lista de todos los servicios gestionados por Docker Compose y su estado actual. Todos los servicios deben estar en estado running.

En este punto, los componentes principales de Sentry están instalados y en funcionamiento. A continuación, pasaremos a la configuración.

Copias de seguridad y mantenimiento

Las copias de seguridad fiables y el mantenimiento regular son clave para cualquier sistema en producción, y Sentry no es una excepción. La pérdida de datos de errores puede ser crítica para la depuración y el monitoreo.

Qué respaldar

Para una recuperación completa de Sentry, debe respaldar los siguientes datos:

1. Base de datos PostgreSQL: Almacenamiento principal de todos los datos de Sentry (proyectos, eventos, usuarios, configuraciones).
2. Datos de Redis: Aunque Redis se utiliza principalmente para el almacenamiento en caché y las colas, también puede almacenar información temporal pero importante.
3. Datos de ClickHouse: Almacena datos de eventos sin procesar para Snuba, lo cual es importante para el análisis y la búsqueda.
4. Archivos de configuración de Sentry: Los archivos .env, config.yml y docker-compose.yml.
5. Volúmenes de Docker: Todos los volúmenes utilizados por Sentry (sentry-postgres, sentry-redis, sentry-data, sentry-attachments, sentry-clickhouse, sentry-kafka, etc.).

La forma más sencilla es respaldar todos los volúmenes de Docker relacionados con Sentry, ya que contienen datos de PostgreSQL, Redis, ClickHouse y otros archivos importantes.

Script simple de copia de seguridad automática (cron + restic / borg / rsync)

Crearemos un script simple que archivará todos los volúmenes de Docker y archivos de configuración necesarios, y luego los enviará a una ubicación segura. Por ejemplo, usaremos rsync para copiar a otro servidor o a un almacenamiento compatible con S3. Para copias de seguridad más avanzadas, considere restic o borgbackup.

Se asume que tiene un servidor separado o un almacenamiento compatible con S3 (por ejemplo, MinIO, Wasabi, Backblaze B2) para almacenar las copias de seguridad. Si utiliza otro servidor, configure el acceso SSH por clave sin contraseña para el usuario que realizará las copias de seguridad.

Cree el archivo backup_sentry.sh en el directorio ~/sentry/scripts:

mkdir -p ~/sentry/scripts
nano ~/sentry/scripts/backup_sentry.sh

Crea el directorio para los scripts y abre el archivo para editarlo.

#!/bin/bash

# Переменные
BACKUP_DIR="/var/backups/sentry"
SENTRY_ROOT_DIR="/home/sentryuser/sentry" # Путь к вашей директории Sentry
TIMESTAMP=$(date +%Y%m%d%H%M%S)
BACKUP_FILE="$BACKUP_DIR/sentry_backup_$TIMESTAMP.tar.gz"
RETENTION_DAYS=7 # Сколько дней хранить бэкапы

# Настройки удаленного хранилища (пример для rsync по SSH)
REMOTE_USER="backupuser"
REMOTE_HOST="your_backup_server_ip"
REMOTE_PATH="/mnt/backups/sentry_backups"

# --- Начало процесса бэкапа ---
echo "Starting Sentry backup at $TIMESTAMP..."

# 1. Останавливаем Sentry для консистентности данных (опционально, но рекомендуется для БД)
# Если Sentry очень нагружен, рассмотрите бэкап без остановки, используя pg_dump и redis-cli BGSAVE
# docker compose stop # Можно останавливать только postgres и redis, если хотите минимизировать даунтайм
# docker compose stop postgres redis

# 2. Создаем директорию для бэкапов, если ее нет
sudo mkdir -p "$BACKUP_DIR"
sudo chown sentryuser:sentryuser "$BACKUP_DIR"

# 3. Бэкап томов Docker
# Для PostgreSQL: делаем дамп базы данных
echo "Dumping PostgreSQL database..."
docker compose exec -T postgres pg_dumpall -U postgres > "$BACKUP_DIR/sentry_postgres_dump_$TIMESTAMP.sql"
if [ $? -ne 0 ]; then
    echo "ERROR: PostgreSQL dump failed. Exiting."
    # docker compose start postgres redis # Запускаем обратно, если останавливали
    exit 1
fi

# Для Redis: делаем сохранение RDB файла
echo "Saving Redis RDB file..."
docker compose exec -T redis redis-cli BGSAVE
# Дожидаемся завершения BGSAVE (несколько секунд)
sleep 5
docker cp sentry-redis-1:/data/dump.rdb "$BACKUP_DIR/sentry_redis_dump_$TIMESTAMP.rdb"
if [ $? -ne 0 ]; then
    echo "ERROR: Redis dump failed. Exiting."
    # docker compose start postgres redis # Запускаем обратно, если останавливали
    exit 1
fi

# Бэкап всех остальных Docker томов Sentry
# Можно использовать 'docker volume ls -q' и 'docker run --rm -v VOLUME_NAME:/volume -v /path/to/backup:/backup alpine tar czf /backup/volume.tar.gz /volume'
# Но проще бэкапить всю директорию SENTRY_ROOT_DIR, которая содержит docker-compose.yml и .env,
# а также все локальные тома (если они созданы как bind mounts или в этой директории)

echo "Archiving Sentry configuration and data volumes..."
# Создаем временную директорию для архивации Docker томов
TEMP_VOLUMES_DIR="$BACKUP_DIR/volumes_$TIMESTAMP"
mkdir -p "$TEMP_VOLUMES_DIR"

# Копируем .env, docker-compose.yml и другие важные файлы
cp "$SENTRY_ROOT_DIR/.env" "$TEMP_VOLUMES_DIR/"
cp "$SENTRY_ROOT_DIR/config.yml" "$TEMP_VOLUMES_DIR/"
cp "$SENTRY_ROOT_DIR/docker-compose.yml" "$TEMP_VOLUMES_DIR/"
cp -R "$SENTRY_ROOT_DIR/caddy_logs" "$TEMP_VOLUMES_DIR/" # Если Caddy логи не в томе

# Копируем данные persistent томов Sentry (пути могут отличаться, проверьте через 'docker volume inspect ')
# Это более сложный шаг, так как тома могут быть вне SENTRY_ROOT_DIR.
# Проще всего использовать tar для конкретных томов или просто бэкапить всю директорию SENTRY_ROOT_DIR
# Если у вас используются именованные тома (как по умолчанию в Sentry), то их нужно бэкапить отдельно
# Например, для sentry-data:
# docker run --rm -v sentry-data:/data -v "$TEMP_VOLUMES_DIR":/backup ubuntu tar czf /backup/sentry-data.tar.gz -C /data .
# Аналогично для sentry-attachments, sentry-clickhouse-data и т.д.

# Для простоты и если тома не bind-mounts, а Docker-managed volumes, можно просто бэкапить всю директорию Sentry
# с конфигами, а данные БД и Redis уже сделали дампом.
# Для полных Docker-managed volumes, скрипт будет сложнее, с использованием 'docker run --rm -v :/vol ... tar'
# Для этого примера, мы сосредоточимся на конфигах и дампе БД/Redis, что достаточно для восстановления.

# Архивация всех бэкап-файлов
echo "Creating final archive..."
cd "$BACKUP_DIR"
tar -czf "$BACKUP_FILE" sentry_postgres_dump_"$TIMESTAMP".sql sentry_redis_dump_"$TIMESTAMP".rdb volumes_"$TIMESTAMP"/
cd "$SENTRY_ROOT_DIR" # Возвращаемся в исходную директорию

# 4. Загрузка бэкапа на удаленный сервер (rsync)
echo "Uploading backup to remote server..."
rsync -avz "$BACKUP_FILE" "$REMOTE_USER@$REMOTE_HOST:$REMOTE_PATH"
if [ $? -ne 0 ]; then
    echo "ERROR: Failed to upload backup to remote server."
fi

# 5. Удаление старых бэкапов
echo "Removing old backups..."
find "$BACKUP_DIR" -type f -name "sentry_backup_.tar.gz" -mtime +$RETENTION_DAYS -delete
find "$BACKUP_DIR" -type f -name "sentry_postgres_dump_.sql" -mtime +$RETENTION_DAYS -delete
find "$BACKUP_DIR" -type f -name "sentry_redis_dump_.rdb" -mtime +$RETENTION_DAYS -delete
find "$BACKUP_DIR" -type d -name "volumes_" -mtime +$RETENTION_DAYS -exec rm -rf {} + # Удаляем временные директории

# 6. Запускаем Sentry обратно (если останавливали)
# docker compose start # Или только postgres redis
echo "Sentry backup finished."

El script realiza un volcado de PostgreSQL y Redis, archiva los archivos de configuración y sube la copia de seguridad a un servidor remoto. También elimina las copias de seguridad antiguas. Reemplace your_backup_server_ip, backupuser y [email protected] con sus propios datos.

Haga el script ejecutable:

chmod +x ~/sentry/scripts/backup_sentry.sh

Hace el script ejecutable.

Dónde almacenar

• Servicio externo compatible con S3: Almacenamientos en la nube (AWS S3, Google Cloud Storage, Backblaze B2, DigitalOcean Spaces, Linode Object Storage) son una opción fiable y escalable. Para esto, necesitará una herramienta como s3cmd o rclone.
• VPS separado: Puede utilizar otro VPS menos potente para almacenar las copias de seguridad, copiándolas por SSH con rsync, como se muestra en el ejemplo anterior.
• Disco local (con precaución): No se recomienda almacenar las copias de seguridad en el mismo servidor que Sentry, ya que en caso de fallo del disco, perderá tanto Sentry como las copias de seguridad. Esto puede ser solo una solución temporal antes de transferirlas a un medio externo.

Actualizaciones: rolling vs. ventana de mantenimiento

Actualizar Sentry autoalojado es un procedimiento importante. Sentry lanza nuevas versiones con frecuencia, y su actualización generalmente incluye la actualización de imágenes de Docker y la migración de la base de datos.

• Ventana de mantenimiento: Este es el enfoque más común y seguro para Sentry autoalojado. Durante la ventana de mantenimiento, detiene todos los servicios de Sentry, realiza la actualización, las migraciones de la base de datos y luego los inicia de nuevo. Esto asegura que todos los componentes se actualicen sincrónicamente y que las migraciones se realicen sin conflictos.

  
  # В директории ~/sentry
  docker compose down # Detiene todos los servicios
  docker compose pull # Descarga las nuevas imágenes de Docker
  docker compose run --rm web upgrade # Ejecuta las migraciones de la base de datos
  docker compose up -d # Inicia todos los servicios de Sentry
  

  Procedimiento estándar para actualizar Sentry. Se recomienda realizarlo regularmente para utilizar las últimas funciones y correcciones de seguridad.

• Actualizaciones continuas (rolling updates): Para Sentry, esto es más difícil de implementar debido a la estrecha relación entre sus componentes y los posibles cambios en el esquema de la base de datos. Generalmente, las actualizaciones continuas requieren una arquitectura más compleja (por ejemplo, un clúster de Kubernetes) y no siempre son aplicables a una instalación estándar de Docker Compose sin tiempo de inactividad. Para la mayoría de los usuarios autoalojados, el enfoque de ventana de mantenimiento es preferible.

Siempre lea la documentación oficial de Sentry antes de actualizar, ya que puede haber instrucciones específicas para versiones concretas.

Solución de problemas + Preguntas frecuentes

Incluso con una configuración cuidadosa, pueden surgir problemas. Esta sección le ayudará a diagnosticar y resolver las preguntas más comunes al trabajar con Sentry autoalojado.

1. ¿Qué configuración mínima de VPS es adecuada para Sentry?

Para proyectos pequeños (hasta 1000 eventos por minuto), se recomienda un VPS mínimo con 4 núcleos de CPU, 8 GB de RAM y 100-200 GB de SSD. Sin embargo, Sentry es bastante intensivo en recursos. Si espera una carga más alta o desea garantizar un funcionamiento fluido sin ralentizaciones, es mejor considerar 6-8 núcleos de CPU, 16-32 GB de RAM y 300-500 GB de SSD NVMe. Un disco SSD es una condición obligatoria para un buen rendimiento debido a las intensas operaciones de entrada/salida con la base de datos y ClickHouse.

2. ¿Qué elegir: VPS o dedicado para esta tarea?

Para la mayoría de los proyectos y equipos medianos, un VPS será suficiente y es una solución más económica. El VPS proporciona un buen aislamiento y escalabilidad. Un servidor dedicado (dedicated) debe considerarse si tiene una carga muy alta (decenas de miles de eventos por minuto), requisitos estrictos de rendimiento, aislamiento de recursos o requisitos regulatorios específicos. Proporciona control total sobre el hardware, pero requiere un mayor nivel de administración.

3. La interfaz de usuario de Sentry no está disponible o muestra un error 502/503. ¿Qué hacer?

Verifique el estado de los contenedores Docker: docker compose ps. Asegúrese de que todos los contenedores (especialmente web, postgres, redis, caddy) estén en estado running. Verifique los logs de los servicios: docker compose logs web, docker compose logs caddy, docker compose logs postgres. Causas frecuentes: falta de memoria (Sentry puede consumir mucha RAM), configuración incorrecta de Caddy, problemas con la base de datos.

4. No puedo iniciar sesión en Sentry después de crear un usuario.

Asegúrese de haber creado un superusuario usando el comando docker compose run --rm web createuser. Verifique la exactitud de las credenciales ingresadas. Si olvidó su contraseña, puede restablecerla usando el mismo comando createuser e indicando un correo electrónico existente, Sentry le ofrecerá restablecer la contraseña.

5. Los eventos no llegan a Sentry, aunque configuré el SDK.

Verifique los siguientes puntos: 1. ¿El DSN está correctamente especificado en su aplicación? El DSN se puede encontrar en la configuración del proyecto en la interfaz de usuario de Sentry. 2. ¿Su servidor Sentry es accesible desde el exterior (DNS, firewall)? Intente curl -v https://sentry.yourdomain.com desde el servidor donde se ejecuta la aplicación. 3. Verifique los logs de Sentry (especialmente los servicios web y worker) en busca de errores al recibir eventos: docker compose logs web. 4. Asegúrese de que todos los componentes de Sentry estén funcionando: docker compose ps.

6. Sentry funciona lento o se "ralentiza".

El funcionamiento lento de Sentry a menudo está relacionado con la falta de recursos. Verifique el uso de CPU, RAM y operaciones de disco en su VPS. Use los comandos htop, free -h, iostat -x 1. Si algún recurso está cerca del 100%, considere aumentar los recursos del VPS. También verifique los logs de Sentry en busca de errores que puedan ralentizar el funcionamiento (por ejemplo, problemas con PostgreSQL o ClickHouse).

7. ¿Cómo actualizar Sentry a una nueva versión?

El proceso de actualización de Sentry incluye detener todos los servicios, descargar nuevas imágenes Docker, ejecutar migraciones de la base de datos y reiniciar. Siempre siga la documentación oficial de Sentry para la versión específica, pero la secuencia general de comandos es: docker compose down, docker compose pull, docker compose run --rm web upgrade, docker compose up -d. Asegúrese de tener una copia de seguridad actualizada antes de comenzar la actualización.

8. ¿Cómo limpiar datos antiguos de Sentry?

Sentry proporciona un comando para limpiar datos antiguos. Puede ejecutarlo manualmente o configurarlo como una tarea cron regular. Ejemplo de comando para eliminar datos de más de 90 días:

docker compose run --rm web cleanup --days 90

Este comando elimina eventos y datos relacionados que tienen más de 90 días. Se recomienda ejecutarlo regularmente para mantener el rendimiento y ahorrar espacio en disco.

Conclusiones y próximos pasos

¡Felicidades! Ha desplegado y configurado con éxito su propia instalación de Sentry en su VPS, utilizando Docker, PostgreSQL y Redis. Ahora tiene una potente herramienta para monitorear errores y rendimiento, que le proporciona control total sobre sus datos e infraestructura. Esto aumentará significativamente la fiabilidad de sus aplicaciones y la eficiencia de su equipo.

Próximos pasos:

• Integración de proyectos: Agregue todos sus proyectos a Sentry e integre el SDK en sus aplicaciones para comenzar a recopilar datos de errores.
• Configuración de alertas: Configure alertas por correo electrónico, Slack, PagerDuty u otros canales para que su equipo sea notificado rápidamente sobre nuevos problemas.
• Monitoreo de Sentry: Configure el monitoreo del rendimiento y el estado de Sentry (uso de recursos del VPS, estado de los contenedores Docker) utilizando herramientas como Prometheus/Grafana o Zabbix.
• Escalado: A medida que su proyecto crezca y aumente el volumen de eventos, considere escalar Sentry aumentando los recursos del VPS o migrando a un servidor dedicado.