How to Use GlitchTip: The Beginner's Guide (First Deploy, the Retention Rule, and the DSN-Swap Migration)

CodexFuse Team · 2026-11-01T06:45:01.602Z · 12 min read

Learn how to use GlitchTip: deploy the self-hosted Sentry alternative with Docker, set the retention rule, send your first error via the DSN, and migrate from Sentry.

Learning how to use GlitchTip is the fastest way to own your error tracking: GlitchTip is an open-source, MIT-licensed, Sentry-compatible error tracker you run on your own hardware, and it accepts events from Sentry's own SDKs — so migrating is literally changing one URL. If you can follow a Docker beginner guide, you can have a working GlitchTip instance in under an hour — and this guide takes you from first deploy to the DSN-swap migration that replaces hosted Sentry, with the retention rule every beginner needs to set on day one.

What Is GlitchTip?

GlitchTip is an open-source, self-hosted error-tracking platform that implements Sentry's SDK wire protocol, so your application's existing Sentry instrumentation works verbatim — only the DSN URL changes. Development happens on GitLab (glitchtip/glitchtip-backend, last active 2026-10-30), the project is MIT-licensed and 100% open source, and release v6.2.6 was the current tag as of 2026-08-07, with GlitchTip 6.2 shipping on June 22, 2026 (all facts verified 2026-11-01). The pitch is simple: Sentry-grade error tracking without per-seat pricing, with your data and your retention policy on your own server.

GlitchTip is not a Sentry clone with every feature — it is a focused, lightweight error tracker. It speaks the same protocol as Sentry's SDKs for Python, JavaScript/Node, Go, Ruby, PHP, Java, .NET, Rust, Elixir, Flutter, and React Native, and since 6.2 it can also ingest logs natively over OpenTelemetry at /v1/logs with no sentry-sdk required. Advanced Sentry features like session replay, profiling, and AI triage are not supported — which is exactly why it runs comfortably on a cheap VPS where full Sentry would not.

How Do I Use GlitchTip for the First Time?

Using GlitchTip for the first time follows a ten-step arc: deploy, set the retention rule, log in, create an organization, create a project, grab the DSN, trigger your first error, watch it land, set up an alert, then plan the DSN swap. Here is the arc in order, with the detail behind each step in the sections that follow:

1. Deploy GlitchTip with Docker. The official path is to copy compose.sample.yml as compose.yml, edit the environment, and run docker compose up -d — migrations run automatically on startup.
2. Set the retention rule before ingesting. Put GLITCHTIP_RETENTION_DAYS=90 in your environment on day one, because every event you accept lands in PostgreSQL and a busy app can fill a cheap VPS disk fast.
3. Register the first account. The first user you register becomes the superuser automatically — use a strong password, since registration defaults to open.
4. Create an organization and a project. The project page hands you the DSN: the one URL your app needs.
5. Point your existing Sentry SDK at it. Change only the DSN — app code stays identical. This is the money moment of the whole platform.
6. Trigger a test error. The divide-by-zero test proves the whole pipeline works end to end.
7. Watch it land in Issues. Your error appears with a stack trace, environment data, and occurrence counts — the Sentry experience, on your box.
8. Set up alerts. Email is the default; add webhook recipients for Slack, PagerDuty, or your own endpoint.
9. Turn on uptime monitors. GlitchTip ships built-in uptime checks, so your cron jobs and APIs get monitored in the same UI.
10. Migrate staging, then production. Swap DSNs one environment at a time, keep the old provider running until you are confident, and know the rollback is a one-line revert.

What Do I Need Before Installing GlitchTip?

You need a server and Docker — that is the whole prerequisites list. A small VPS with 1 GB of RAM is enough for a personal install: the official guidance recommends 512 MB, with 256 MB workable in all-in-one mode, and the sample compose ships PostgreSQL 18 and Valkey 9 alongside the app. If you have never rented a server before, start with what is VPS hosting before continuing.

Docker is the only required install. The official install docs assume you can run Docker Compose on a Linux host; there is also a Helm chart for Kubernetes and one-click installers on PikaPods, Elestio, Railway, and RepoCloud if you prefer managed hosting. This guide uses the Docker Compose path because it is the one you control completely.

