Sentry es una plataforma de seguimiento de errores y rendimiento: recoge las excepciones de tus aplicaciones con su traza completa, las agrupa en incidencias y avisa al equipo cuando aparece un error nuevo. La edición self-hosted es la misma plataforma empaquetada como un conjunto de contenedores Docker, de modo que los datos de errores nunca salen de tu infraestructura. En este tutorial instalarás Sentry self-hosted en Ubuntu 24.04, lo publicarás detrás de Nginx con un certificado de Let's Encrypt, configurarás el envío de correo y comprobarás que recibe eventos desde una aplicación Python.

Requisitos previos

Para seguir esta guía necesitas:

  • Un servidor con Ubuntu 24.04 LTS dedicado a Sentry, por ejemplo un VPS de CubePath, con un usuario no root con privilegios sudo.
  • Al menos 4 vCPU, 16 GB de RAM y 20 GB libres en disco. Con menos memoria la instalación falla o los contenedores se reinician en bucle. El proyecto recomienda además 16 GB de swap.
  • Docker Engine y el plugin de Docker Compose instalados desde el repositorio oficial de Docker, con tu usuario añadido al grupo docker. Las versiones de los paquetes de Docker de Ubuntu suelen quedarse cortas para los requisitos de Compose de Sentry.
  • Un dominio o subdominio, por ejemplo sentry.your_domain, con un registro DNS de tipo A que apunte a la IP pública del servidor.
  • Una cuenta SMTP (la de tu proveedor de correo transaccional o tu propio servidor) si quieres que Sentry envíe alertas por email.

A lo largo de la guía, sustituye sentry.your_domain por tu subdominio real.

Paso 1: Preparar el servidor

Comprueba primero la memoria y la versión de Docker Compose, ya que el instalador se detiene si no cumplen el mínimo:

free -h
docker compose version

               total        used        free      shared  buff/cache   available
Mem:            15Gi       512Mi        14Gi       1.0Mi       1.1Gi        14Gi
Swap:             0B          0B          0B
Docker Compose version v2.39.2

Si el servidor no tiene swap, crea un archivo de 16 GB y actívalo de forma permanente:

sudo fallocate -l 16G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Vuelve a ejecutar free -h y comprueba que la línea Swap muestra 16Gi.

Configura también el cortafuegos. Solo necesitas SSH y HTTP/HTTPS para Nginx; el puerto interno de Sentry quedará ligado a 127.0.0.1:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Paso 2: Descargar Sentry self-hosted

Sentry self-hosted se distribuye como un repositorio de Git con un script de instalación. Clónalo en /opt/sentry:

sudo git clone https://github.com/getsentry/self-hosted.git /opt/sentry
sudo chown -R "$USER": /opt/sentry
cd /opt/sentry

No instales desde la rama master: usa siempre una versión publicada. Consulta la última en la página de releases del repositorio o lista las etiquetas más recientes:

git tag --sort=-v:refname | head -5

25.9.0
25.8.0
25.7.0
25.6.2
25.6.1

Cambia a la versión más reciente de la lista (sustituye 25.9.0 por la que te aparezca):

git checkout 25.9.0

Paso 3: Limitar Sentry a la interfaz local

Por defecto, el contenedor Nginx interno de Sentry escucha en el puerto 9000 de todas las interfaces. Como vas a poner delante el Nginx del sistema con HTTPS, crea un archivo .env.custom a partir del .env de la versión y cambia la variable SENTRY_BIND. Usar .env.custom evita conflictos con Git al actualizar:

cp .env .env.custom
nano .env.custom

Localiza la línea SENTRY_BIND y déjala así:

SENTRY_BIND=127.0.0.1:9000

En ese mismo archivo puedes ajustar SENTRY_EVENT_RETENTION_DAYS, que por defecto guarda los eventos 90 días. Reducirlo a 30 ahorra mucho disco en instalaciones con tráfico alto.

