GlitchTip

Open-source, Sentry API-compatible error tracking and uptime monitoring. Django + PostgreSQL backend, Angular frontend. Runs on 256MB RAM (all-in-one) or 512MB (standard).

• Site: https://glitchtip.com
• Docs: https://glitchtip.com/documentation
• API: https://app.glitchtip.com/api/docs
• Repo: https://gitlab.com/glitchtip/glitchtip-backend
• License: MIT

When to Use

• Deploying GlitchTip self-hosted (Docker Compose, Helm, or manual)
• Integrating Sentry SDKs (Python, JS, Ruby, etc.) with a GlitchTip DSN
• Configuring source maps upload via sentry-cli
• Setting up uptime monitoring and alerting (email, webhooks)
• Troubleshooting event ingestion, worker failures, or Celery issues
• Migrating from Sentry to GlitchTip

When NOT to Use

• Sentry SaaS (sentry.io) — compatible SDK-side, but different server admin
• Application Performance Monitoring (APM) — GlitchTip is error tracking only

Quick Reference

Deployment

Docker Compose (recommended)

# Download sample compose file
curl -sLO https://glitchtip.com/assets/docker-compose.sample.yml
mv docker-compose.sample.yml compose.yml
# Edit environment variables, then:
docker compose up -d
# Upgrade: docker compose pull && docker compose stop && docker compose up -d

Minimal variant: compose.minimal.yml — all-in-one mode, ~256MB RAM.

Kubernetes (Helm)

helm repo add glitchtip https://gitlab.com/api/v4/projects/16325141/packages/helm/stable
helm install glitchtip glitchtip/glitchtip

Externally managed PostgreSQL recommended. Supports pod disruption budgets and anti-affinity for HA.

Managed Platforms

PikaPods, Elestio, Nodion, Railway (one-click template), RepoCloud.

Configuration

All via environment variables. Set in compose.yml or Helm values.

Required

Email

Also supports Postmark, Mailjet, Mandrill, SparkPost, Brevo via Anymail.

Data Retention

Cache & Workers

Set VALKEY_URL to empty string to disable and use PostgreSQL as queue.

Feature Flags & Security

File Storage

SDK Integration

GlitchTip uses Sentry SDKs — 58 implementations across 18 languages. Configure any Sentry SDK by pointing the DSN to the GlitchTip instance:

https://<SENTRY_KEY>@<GLITCHTIP_DOMAIN>/<PROJECT_ID>

Find the DSN in Project Settings > Security Endpoint.

Supported Platforms

JavaScript: Browser, React, Angular, Vue, Ember, Next.js, Backbone Node.js: Express, Koa, Connect, plain Node Python: Django, Flask, Celery, FastAPI (ASGI), AWS Lambda, WSGI, + 10 more PHP: Laravel, Symfony, Drupal, Monolog Ruby: Rails, Rack Java: Android, Log4j, Logback, App Engine Go: net/http, plain Go C#: ASP.NET Core Rust, Elixir, Flutter, React Native, Electron, Cordova, C/C++, Objective-C

Reduce Event Volume

sentry_sdk.init(
    dsn="...",
    traces_sample_rate=0.01,  # 1% of transactions
    sample_rate=0.5,          # 50% of errors
)

Source Maps (sentry-cli)

GlitchTip is Sentry API-compatible but does not support the newer artifact-bundle/debug-ID upload flow. Use legacy release-based uploads only.

• SDK docs: https://glitchtip.com/sdkdocs
• Install/storage guide: https://glitchtip.com/documentation/install

Prerequisites: File storage must be configured (S3/Azure/GCS or local volume) — source maps are storage-backed, not just metadata.

Discover Org & Project Slugs

# Slugs ≠ display names. Query the API to find correct values:
curl -s https://<GLITCHTIP_DOMAIN>/api/0/projects/ \
  -H "Authorization: Bearer <AUTH_TOKEN>" | jq '.[].slug'

Legacy Upload Workflow

# 1. Set release in your SDK init: release: "<RELEASE_ID>"
# 2. Build with source maps enabled
# 3. Upload (--url is a GLOBAL flag, must precede subcommand):
sentry-cli --url https://<GLITCHTIP_DOMAIN> releases \
  --org <org-slug> --project <project-slug> \
  files "<RELEASE_ID>" upload-sourcemaps ./dist \
  --url-prefix "~/"

Bundler Plugin (Vite/Webpack/esbuild/Rollup)

// Use uploadLegacySourcemaps — the default artifact-bundle mode
// triggers 404 on GlitchTip's /artifactbundle/assemble/ endpoint
sentryPlugin({
  url: "https://<GLITCHTIP_DOMAIN>",  // REQUIRED — defaults to sentry.io
  authToken: process.env.SENTRY_AUTH_TOKEN,
  org: "<org-slug>",
  project: "<project-slug>",
  release: { uploadLegacySourcemaps: "./dist" },
})

Next.js Specifics

• Set productionBrowserSourceMaps: true in next.config.js
• Pass sentryUrl (not url) into withSentryConfig
• Watch for trailing slashes in the instance URL — they can break uploads

Gotchas

Uptime Monitoring

Four monitor types:

Link monitors to a project with email alerts configured for status change notifications.

Integrations

Alerting

Configure in Projects > Alert Recipients:

• Email: Team member notifications on error frequency thresholds
• Webhooks: POST to any URL on alert trigger

External Tools

Auth tokens: Profile > Auth Tokens (scope: read-only or full).

Social Auth (OAuth)

Configure via Django Admin (/admin/socialaccount/socialapp/):

GitHub, GitLab, Google, Microsoft, Gitea, DigitalOcean, NextCloud, Okta, OpenID Connect (Keycloak, etc.)

Callback URL: https://example.com/accounts/<provider>/login/callback/

OpenID Connect settings:

{ "server_url": "https://idp.example.com/auth/realms/realm/.well-known/openid-configuration" }

CLI Tool (gtc)

pip install glitchtip-cli
gtc list      # list organizations
gtc create    # create organization
gtc delete    # delete organization
gtc members   # show org membership

First run prompts for API token and instance URL. Config saved to .env.

Troubleshooting

Common Mistakes