Self-host Sentry
All of Sentry on your own VM, behind exe.dev login.
Shelley handles the setup. About 30 minutes. Needs a 100 GB disk: Shelley sends you a link to grow it.
Prefer a terminal?
curl -fsSL https://exe-staging.dev/deploy/sentry/prompt.txt | ssh exe.dev new --disk=100GB --prompt=/dev/stdinSentry is the error tracker most SDKs are written for: an SDK in your app catches every exception and sends the stack trace, request and release to a dashboard that groups them into issues, with performance traces, Session Replay, profiling, crons and uptime checks beside them. Its self-hosted release is the whole product as a Docker Compose stack, free to run for your own team.
This page runs that release on an exe.dev VM big enough for it, with the dashboard behind exe.dev login and an address that only accepts events. Your servers reach it with a token, so nothing has to be public, and Sentry's email goes through exe.dev with no SMTP account. It's a lot of machinery: more than fifty containers and 16 GB of memory. If you mostly want errors and alerts, GlitchTip takes the same SDKs on the smallest VM.
What you get#
- Sentry 26.11.0, every feature of the self-hosted release, restarted after a reboot.
- A private dashboard on port 9000 and an ingest-only address on the VM's main URL.
- Sentry's email (alerts, invitations) delivered through exe.dev, with no SMTP account.
- A nightly export of users, projects and settings, with the secret key beside it.
What's running, and where
https://my-sentry.exe.xyz:9000/
The Sentry dashboard, behind exe.dev login and Sentry's own
https://my-sentry.exe.xyz/
Where SDKs send events; apps get in with a VM token, or browsers once you make it public
Deploy with Shelley#
Click Deploy and Shelley will set up Sentry on a new VM, then check that it works. No config-file wrangling required.
Sentry needs a 100 GB disk, more than a new VM has. Shelley checks first and, if it's too small, gives you a link to grow it; the terminal command below makes the VM that size from the start.
Prefer a terminal?
curl -fsSL \
https://exe-staging.dev/deploy/sentry/prompt.txt \
| ssh exe.dev new --disk=100GB --prompt=/dev/stdinWhat Shelley is told
Set up Sentry on this VM by following the exe.dev recipe at https://exe-staging.dev/deploy/sentry.md?via=deploy from top to bottom.
The recipe's example VM name is my-sentry. This VM's name is the output of `hostname`: use it wherever the recipe writes my-sentry. Skip the step that creates the VM; you are on it.
This recipe needs a 100GB disk, and a new VM's may be smaller. Before you install anything, run `df -h /`. If its size is under 90G, stop and ask me to grow the disk, either with this link: https://exe.dev/suggest?command=resize%20my-sentry%20--disk%3D100GB or, on my computer, with `ssh exe.dev resize my-sentry --disk=100GB`. When I say it's done, run `sudo resize2fs "$(findmnt -no SOURCE /)"`, check `df -h /` again, and carry on.
You are done when all of these are true. Check each one yourself:
- Sentry 26.11.0, every feature of the self-hosted release, restarted after a reboot.
- A private dashboard on port 9000 and an ingest-only address on the VM's main URL.
- Sentry's email (alerts, invitations) delivered through exe.dev, with no SMTP account.
- A nightly export of users, projects and settings, with the secret key beside it.
Read the whole recipe, including closed details, and follow "Install by
hand" first. The opening walkthrough is for the owner afterwards. Do not
run the later Restore or Update instructions.
Do "Check the size" before installing: if the VM has fewer than 4
vCPUs, under 15 GB of memory or under 95G of disk, stop and give the
owner the resize link from that step, with this VM's name; continue when
they say it's done. The installer takes 15 to 30 minutes; run it in tmux
and wait for it. Work as exedev in ~/sentry.
Do not create a Sentry user, projects or send test email: the owner does
that. Leave sharing alone; the VM stays private. Verify docker.service is
enabled, `docker compose ps` shows every service up, localhost:9000/auth/login/
answers 200, localhost:8000/ answers 200 with the ingest message, and
localhost:8000/auth/login/ and localhost:8000/api/0/ return 404. Check the
backup timer is enabled and the first export exists in ~/sentry-backups.
Finish with the dashboard URL on port 9000 and the createuser command from
"Create your account" for the owner to run.
Finish with the URLs I should open.
Also at /deploy/sentry/prompt.txt. The recipe it follows is /deploy/sentry.md.
Create your account#
Sentry's installer leaves user creation to you. Open a terminal on the VM
(ssh my-sentry.exe.xyz) and create the first user with the email
you use for exe.dev, so Sentry's email can reach you:
cd ~/sentry
docker compose run --rm web createuser --superuser --email you@example.com
It asks for a password. Then open https://my-sentry.exe.xyz:9000/,
sign in past exe.dev login, and Sentry shows a one-time Welcome to
Sentry form. Leave the SMTP fields empty (mail already goes through
exe.dev) and Allow Registration off, and click Continue.
Make a project and send an error#
Sentry starts with an internal project for its own errors. Open
Settings → Projects → Create Project, pick a platform, keep the
alert that emails you about high-priority issues, name the project, and
click Create Project. Sentry shows its DSN, the address and key
an SDK sends events to:
https://d4f3b03b3ce2569ef254ad0847794135@my-sentry.exe.xyz:9000/2
The :9000 is the private dashboard. Apps use the same DSN without
:9000, which goes to the ingest-only address. A DSN's key only lets
someone send events; it can't read anything.
For a first test, use the VM itself, where Sentry's port is reachable
without exe.dev login. Paste your DSN with the host changed to
localhost:9000 and https to http:
export SENTRY_DSN='http://d4f3b03b3ce2569ef254ad0847794135@localhost:9000/2'
cat > /tmp/hello_sentry.py <<'EOF'
import os, sentry_sdk
sentry_sdk.init(dsn=os.environ["SENTRY_DSN"], environment="test")
def checkout(cart):
return sum(item["price"] for item in cart) / len(cart)
checkout([])
EOF
uv run --with sentry-sdk python /tmp/hello_sentry.py
Python prints a ZeroDivisionError, and the SDK sends it before exiting.
Open Issues: it's there within a few seconds, with the stack trace and
the test environment.
Send errors from your servers#
Your apps run somewhere else. The VM is private, so exe.dev's proxy turns away their events unless they carry a VM token, a key that works for this VM's web addresses and nothing else. The proxy checks it and strips it, so Sentry never sees it. On your computer, make a token for each app:
ssh exe.dev ssh-key generate-api-key --vm=my-sentry --label=shop-errors --exp=1y
Put it in the app's environment as EXE_VM_TOKEN, and the DSN without
:9000 as SENTRY_DSN. Add --ips=203.0.113.7/32 to accept the token
only from your server's address. To stop an app sending, find its key in
ssh exe.dev ssh-key list and run ssh exe.dev ssh-key remove with its
name or fingerprint.
Node.js (@sentry/node) takes extra headers as an option:
import * as Sentry from "@sentry/node";
Sentry.init({
dsn: process.env.SENTRY_DSN,
transportOptions: {
headers: { "X-Exedev-Authorization": `Bearer ${process.env.EXE_VM_TOKEN}` },
},
});
Python (sentry-sdk) has no such option, so add the header in a
small transport subclass. It overrides an internal method, so pin your
sentry-sdk version and recheck after upgrades:
import os
import sentry_sdk
from sentry_sdk.transport import HttpTransport
class ExeDevTransport(HttpTransport):
def _update_headers(self, headers):
super()._update_headers(headers)
headers["X-Exedev-Authorization"] = "Bearer " + os.environ["EXE_VM_TOKEN"]
sentry_sdk.init(dsn=os.environ["SENTRY_DSN"], transport=ExeDevTransport)
The rest is Sentry's usual setup for your framework; our Django, FastAPI and Node.js pages set up apps this fits into. An app on another of your exe.dev VMs can skip the token with a VM-to-VM integration, which signs its requests on the way out:
ssh exe.dev integrations add http-proxy --name sentry --target https://my-sentry.exe.xyz/ --peer --attach vm:my-app
That app then uses the DSN with its host changed to sentry.int.exe.xyz.
Catch browser errors#
JavaScript errors happen in your visitors' browsers, which can't sign in to exe.dev or keep a token secret. To accept them, make the VM's main address public. On your computer:
ssh exe.dev share set-public my-sentry
That opens https://my-sentry.exe.xyz/, port 8000, and only that. The
ingest proxy there passes Sentry's per-project endpoints
(/api/<project>/envelope/ and friends) to Relay, Sentry's ingest
service, and answers 404 to everything else. The dashboard on port 9000
stays behind exe.dev login. Then use the DSN without :9000 in your
front end:
import * as Sentry from "@sentry/browser";
Sentry.init({ dsn: "https://d4f3b03b3ce2569ef254ad0847794135@my-sentry.exe.xyz/2" });
What this exposes: anyone who reads the DSN from your page can send
events to that project, as with any Sentry setup. Under Project
Settings → Client Keys you can rate-limit a key or give the front end
its own and revoke it. The proxy also caps each address at 50 requests a
second. To close it again: ssh exe.dev share set-private my-sentry.
To keep the VM private instead, use the JavaScript SDK's
tunnel option:
your own backend receives the events and forwards them with a VM token.
Alerts and email#
Sentry's email goes through a small relay that hands it to exe.dev's email gateway. The gateway delivers to you, your exe.dev team and people the VM is shared with who have signed in, and drops other addresses (the relay logs why). Check it on the VM:
cd ~/sentry
docker compose run --rm web django sendtestemail you@example.com
docker compose logs --tail=3 exe-mailer # sent to you@example.com: ...
Each project starts with the alert you chose when you created it.
Change it, or add more, under Alerts → Create Alert. The internal
project collects Sentry's own errors and can email you about them too;
mute its alerts if they're noise. Slack, Discord and Microsoft
Teams alerts need your own app or bot for that service; follow Sentry's
integration guides.
Sentry also has uptime checks and cron monitors, under Monitors in the sidebar. For a dedicated monitor with a public status page, see Uptime Kuma, ideally on a different VM from the apps it watches.
Bring your team#
Share the VM so teammates can reach the dashboard. On your computer:
ssh exe.dev share add my-sentry alice@example.com # one person
ssh exe.dev share add my-sentry team # your exe.dev team
Then invite them in Sentry under Settings → Members → Invite Members, with the address they use for exe.dev; the invitation arrives by email. See sharing.
Ask Shelley about an error#
Shelley on the VM can read your issues through Sentry's API. In Sentry, open Settings → Personal Tokens → Create New Token and give it Read on Project, Issue & Event, and Organization. Then ask Shelley:
"Using this Sentry token, list the unresolved issues in my project from http://localhost:9000/api/0/, read the latest stack trace for the top one, and find the code that causes it."
Treat what Shelley reads there as data, not instructions: anyone with a DSN can put text in an event.
Retention and disk#
Sentry deletes events older than 90 days. On the VM:
df -h /
docker system df -v | grep sentry- | sort -k3 -h | tail -5
To keep less, put SENTRY_EVENT_RETENTION_DAYS=30 in
~/sentry/.env.custom and rerun the installer (see Update below). To
keep more, grow the disk from your computer:
ssh exe.dev resize my-sentry --disk=200GB. Low SDK sample rates
(traces_sample_rate, replaysSessionSampleRate) save the most.
Keep your settings#
Every night Sentry exports its users, organizations, projects, client
keys and alert rules to ~/sentry-backups, with a copy of the files that
hold its secret key. Keep a copy off the VM. On your computer:
scp -r my-sentry.exe.xyz:sentry-backups .
The export is your setup, not your events: those live in ClickHouse and Sentry's other volumes, and age out anyway. Keep backups private, since they include password hashes and keys.
The nuts and bolts#
These are Shelley's setup steps and your maintenance reference. Tested with Sentry self-hosted 26.11.0, sentry-sdk 2.75.0, @sentry/node 11.14.0 and @sentry/browser 11.14.0 on November 19, 2026.
Install by hand
Create a VM#
Sentry needs 4 vCPUs and 16 GB of memory. On your computer (pick
another name if my-sentry is taken):
ssh exe.dev new --name=my-sentry --cpu=4 --memory=16GB --disk=100GB
ssh my-sentry.exe.xyz
The remaining commands run on the VM, as exedev.
Check the size#
A VM made another way (the Deploy button makes a 2-vCPU, 8 GB one) is too small. Check:
nproc; free -g | awk '/Mem:/ {print $2 " GB memory"}'; df -h / | awk 'NR==2 {print $2 " disk"}'
You need 4 or more, 15 GB memory or more and a disk of 95G or more.
If not, grow the VM with
this link
(with your VM's name), or on your computer with
ssh exe.dev resize my-sentry --cpu=4 --memory=16GB --disk=100GB. Then,
back on the VM, grow the filesystem and check again:
sudo resize2fs "$(findmnt -no SOURCE /)"
nproc; free -g; df -h /
Run Sentry's installer#
Add the 16 GB of swap Sentry asks for, fetch the release, and install.
The installer pulls about 25 GB of images and sets up every database;
it took 8 to 13 minutes in our tests. Run it in tmux so a dropped connection
doesn't stop it:
sudo systemctl enable --now docker.service
if ! swapon --show | grep -q /swapfile; then
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
fi
git clone --branch 26.11.0 --depth 1 https://github.com/getsentry/self-hosted.git ~/sentry
cd ~/sentry
./install.sh --skip-user-creation --no-report-self-hosted-issues --apply-automatic-config-updates
It ends with You're all done!.
Point Sentry at exe.dev#
Sentry needs to know its address, that it sits behind exe.dev's HTTPS proxy, and where to send mail. This appends those settings once:
cd ~/sentry
h=$(hostname).exe.xyz
if ! grep -q '^system.url-prefix' sentry/config.yml; then
sed -i "s/^mail.host: 'smtp'/mail.host: 'exe-mailer'/" sentry/config.yml
cat >> sentry/config.yml <<EOF
# exe.dev: the dashboard's address, and mail through exe.dev's email gateway
system.url-prefix: 'https://$h:9000'
mail.port: 2525
mail.from: 'sentry@$h'
EOF
cat >> sentry/sentry.conf.py <<EOF
# exe.dev: behind the HTTPS proxy
SECURE_PROXY_SSL_HEADER = ("HTTP_X_FORWARDED_PROTO", "https")
USE_X_FORWARDED_HOST = True
CSRF_TRUSTED_ORIGINS = ["https://$h:9000"]
EOF
fi
Add the ingest proxy and mail relay, and start Sentry#
Two small services join Sentry's own in docker-compose.override.yml,
which Sentry's Compose commands read and its upgrades leave alone. The
mail relay is a short Python program,
mail-relay.py, that takes
Sentry's SMTP and passes each message to exe.dev's email gateway. The
ingest proxy answers on port 8000 and passes only SDK traffic to Relay.
curl -fsSL -o exe-mail-relay.py https://exe-staging.dev/deploy/sentry/mail-relay.py
cat > docker-compose.override.yml <<'EOF'
services:
exe-mailer:
build:
dockerfile_inline: |
FROM python:3.13-alpine
RUN pip install --no-cache-dir aiosmtpd==1.4.6
restart: unless-stopped
init: true
command: python /mail-relay.py
volumes: ["./exe-mail-relay.py:/mail-relay.py:ro"]
ingest:
image: nginx:stable-alpine
restart: unless-stopped
ports: ["8000:8000"]
volumes: ["./ingest.conf:/etc/nginx/conf.d/default.conf:ro"]
EOF
cat > ingest.conf <<'EOF'
limit_req_zone $binary_remote_addr zone=ingest:10m rate=50r/s;
server {
listen 8000;
access_log off;
client_max_body_size 100m;
resolver 127.0.0.11 valid=30s;
set $relay http://relay:3000;
# exe.dev's proxy puts the sender's address last in X-Forwarded-For.
set_real_ip_from 0.0.0.0/0;
set_real_ip_from ::/0;
real_ip_header X-Forwarded-For;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header X-Forwarded-Proto https;
limit_req zone=ingest burst=500 nodelay;
limit_req_status 429;
# The project endpoints SDKs send to, served by Sentry's Relay.
location ~ ^/api/[1-9][0-9]*/ {
limit_except POST OPTIONS { deny all; }
proxy_pass $relay;
}
location = / {
default_type text/plain;
return 200 "Sentry event ingest. The dashboard is private.\n";
}
location / { return 404; }
}
EOF
# Sentry reports its own errors to its internal project; send them
# straight to Relay inside Compose, not out through exe.dev's proxy.
if ! grep -q backend_dsn sentry/sentry.conf.py; then
docker compose up -d --wait postgres
dsn=$(docker compose exec -T postgres psql -U postgres -tAc \
"select 'http://' || k.public_key || '@relay:3000/' || p.id from sentry_projectkey k join sentry_project p on p.id = k.project_id where p.slug = 'internal' order by k.id limit 1")
echo "SENTRY_SDK_CONFIG[\"backend_dsn\"] = \"$dsn\"" >> sentry/sentry.conf.py
fi
tail -1 sentry/sentry.conf.py
docker compose up -d --wait
docker compose ps --format '{{.Service}} {{.Status}}' | grep -v Up || echo "all services up"
curl -s -o /dev/null -w 'dashboard %{http_code}\n' localhost:9000/auth/login/
curl -s localhost:8000/
curl -s -o /dev/null -w 'login on the ingest port %{http_code}\n' localhost:8000/auth/login/
curl -s -o /dev/null -w 'API on the ingest port %{http_code}\n' localhost:8000/api/0/
printf 'Dashboard: https://%s:9000/\n' "$h"
Every service is up (all services up), the dashboard answers 200,
and the ingest port shows its message and 404 for the sign-in page
and the API. The first start takes a few minutes.
What the pieces do:
- The HTTPS proxy sends
https://my-sentry.exe.xyz:9000/to Sentry's own nginx, andhttps://my-sentry.exe.xyz/to the ingest proxy on port 8000. Both need exe.dev login or a VM token until you make the VM public, and port 9000 always does. - Relay, Sentry's ingest service, checks each event's key and project and queues it in Kafka; workers write it to ClickHouse and PostgreSQL.
- Sentry reports its own errors to its
internalproject; thebackend_dsnline sends them straight to Relay instead of out through exe.dev's proxy, which would refuse them. - The ingest proxy takes the sender's address from the end of
X-Forwarded-For, which exe.dev's proxy sets, and rate-limits by it.
Set up nightly backups#
Sentry's scripts/backup.sh exports users, organizations, projects,
client keys and alert rules as JSON. This keeps two weeks of exports,
with the two files that hold Sentry's secret key:
cd ~/sentry
cat > exe-backup.sh <<'EOF'
#!/bin/sh
set -eu
umask 077
cd "$(dirname "$0")"
dest="$HOME/sentry-backups"
mkdir -p "$dest"
./scripts/backup.sh --no-report-self-hosted-issues > /dev/null
python3 -m json.tool sentry/backup.json > /dev/null
chmod 600 sentry/backup.json
mv sentry/backup.json "$dest/sentry-$(date +%Y%m%d-%H%M%S).json"
cp sentry/config.yml sentry/sentry.conf.py "$dest/"
find "$dest" -name 'sentry-*.json' -mtime +14 -delete
EOF
chmod +x exe-backup.sh
sudo tee /etc/systemd/system/sentry-backup.service >/dev/null <<'EOF'
[Unit]
Description=Export Sentry's settings
After=docker.service
[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/sentry/exe-backup.sh
EOF
sudo tee /etc/systemd/system/sentry-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Export Sentry's settings nightly
[Timer]
OnCalendar=daily
Persistent=true
[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now sentry-backup.timer
sudo systemctl start sentry-backup.service
systemctl list-timers sentry-backup.timer
ls -l ~/sentry-backups
The timer lists its next run, and ~/sentry-backups holds a
sentry-*.json export, config.yml and sentry.conf.py. Now follow the
walkthrough at the top to create your account.
Restore settings on a new VM
Sentry's import loads users, organizations, projects, client keys and alert rules into a fresh install, so your apps' DSNs keep working. Events are not included.
On the new VM, run Install by hand up to and including the
installer. Before the next step, copy the old config.yml and
sentry.conf.py from the backup into ~/sentry/sentry/ (they hold the
secret key; if the VM's name changed, fix the address lines at their
ends), and the export as ~/sentry/sentry/backup.json. Run the rest of
Install by hand, then on the VM:
cd ~/sentry
./scripts/restore.sh --no-report-self-hosted-issues
rm sentry/backup.json
Sign in with your old password.
Update
Sentry releases monthly as YY.MM.N. Upgrades must stop at each
hard stop on the way,
so read that page before jumping far. On the VM, back up, then fetch the
new release and rerun the installer, which runs the migrations:
cd ~/sentry
./exe-backup.sh
release=26.12.0 # the release you're moving to
git fetch --depth 1 origin tag "$release"
git checkout "$release"
./install.sh --skip-user-creation --no-report-self-hosted-issues --apply-automatic-config-updates
docker compose up -d --wait
The exe.dev settings appended to sentry/config.yml and
sentry/sentry.conf.py, docker-compose.override.yml and
ingest.conf are yours, and the installer keeps them.
Something not working?
Start with what's not running. On the VM:
cd ~/sentry
docker compose ps -a --format '{{.Service}} {{.Status}}' | grep -v ' Up'
docker compose logs --tail=50 web relay
free -h
- Down after a reboot? Run
sudo systemctl enable --now docker.service, thendocker compose up -d --waitin~/sentry. - A service exited, or the VM is sluggish. Sentry wants all of its
16 GB plus swap. Check
free -hshows the swap, and that nothing else big runs on this VM.docker compose up -d --waitrestarts stopped services. - The SDK sends but nothing shows up. Apps off the VM use the DSN
without
:9000, plus the token header; without it exe.dev answers401and the SDK drops the event.debug=Trueinsentry_sdk.init(ordebug: truein JavaScript) prints what the SDK sent and the reply.docker compose logs --tail=50 relayshows what Relay rejected. - CSRF errors when signing in. The address in
CSRF_TRUSTED_ORIGINSat the end ofsentry/sentry.conf.pymust match the one in your browser, port included; restart withdocker compose restart web. - No email.
docker compose logs exe-mailershows each message and, if exe.dev refused it, why. Use the address you use for exe.dev, or share the VM with the person first.
Frequently asked questions#
What does self-hosted Sentry need?
Sentry's minimum is 4 CPU cores, 16 GB of memory plus 16 GB of swap, and 20 GB of free disk; its installer refuses less than 4 cores or about 14 GB. In our tests it used about 13 GB of memory at idle. On exe.dev that's a VM made with --cpu=4 --memory=16GB, which needs a plan with 16 GB of capacity or more; see pricing.
Is self-hosted Sentry free?
Yes. Sentry's code is under the Functional Source License, which lets you run it for your own team at no charge; it only forbids offering it as a competing service. You pay for the VM.
Self-hosted Sentry or GlitchTip?
Sentry if your team uses Session Replay, profiling, crons, its dashboards or its integrations, and will keep up with upgrades. GlitchTip takes the same SDKs, covers errors, alerts and basic performance in about 300 MB, and fits on the smallest VM.
Can my servers send errors without making anything public?
Yes. Give each app a VM token and send it as an X-Exedev-Authorization header from the SDK. exe.dev checks it and strips it before Sentry sees the request. See Send errors from your servers.
How long does Sentry keep events?
90 days by default. Set SENTRY_EVENT_RETENTION_DAYS in ~/sentry/.env.custom and rerun the installer to change it.
Updated Nov 19, 2026 · tested end to end Nov 19, 2026 · Markdown · manifest.json · Something wrong? Tell us