How Do I Deploy GlitchTip with Docker?

Deploy GlitchTip with Docker by copying the official sample compose file, editing the environment block, and starting the stack — database migrations run automatically on first boot. The official install arc is: install Docker, copy compose.sample.yml to compose.yml, edit the environment, then docker compose up -d. A representative stack looks like this:

services:
  glitchtip:
    image: glitchtip/glitchtip:6
    ports:
      - "8000:8000"
    environment:
      SECRET_KEY: "change-me-to-a-long-random-string"
      EMAIL_URL: "smtp://user:[email protected]:587"
      DEFAULT_FROM_EMAIL: "[email protected]"
      GLITCHTIP_DOMAIN: "https://errors.example.com"
      DATABASE_URL: "postgres://gt:secret@postgres:5432/glitchtip"
      GLITCHTIP_RETENTION_DAYS: "90"
    depends_on:
      - postgres
      - valkey
  postgres:
    image: postgres:18
  valkey:
    image: valkey/valkey:9

Pin the image to a major-version tag like glitchtip/glitchtip:6 rather than latest once the instance works — latest is fine for a first run, not for something your team depends on. The environment variables that matter most are:

Two first-run behaviors confuse everyone: the migrate service printing Exited (0) is normal — it runs migrations once and stops — and database init scripts only apply on the very first PostgreSQL start. If you change the database credentials later, you must recreate the data volume or the new credentials will not take effect.

Why Does GlitchTip's Retention Setting Matter So Much?

GlitchTip's retention setting matters because every accepted event is stored in PostgreSQL, and without a retention policy a busy application can grow the database until the VPS disk fills and the whole server stops. The current setting is GLITCHTIP_RETENTION_DAYS (default 90); older third-party guides quote GLITCHTIP_MAX_EVENT_LIFE_DAYS with the same 90-day default, but that name does not appear in the current official docs. Set the current variable in your compose file on day one, before the first event lands.

Version 6 introduced hot/cold storage to make retention cheap instead of painful: recent data stays hot in PostgreSQL, and older data is converted to Parquet files on S3 or local disk, queried with DuckDB. The current defaults tell the whole story:

The honest trade-off is this: self-hosted means you own the data AND the disk bill. The retention settings are how you keep both under control.

How Do I Create My First Organization and Project?

Creating your first organization and project is the first thing you do after logging in: sign up, and the first account automatically becomes the superuser. Open http://your-server:8000, register, and you land in an empty instance ready for its first organization. The registration page is open by default — once your admin account exists, flip ENABLE_USER_REGISTRATION to False so strangers cannot sign up on an internet-facing instance.

Inside the UI, create an organization, then a project for the application you want to monitor. When you first visit the project's Issues page, GlitchTip shows you the project's DSN: a URL shaped like https://<key>@errors.example.com/<project-id>. Copy it — the DSN is the only configuration your application needs.

How Do I Send My First Error to GlitchTip?

Sending your first error to GlitchTip means initializing the Sentry SDK you already use with your project's DSN and throwing a test exception. In Python, the whole wiring is one init call:

import sentry_sdk

sentry_sdk.init(dsn="https://[email protected]/1")

# The divide-by-zero test: a deliberate crash to prove the pipeline works.
1 / 0

Run it and open the project's Issues page in GlitchTip. Your ZeroDivisionError appears with the stack trace, the environment, and the occurrence count — the Sentry experience, served from your own server. If nothing appears, the usual suspect is the worker: events can be accepted by the web service but never processed when the worker is not running, so check that the worker container (or GLITCHTIP_EMBED_WORKER all-in-one mode) is up.

For JavaScript apps, the same lesson applies to minified production bundles: readable stack traces need source maps. GlitchTip ships a CLI for this — glitchtip-cli sourcemaps inject stamps your build, glitchtip-cli sourcemaps upload sends them — so production errors resolve to real file names and line numbers.

How Do I Migrate from Sentry to GlitchTip?

Migrating from Sentry to GlitchTip is a DSN swap: change the DSN string in your configuration from your Sentry project's URL to your GlitchTip project's URL, and your app code stays byte-identical. Because GlitchTip speaks the Sentry SDK protocol, there is no SDK rewrite, no dependency swap, no code review — the migration is a configuration change. A typical staging-first rollout looks like this:

