Your infrastructure logs can tell you that something broke, but not why a specific release broke it for a specific user. That’s what error tracking is for. This guide shows you how to deploy Sentry with Docker Compose on your own server. You’ll set up SMTP, TLS, and storage, create projects and alert rules, and connect a Python and a Node.js app to capture errors, traces, and releases.

Why Deploy Sentry with Docker Compose Instead of Using SaaS

Sentry’s SaaS plan is easy to use, but your data leaves your servers, and you pay based on how many events you send. When you deploy Sentry with Docker Compose on your own infrastructure, you keep full control of your error and performance data, skip event-based pricing, and set retention rules yourself.

Self-hosted Sentry has almost all the same features as the paid plan; issues, tracing, releases, and alerts all work the same way, without billing and a few AI extras.

Prerequisites and System Requirements

Before you deploy Sentry with Docker Compose, pick a server correctly. Undersizing is the top cause of self-hosted Sentry problems, since it runs several databases, a message broker, and worker services all on one machine.

Make sure your server meets these minimum requirements first:

• 4 CPU cores minimum.
• 16 GB RAM with 16 GB swap.
• 20 GB of free disk space.
• Docker Engine and Docker Compose are installed.
• An Ubuntu-based Linux distribution.
• A domain name is pointed at your server’s IP.

Self-hosted Sentry uses a lot of disk I/O. If you track iowait, anything above 10% means your disk is too slow. If you don’t have a server ready yet, get a Linux VPS with fast NVMe storage first; disk speed affects Sentry’s performance more than almost anything else.

Step 1. Install the Official Self-Hosted Sentry Repository

It is recommended to use the latest release instead of the master branch. You can check the GitHub releases page for the current tag.

To get and check the latest Sentry tag, use the commands below:

