Glitchtip

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

Resource	URL
Hosted (US)	app.glitchtip.com
Hosted (EU)	eu.glitchtip.com
SDK docs	glitchtip.com/sdkdocs
Install guide	glitchtip.com/documentation/install
CLI (gtc)	pip install glitchtip-cli

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

Variable	Purpose
SECRET_KEY	Random string for Django security
DATABASE_URL	PostgreSQL 14+ connection string
GLITCHTIP_DOMAIN	Full URL with scheme (https://glitchtip.example.com)
DEFAULT_FROM_EMAIL	Sender address for notifications

Email

Method	Config
SMTP	EMAIL_URL=smtp://user:pass@host:port
Mailgun	MAILGUN_API_KEY + EMAIL_BACKEND=anymail.backends.mailgun.EmailBackend
SendGrid	SENDGRID_API_KEY + EMAIL_BACKEND=anymail.backends.sendgrid.EmailBackend
Console (dev)	EMAIL_URL=consolemail://

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

Data Retention

Variable	Default
GLITCHTIP_MAX_EVENT_LIFE_DAYS	90
GLITCHTIP_MAX_TRANSACTION_EVENT_LIFE_DAYS	(inherits above)
GLITCHTIP_MAX_FILE_LIFE_DAYS	(inherits above)
GLITCHTIP_MAX_UPTIME_CHECK_LIFE_DAYS	(inherits above)

Cache & Workers

Variable	Default	Purpose
VALKEY_URL	—	redis://:pass@host:port/db (Valkey/Redis 7+)
DATABASE_POOL_MAX_SIZE	20	psycopg connection pool
GRANIAN_WORKERS	1	Web server workers (async, rarely needs >1)
VTASKS_CONCURRENCY	20	Background task concurrency

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

Feature Flags & Security

Variable	Default	Purpose
ENABLE_USER_REGISTRATION	true	Allow self-signup
ENABLE_ORGANIZATION_CREATION	false	Allow users to create orgs
GLITCHTIP_ENABLE_UPTIME	true	Uptime monitoring
GLITCHTIP_ENABLE_MCP	false	Model Context Protocol server
ENABLE_OBSERVABILITY_API	false	Prometheus metrics
ALLOWED_HOSTS	*	Comma-separated allowed domains
CSRF_TRUSTED_ORIGINS	—	Reverse proxy origins
BASE_PATH	—	Subpath hosting (/glitchtip)

File Storage

Backend	DEFAULT_FILE_STORAGE	Key Variables
AWS S3 / DO Spaces	storages.backends.s3boto3.S3Boto3Storage	AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_STORAGE_BUCKET_NAME
Azure Blob	storages.backends.azure_storage.AzureStorage	AZURE_ACCOUNT_NAME, AZURE_ACCOUNT_KEY, AZURE_CONTAINER
GCS	storages.backends.gcloud.GoogleCloudStorage	GS_BUCKET_NAME, GS_PROJECT_ID, GOOGLE_APPLICATION_CREDENTIALS

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

Gotcha	Detail
.sentryclirc ignored	Bundler plugin v2 no longer reads .sentryclirc — pass config via plugin options or env vars (SENTRY_URL, SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT)
CLI calls sentry.io	--url is a global flag — must come before the subcommand, not after
Auth token vs DSN	DSN = SDK event ingestion. Auth token = CLI/API operations (Profile > Auth Tokens). Do not mix them
Upload succeeds, UI empty	CLI output can be decoupled from server persistence — always check server logs for 500s
releases finalize fails	Not fully supported on GlitchTip — skip finalize, rely on release creation + artifact upload
Proxy/TLS false 401	Corporate proxies cause "Invalid token" errors — enable sentry-cli --log-level debug, verify proxy env vars are full URLs

Uptime Monitoring

Four monitor types:

Type	Behavior
Ping	HTTP HEAD request (most common)
GET	HTTP GET, validates expected status code
POST	HTTP POST, validates expected status code
Heartbeat	Awaits inbound requests from your app at a generated URL

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

Tool	Setup
GitLab	Settings > Monitor > Error Tracking > Sentry provider > GlitchTip URL + Auth Token
Grafana	Data source > Sentry type > GlitchTip URL + org + Auth Token

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

Issue	Fix
Events not appearing	Verify DSN, check SDK sampleRate, confirm GLITCHTIP_DOMAIN matches
High event volume	Lower traces_sample_rate / sample_rate in SDK config
Email not sending	Check EMAIL_URL or provider API key, try consolemail:// for debugging
401 on API/integration	Regenerate Auth Token in Profile > Auth Tokens
Worker not processing	Check VALKEY_URL, ensure worker container running, verify VTASKS_CONCURRENCY
Out of memory	Use all-in-one mode (compose.minimal.yml) or increase RAM to 512MB+
Uptime checks failing	Verify monitor URL accessible from GlitchTip server, check expected status code
Social auth not working	Verify callback URL, check Django Admin socialaccount config
Search not working	Check PostgreSQL text_search_config for non-English languages
Disk growing fast	Lower GLITCHTIP_MAX_EVENT_LIFE_DAYS, check source map / file retention
404 on /artifactbundle/assemble/	GlitchTip doesn't support artifact-bundle flow — switch to uploadLegacySourcemaps or releases files upload-sourcemaps
"Nothing to upload" but UI empty	Check file storage config (S3/volume), inspect server logs for 500s on assemble endpoint
debug_id_or_release_required	Upload only .js + .map pairs, not entire dist/ — remove files without matching maps
files_fileblob_checksum_key duplicate	Clean release artifacts before re-uploading identical builds; upload is not idempotent
releases finalize → "version required"	Skip finalize — not fully supported on GlitchTip. Use release creation + artifact upload only
CLI sends to sentry.io unexpectedly	--url must precede subcommand; check .sentryclirc defaults.url; bundler plugin v2 ignores .sentryclirc
Stack traces stay minified	Verify: (1) storage has files, (2) release value matches SDK init, (3) --url-prefix matches runtime paths

Common Mistakes

Mistake	Fix
Using Sentry SDK features unsupported by GlitchTip	Check GlitchTip compatibility — no performance tracing, no replays
Missing GLITCHTIP_DSN env var	SDK silently drops events without a valid DSN
Source maps not matching release version	sentry-cli releases files <release> upload-sourcemaps must match release in SDK init
Running without Redis/Celery workers	Events queue but never process — always run celery-worker service
Setting DEBUG=True in production	Leaks secrets in error pages; use ENVIRONMENT=production