Paso 4: Ejecutar el instalador

El script install.sh comprueba los requisitos, descarga las imágenes, genera la clave secreta, ejecuta las migraciones de base de datos y, al final, te pide crear el primer usuario administrador. Tarda entre 10 y 30 minutos según el servidor:

./install.sh

Cuando pregunte si quieres crear un usuario, responde y e introduce tu email y una contraseña robusta. Esa cuenta será superusuario de la instancia. Al terminar, el script muestra You're all done! junto con el comando para arrancar Sentry.

Arranca todos los servicios con el archivo de variables personalizado:

docker compose --env-file .env --env-file .env.custom up --wait

La opción --wait no devuelve el control hasta que los contenedores con comprobación de salud están sanos. Verifica que Sentry responde en local:

curl -sI http://127.0.0.1:9000/auth/login/ | head -1

HTTP/1.1 200 OK

Los contenedores tienen la política restart: unless-stopped, así que volverán a arrancar solos tras un reinicio del servidor.

Paso 5: Publicar Sentry con Nginx y HTTPS

Instala Nginx y Certbot con su plugin para Nginx:

sudo apt update
sudo apt install nginx certbot python3-certbot-nginx

Crea el bloque de servidor para Sentry:

sudo nano /etc/nginx/sites-available/sentry