# Before (Sentry SaaS):
SENTRY_DSN=https://[email protected]/456

# After (self-hosted GlitchTip):
SENTRY_DSN=https://[email protected]/1

Do it in staging first, throw a test error, and confirm it lands in GlitchTip's Issues page. Roll out to production one service at a time, and keep the old provider running behind each step. If anything goes wrong, the rollback is the same change in reverse — change the DSN back, and that is your whole recovery plan.

A sensible migration order is analytics first, error tracking second, and authentication secrets last, so the riskiest swaps happen when you are already comfortable. If you are still on Sentry and want to understand the platform you are replacing first, read the Sentry beginner guide — then decide which parts of it you actually need before you self-host them.

How Do I Set Up Alerts in GlitchTip?

Setting up alerts in GlitchTip starts with email, which works out of the box once EMAIL_URL is configured — new issues notify you without any further setup. For team chat and paging, open a project, go to alerts, and use "Add An Alert Recipient" to wire up webhooks: Slack, PagerDuty, or your own endpoint. Each project gets its own alert rules, so a noisy staging project can go to email while production pages the on-call phone.

The alert lesson beginners miss is volume: a crashing background job can generate thousands of duplicate events overnight. Tune alert thresholds per project and lean on GlitchTip's issue grouping so one bug is one issue, not ten thousand notifications.

What Is Uptime Monitoring in GlitchTip?

Uptime monitoring in GlitchTip is a built-in feature that polls your URLs on a schedule and alerts you when they stop responding — enabled by default via GLITCHTIP_ENABLE_UPTIME. Create an uptime monitor, give it a URL and an interval, and GlitchTip checks it like a visitor would, recording response times and flagging outages in the same dashboard where your errors live.

There is one important distinction: GlitchTip's monitors are outside-in polling — the server checks your URL. For inside-out monitoring, where your cron job phones home to prove it ran, a dead-man's-switch tool is the right complement; see the Healthchecks beginner guide. Together they cover both failure modes: things that are down, and things that never ran.

GlitchTip vs Sentry: What's the Difference?

GlitchTip vs Sentry is a trade of breadth for ownership: Sentry is the full platform with every bell and whistle, GlitchTip is the lightweight self-hosted drop-in that covers error tracking without the per-seat bill.

This is the draw-the-line rule for the whole lane: if you need the full Sentry platform, use Sentry; if you need error tracking you fully control, GlitchTip is the lightweight lane and the DSN swap makes the two interchangeable at the SDK level.

What Are the Common GlitchTip Beginner Mistakes?

The common GlitchTip beginner mistakes all come from treating a self-hosted service like a SaaS account. First, forgetting the worker: in the default compose layout the worker is a separate process, and without it events are accepted but never processed — if errors vanish after the DSN swap, check the worker first. Second, leaving registration open: ENABLE_USER_REGISTRATION defaults to true, so lock it after creating your admin account. Third, skipping the retention setting and discovering a full disk at 3 AM. Fourth, using latest in production instead of pinning a major-version tag. Fifth, omitting the scheme from GLITCHTIP_DOMAIN — the docs require the full https:// URL, not a bare hostname.

Two network lessons round it out: GlitchTip listens on port 8000, so your reverse proxy targets http://127.0.0.1:8000, and putting it behind HTTPS is mandatory before it faces the internet — the same Caddy beginner guide pattern every self-hosted app uses. With the worker running, registration locked, retention set, and HTTPS in front, the instance is production-shaped.

Sources