VERSION=$(curl -Ls -o /dev/null -w %{url_effective} https://github.com/getsentry/self-hosted/releases/latest)
VERSION=${VERSION##*/}
git clone https://github.com/getsentry/self-hosted.git
cd self-hosted
git checkout ${VERSION}
echo "Installing self-hosted Sentry ${VERSION}"

In the output, you should see:

Installing self-hosted Sentry 26.7.2

Inside the self-hosted directory, run the bundled Sentry installer. It sets up the base configuration files, pulls all required images, and prepares the databases:

./install.sh

During installation, you’ll be asked whether you want to send anonymous error reports to Sentry’s team, which is optional, and to set up your admin login. If you’re running this in a script and don’t want prompts, add the flag --no-report-self-hosted-issues to skip the first question automatically.

The install script also creates two files you’ll need to edit next:

• sentry/config.yml: Basic settings like your site URL and email setup.
• sentry/sentry.conf.py: More advanced settings, like TLS and trusted domains.

Step 2. Configure Sentry Persistent Storage

When you deploy Sentry with Docker Compose, persistence is handled entirely through named volumes rather than manual database setup. Everything Sentry writes, including Postgres data, Kafka logs, ClickHouse tables, uploaded artifacts, and symbolicator caches, comes in named Docker volumes defined in docker-compose.yml.

You don’t need to set up manual folder mounts to deploy Sentry with Docker Compose safely; Docker handles storage on its own. Just check where these volumes are saved on disk, and make sure you back them up:

docker volume ls | grep sentry
docker volume inspect sentry-postgres

Note: If your VPS has a separate disk for data, mount it at Docker’s data folder (/var/lib/docker) before you run ./install.sh for the first time. If your local disk fills up later, you can store large files, such as event attachments, in S3-compatible storage by setting filestore.backend in config.yml.

Step 3. Configure SMTP for Alert and Invite Emails

Sentry ships with a bundled internal SMTP relay, but for real alert delivery you should point it at a real mail provider.

Open the Config YAML file:

nano sentry/config.yml

Set the mail.* block:

mail.backend: 'smtp'
mail.host: 'smtp.yourprovider.com'
mail.port: 587
mail.username: 'apikey-or-username'
mail.password: 'your-smtp-password'
mail.use-tls: true
mail.from: 'se****@********in.com'

Then re-run ./install.sh, so the new configuration and any pending migrations apply cleanly:

./install.sh

Test email delivery later from the admin panel under Settings > Admin > Mail once the stack is running. This is also how you’ll confirm alert notifications actually reach your inbox.

Step 4. Set the URL Prefix and Prepare Reverse-Proxy TLS

Again, open the following file:

nano sentry/config.yml

Uncomment and set:

system.url-prefix: 'https://sentry.yourdomain.com'

Sentry uses port 9000 by default and does not handle HTTPS on its own. For production, deploy Sentry with Docker Compose behind a reverse proxy or load balancer. It manages the SSL/TLS certificate and passes the real visitor IP address to Sentry.

You can use Caddy to get automatic Let’s Encrypt certificates. Create and edit this file:

sudo nano /etc/caddy/Caddyfile

Add:

sentry.yourdomain.com {
    reverse_proxy 127.0.0.1:9000
}

Save, then reload Caddy:

sudo systemctl reload caddy

Caddy will create and renew the HTTPS certificate automatically.

Step 5. Start the Sentry Stack

After you finish the setup, run the command below to start all Sentry containers in the background. This is when you deploy Sentry with Docker Compose and Sentry starts running:

docker compose up --wait

Wait for health checks to pass and check that all services report healthy:

docker compose ps

Sentry is now reachable at http://127.0.0.1:9000 locally, or at your HTTPS domain once the reverse proxy is set up. Log in with the admin account you created during install.sh.

Step 6. Create an Organization, Project, and DSN

At this point you have a fully running stack, but you haven’t yet connected any real application to the instance you just used to deploy Sentry with Docker Compose.

• Open the Sentry web dashboard.
• Create an organization if you do not have one yet.
• Go to Projects > Create Project.
• Choose your app type, such as Python or Node.js.
• Enter a project name and choose a team.
• Sentry will create a DSN for the project.
• A DSN looks like this:

https://<key>@your-domain/<projectId>

• Copy the DSN. You will add it to your app code, so Sentry knows where to send errors and performance data.

Each project can have its own DSN, data retention time, and alert rules. You can deploy Sentry with Docker Compose once for staging or production, then create a separate project for each app or repository.

Step 7. Configure Alert Rules

Go to Project Settings > Alerts and create a new alert rule.

You can send an alert when:

• A new issue appears.
• The same error happens too often, such as more than 10 times in 5 minutes.
• A fixed issue happens again.

Choose what Sentry should do when the rule runs:

• Send an email through your SMTP server.
• Send a message to Slack.
• Send data to a webhook.

If your SMTP setup works, you should receive the email alert shortly after the rule is triggered.

Step 8. Tune Event Retention

After you deploy Sentry with Docker Compose, watch your disk space. By default, Sentry keeps events for 90 days, which can slowly fill your disk.

To change how long Sentry keeps events, edit the .env file. You can also use .env.custom , so upgrades do not overwrite your setting:

SENTRY_EVENT_RETENTION_DAYS=30

Keeping data for fewer days uses less disk space in ClickHouse and PostgreSQL. This is useful if your VPS has a small disk.

If you use an .env.custom file, start Sentry with this command:

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

The normal docker compose up command does not load .env.custom.

Step 9. Configure Inbound Filters

After you deploy Sentry with Docker Compose, you should filter out errors that are not useful. This keeps your issue list clean and saves disk space.

Go to Project Settings > Inbound Filters and enable filters for:

• Known browser extension errors.
• Old browser errors, such as old Internet Explorer or Edge versions.
• Events from selected IP addresses or user agents.
• Errors that match a custom text pattern.

These filters stop unwanted events before Sentry saves them. This helps you focus on real app errors instead of bot traffic, browser add-ons, or ad-blocker errors.

Step 10. Connect Python App to Sentry

To send Python errors to Sentry, install the SDK in your Python service:

pip install "sentry-sdk"

Add this code near the top of your main Python file. Replace dsn with the project DSN you copied in Step 6:

import sentry_sdk

sentry_sdk.init(
    dsn="https://<key>@sentry.yourdomain.com/<projectId>",
    send_default_pii=True,
    traces_sample_rate=1.0,
    environment="production",
    release="[email protected]",
)

Run a test exception to confirm error capture works:

division_by_zero = 1 / 0

Test a custom performance trace:

import sentry_sdk

with sentry_sdk.start_transaction(op="task", name="Test Transaction"):
    span = sentry_sdk.start_span(name="Custom Span Name")
    span.finish()

Sentry can track many common Python tools automatically, such as Flask, Django, requests, and SQLAlchemy. It can show web requests and database queries as spans without adding extra code. This works when tracing is enabled and a transaction is running.

Step 11. Connect Node.js App to Sentry

Install the Node SDK and the optional profiling package:

npm install @sentry/node @sentry/profiling-node --save

Create an instrument.js file that must be required before any other module:

const Sentry = require("@sentry/node");
const { nodeProfilingIntegration } = require("@sentry/profiling-node");

Sentry.init({
  dsn: "https://<key>@sentry.yourdomain.com/<projectId>",
  integrations: [nodeProfilingIntegration()],
  tracesSampleRate: 1.0,
  profileSessionSampleRate: 1.0,
  release: "[email protected]",
  environment: "production",
});

Load it first in your main file:

require("./instrument");
const http = require("http");
// your application code goes here

Test that Sentry works by sending a test error and a test span:

Sentry.startSpan({ op: "test", name: "My First Test Transaction" }, () => {
  setTimeout(() => {
    try {
      foo();
    } catch (e) {
      Sentry.captureException(e);
    }
  }, 99);
});

Step 12. Track App Releases in Sentry

Add a release name to every event so Sentry can show which app version caused an error. This helps you find errors that started after a new deployment.

For minified JavaScript, error details are hard to read without source maps. Use the Sentry Wizard to create and upload source maps. It can detect your build tool automatically:

npx @sentry/wizard@latest -i sourcemaps

This uploads source maps for the same release name used by your app. When you deploy Sentry with Docker Compose and use CI/CD, Sentry can show the original TypeScript or JSX code instead of minified JavaScript.

Confirm Sentry Alert Delivery

After you set up error tracking and alert rules, check the following:

• Create a test error in your Python or Node.js app.
• Check that the error appears in Issues after a few seconds.
• Check that the related trace and spans appear in Traces.
• Make sure the alert email reaches the email address you set in the alert rule.
• Mark the issue as resolved, then create the same error again. Check that Sentry sends a new alert.

If you do not receive an email, check the mail.* settings in config.yml. Run ./install.sh again, then test the email from Settings > Admin > Mail.

Note: Sentry and log tools do different jobs. Sentry shows what failed in your code, while log tools like Loki show what your containers were doing at the same time. You can use this setup with Grafana Alloy and Loki for Docker logs to check errors faster.

Upgrade Self-Hosted Sentry Instance

To upgrade later, you should pull the newest tag and re-run the installer rather than manually editing containers:

cd self-hosted
git fetch --tags
git checkout $(curl -Ls -o /dev/null -w %{url_effective} https://github.com/getsentry/self-hosted/releases/latest | sed 's/.*\///')
./install.sh
docker compose up --wait

When you update Sentry, always run:

./install.sh

The install script applies needed database updates during upgrades.

Conclusion

At this point, you learned how to deploy Sentry with Docker Compose on a properly sized server, HTTPS, email alerts, data retention, and inbound filters. Your Python and Node.js apps can now send errors, traces, and release data to your own Sentry server.

Next, adjust trace sample rates, alert limits, and data retention based on your app traffic and the number of errors you receive.

We hope you enjoy this guide.

FAQs