server {
    listen 80;
    listen [::]:80;
    server_name sentry.your_domain;

    # Los source maps y los envíos grandes de eventos superan el límite por defecto
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:9000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Activa el sitio, comprueba la sintaxis y recarga Nginx:

sudo ln -s /etc/nginx/sites-available/sentry /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Solicita el certificado. Certbot añadirá el bloque listen 443 ssl y la redirección de HTTP a HTTPS en el mismo archivo:

sudo certbot --nginx -d sentry.your_domain

Comprueba que el sitio responde por HTTPS:

curl -sI https://sentry.your_domain/auth/login/ | head -1

HTTP/2 200

Paso 6: Configurar la URL pública y el correo

Sentry necesita conocer su URL pública para generar enlaces y DSN correctos, y un servidor SMTP para enviar alertas. Ambas opciones van en sentry/config.yml:

nano /opt/sentry/sentry/config.yml

Busca las claves correspondientes (algunas están comentadas) y déjalas con tus datos:

system.url-prefix: 'https://sentry.your_domain'

mail.backend: 'smtp'
mail.host: 'smtp.your_mail_provider.com'
mail.port: 587
mail.username: 'sentry@your_domain'
mail.password: 'your_smtp_password'
mail.use-tls: true
mail.use-ssl: false
mail.from: 'sentry@your_domain'

Sustituye your_smtp_password por la contraseña real de la cuenta SMTP. Después indica a Django que está detrás de un proxy con HTTPS. Abre sentry/sentry.conf.py:

nano /opt/sentry/sentry/sentry.conf.py

Busca el bloque de opciones para SSL (viene comentado) y descoméntalo, añadiendo tu dominio a CSRF_TRUSTED_ORIGINS:

SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
USE_X_FORWARDED_HOST = True
SESSION_COOKIE_SECURE = True
CSRF_COOKIE_SECURE = True
SOCIAL_AUTH_REDIRECT_IS_HTTPS = True

CSRF_TRUSTED_ORIGINS = ["https://sentry.your_domain"]

Reinicia los servicios para que lean la nueva configuración:

cd /opt/sentry
docker compose --env-file .env --env-file .env.custom restart

Entra en https://sentry.your_domain con el usuario que creaste en el paso 4. En Admin > Mail verás la configuración SMTP activa y un botón para enviar un correo de prueba a tu dirección.

Paso 7: Crear un proyecto y enviar el primer error

En la interfaz web, ve a Projects > Create Project, elige la plataforma Python, ponle un nombre y pulsa Create Project. Sentry mostrará el DSN del proyecto, una URL con este formato:

https://[email protected]_domain/2

Para probarlo, crea en tu equipo (o en el propio servidor) un entorno virtual de Python e instala el SDK. En Ubuntu 24.04 es obligatorio usar un entorno virtual para instalar paquetes con pip:

sudo apt install python3-venv
python3 -m venv ~/sentry-test
~/sentry-test/bin/pip install sentry-sdk

Crea un script que inicializa el SDK y provoca una excepción:

nano ~/sentry-test/prueba.py

import sentry_sdk

sentry_sdk.init(
    dsn="https://[email protected]_domain/2",
    environment="pruebas",
    release="[email protected]",
    traces_sample_rate=1.0,
)

division = 1 / 0

Sustituye el DSN por el de tu proyecto y ejecútalo:

~/sentry-test/bin/python ~/sentry-test/prueba.py

El script termina con un ZeroDivisionError, que es lo esperado. El SDK envía el evento antes de salir, y en unos segundos aparecerá en Issues una incidencia ZeroDivisionError: division by zero con la traza, el entorno pruebas y la versión [email protected].

En una aplicación real, llama a sentry_sdk.init() lo antes posible al arrancar, y baja traces_sample_rate a un valor como 0.1 en producción para no enviar el 100 % de las transacciones. Si usas Django, Flask o FastAPI, el SDK activa automáticamente su integración al detectar el framework instalado.

Paso 8: Mantener y actualizar Sentry

Sentry self-hosted se actualiza cambiando a una etiqueta más nueva y volviendo a ejecutar el instalador, que aplica las migraciones necesarias. Antes de actualizar, lee las notas de la versión: algunas son paradas obligatorias (hard stops) por las que hay que pasar antes de saltar a versiones posteriores.

cd /opt/sentry
docker compose --env-file .env --env-file .env.custom down
git fetch --tags
git checkout 25.10.0
./install.sh --skip-user-creation
docker compose --env-file .env --env-file .env.custom up --wait

Si .env cambió en la nueva versión, revisa las diferencias con tu .env.custom con diff .env .env.custom y traslada las variables nuevas.

Para saber cuánto disco ocupan los volúmenes de Docker, incluidos los de Postgres, ClickHouse y Kafka que usa Sentry:

docker system df -v | grep sentry

La limpieza de eventos antiguos la hace automáticamente el contenedor sentry-cleanup según SENTRY_EVENT_RETENTION_DAYS.

Solución de problemas

El instalador se detiene por falta de recursos. El script comprueba la RAM y la CPU al inicio. Si el servidor tiene menos de lo requerido, amplía el plan en lugar de forzar la instalación: con poca memoria, ClickHouse y Kafka se reinician constantemente y se pierden eventos.

La web da error 403 CSRF al iniciar sesión. Falta tu dominio en CSRF_TRUSTED_ORIGINS o no has reiniciado tras editar sentry.conf.py. Revisa el paso 6.

Los eventos no aparecen. Comprueba que el DSN usa https://sentry.your_domain y no la IP o el puerto 9000, y revisa los registros de los servicios que reciben y procesan eventos:

docker compose --env-file .env --env-file .env.custom logs --tail 100 relay
docker compose --env-file .env --env-file .env.custom logs --tail 100 web

Un contenedor se reinicia en bucle. Lista el estado de todos los servicios y mira los registros del que falla:

docker compose --env-file .env --env-file .env.custom ps

Un contenedor en estado Restarting suele indicar falta de memoria o de disco; compruébalo con free -h y df -h.

Conclusión

Ya tienes Sentry self-hosted funcionando en Ubuntu 24.04, publicado con HTTPS, con envío de correo configurado y recibiendo errores de una aplicación Python. A partir de aquí puedes crear reglas de alerta en Alerts para avisar por email cuando aparezca una incidencia nueva, instalar el SDK en tus otros proyectos (JavaScript, Go, PHP) usando el DSN de cada uno, y programar copias de seguridad de los volúmenes de Docker antes de cada actualización.