• GlitchTip project (gitlab.com/glitchtip/glitchtip-backend) — GitLab API: 363 stars, last activity 2026-10-30, latest tag v6.2.6 (2026-08-07), MIT license; the github.com/GlitchTip/GlitchTip repo is a 3-star placeholder with 0 releases — GitLab is the real home; fetched 2026-11-01.
• GlitchTip 6.2 release blog (glitchtip.com, June 22, 2026) — performance-monitoring improvements, OTel log ingest, subscription-usage page refresh, "MIT, 100% open source software"; fetched 2026-11-01.
• GlitchTip install docs (glitchtip.com/documentation/install) — docker compose arc (copy compose.sample.yml → edit env → docker compose up -d), required env vars SECRET_KEY / EMAIL_URL / DEFAULT_FROM_EMAIL / GLITCHTIP_DOMAIN / DATABASE_URL (PostgreSQL 14+), optional VALKEY_URL / ENABLE_USER_REGISTRATION / GLITCHTIP_EMBED_WORKER / GLITCHTIP_ENABLE_UPTIME, port 8000, image glitchtip/glitchtip, sample compose ships postgres:18 + valkey/valkey:9, 512 MB recommended; fetched 2026-11-01.
• GlitchTip retention docs (glitchtip.com) — GLITCHTIP_RETENTION_DAYS (default 90), GLITCHTIP_EVENT_HOT_DAYS 30, GLITCHTIP_LOG_HOT_DAYS 7, GLITCHTIP_RELEASE_RETENTION_DAYS 365, hot/cold PostgreSQL → Parquet via DuckDB; fetched 2026-11-01.
• GlitchTip error-tracking docs (glitchtip.com/documentation/error-tracking) — project DSN on the Issues page, glitchtip-cli sourcemaps inject/upload, alerts (email default, "Add An Alert Recipient" webhooks); fetched 2026-11-01.
• dev.to/andymunro "Moving Off Per-Seat SaaS" (2026-10-29) — full self-host migration walkthrough: DSN-swap lesson (change SENTRY_DSN, staging first, rollback = change it back), staged order (analytics → error tracking → passwords), worker-must-run gotcha, migrate Exited (0) normal, pin image versions, shared Postgres/Redis, init SQL first-start only; fetched 2026-11-01.
• dev.to/ericwoooo_kr "5 Lightweight Self-Hosted Error Trackers" (~94 days ago) — GlitchTip as Sentry replacement, GLITCHTIP_MAX_EVENT_LIFE_DAYS (default 90) retention name in third-party guides, DSN-swap migration framing; fetched 2026-11-01.
• selfhostingsh GlitchTip-vs-Sentry comparison (~232 days) — Sentry SDKs work verbatim, supported SDK list (Python, JS/Node, Go, Ruby, PHP, Java, .NET, Rust, Elixir, Flutter, React Native), advanced features (session replay, profiling, AI triage) unsupported; fetched 2026-11-01.
• Railway template docs for GlitchTip (~90-147 days) — DSN-swap compatibility claim, worker/migrate service commands (./bin/run-celery-with-beat.sh, ./manage.py migrate); fetched 2026-11-01.
• freedzhost homelab guide (11 days) — current Docker arc details, env vars DATABASE_URL / REDIS_URL / SECRET_KEY / GLITCHTIP_DOMAIN; fetched 2026-11-01.
• shape.host "How to Install GlitchTip on Debian 12" (~353 days) — Debian install arc; fetched 2026-11-01.
• Clever Cloud blog "GlitchTip on Clever Cloud" (~336 days) — PaaS deploy arc; fetched 2026-11-01.

Frequently Asked Questions

Is GlitchTip free?

Yes. GlitchTip is MIT-licensed and 100% open source — the software costs nothing. You pay only for the server it runs on, which is the whole point: unlimited events for the price of one small VPS, instead of per-seat SaaS pricing.

Do I need to rewrite my code to switch from Sentry to GlitchTip?

No. GlitchTip accepts events from Sentry's own SDKs, so migration is changing the DSN string in your configuration — app code stays identical. Test it in staging first, and the rollback is changing the DSN back.

How much server does GlitchTip need?

Very little by self-hosted standards: 512 MB of RAM is recommended, and all-in-one mode (web + worker in one container via GLITCHTIP_EMBED_WORKER) runs in 256 MB. A basic VPS handles personal and small-team workloads comfortably.

What happens if GlitchTip's worker stops?

Events get accepted by the web service but are never processed — they silently pile up with no issues appearing. If errors stop showing after a DSN change, check that the worker container is running before debugging anything else.

Does GlitchTip do uptime monitoring too?

Yes. Built-in uptime monitors poll your URLs on a schedule and alert on outages, enabled by default. For the opposite failure mode — jobs that never run — pair it with a dead-man's-switch tool like Healthchecks.