Skip to content
Klutch.sh Docs

Deploying a GlitchTip App

Introduction

GlitchTip is an open-source error tracking platform that is compatible with the Sentry SDK. It provides powerful error tracking, performance monitoring, and uptime monitoring capabilities for applications across multiple languages and frameworks. Deploying GlitchTip on Klutch.sh provides you with a self-hosted, cost-effective solution for monitoring your applications with full control over your data, persistent storage for error logs, and seamless deployment automation.

This comprehensive guide covers deploying GlitchTip on Klutch.sh using a Dockerfile, configuring persistent storage for PostgreSQL data and media uploads, setting up environment variables, and implementing production best practices for a reliable error tracking infrastructure.

Prerequisites

  • A Klutch.sh account (sign up here)
  • A GitHub repository for your GlitchTip deployment
  • Basic knowledge of Docker and environment variables
  • A PostgreSQL database (can be deployed on Klutch.sh or use an external managed service)
  • Optional: Redis instance for caching and task queue (recommended for production)

What is GlitchTip?

GlitchTip is a Sentry-compatible error tracking platform that helps you monitor and debug applications in production. Key features include:

  • Error Tracking: Capture and organize application errors with detailed stack traces and context
  • Performance Monitoring: Track application performance metrics and identify bottlenecks
  • Uptime Monitoring: Monitor your services and receive alerts when they go down
  • Multi-Project Support: Track errors across multiple applications and environments
  • Team Collaboration: Organize teams and projects with role-based access control
  • Sentry SDK Compatible: Works with existing Sentry SDKs across all major languages

1. Prepare Your Repository

Create a new GitHub repository for your GlitchTip deployment or use an existing one. Your repository structure should include:

  • Dockerfile - Defines the container image for GlitchTip
  • .env.example - Sample environment variables (never commit actual secrets)
  • README.md - Documentation for your deployment

Store sensitive data like database credentials and secret keys as environment variables in Klutch.sh, never commit them to your repository.

Refer to the Klutch.sh Quick Start Guide for repository setup and GitHub integration.

2. Understanding GlitchTip Architecture

GlitchTip consists of several components:

  • Web Application: Django-based web interface for viewing errors and managing projects
  • Background Workers: Celery workers for processing events asynchronously
  • PostgreSQL Database: Stores error data, user accounts, and configuration
  • Redis (optional but recommended): Used for caching and as a message broker for Celery
  • Media Storage: Stores uploaded files and attachments

For a production deployment, you’ll need to deploy GlitchTip web service, and optionally set up separate worker services for better scalability.

3. Sample Dockerfile

GlitchTip automatically detects a Dockerfile in your repository root. Here’s a production-ready Dockerfile for GlitchTip:

FROM glitchtip/glitchtip:latest


# Set working directory
WORKDIR /code


# The official GlitchTip image includes all necessary dependencies
# Environment variables will be configured in Klutch.sh


# Expose the default port
EXPOSE 8000


# The base image provides the default command to run GlitchTip
# For web service: gunicorn server
# For worker service: celery worker

For a minimal deployment, this Dockerfile is sufficient as the official GlitchTip image is well-configured. You can extend it with custom configurations if needed:

FROM glitchtip/glitchtip:latest


WORKDIR /code


# Optional: Add custom Django settings
# COPY custom_settings.py /code/


# Optional: Install additional Python packages
# COPY requirements.txt /code/
# RUN pip install --no-cache-dir -r requirements.txt


EXPOSE 8000

4. Deploying GlitchTip on Klutch.sh

Follow these steps to deploy GlitchTip:

    Step 1: Set Up PostgreSQL Database

    GlitchTip requires a PostgreSQL database. You can either:

    • Deploy PostgreSQL on Klutch.sh as a separate app
    • Use an external managed PostgreSQL service (e.g., AWS RDS, Digital Ocean Managed Database)

    To deploy PostgreSQL on Klutch.sh:

    1. Create a new app in your Klutch.sh project

    2. Use a PostgreSQL Docker image (e.g., postgres:15)

    3. Select TCP traffic in the UI

    4. Set the internal port to 5432 (PostgreSQL’s default port)

    5. Add a persistent volume with mount path /var/lib/postgresql/data (recommended size: 10GB+)

    6. Set environment variables:

      • POSTGRES_DB: glitchtip
      • POSTGRES_USER: glitchtip
      • POSTGRES_PASSWORD: your-secure-password (mark as secret)

    7. Connect to PostgreSQL on port 8000 from other apps (e.g., postgresql-app.klutch.sh:8000)

    Step 2: Optional - Set Up Redis

    For production deployments, Redis is recommended for caching and as a Celery message broker:

    1. Create a new app in your Klutch.sh project
    2. Use the Redis Docker image (e.g., redis:7-alpine)
    3. Select TCP traffic in the UI
    4. Set the internal port to 6379
    5. Optionally add a persistent volume with mount path /data for persistence
    6. Connect to Redis on port 8000 from other apps (e.g., redis-app.klutch.sh:8000)

    Step 3: Create GlitchTip Web Service

    1. Push your repository (with the Dockerfile) to GitHub

    2. In Klutch.sh dashboard, create a new app

    3. Connect your GitHub repository and select the branch

    4. Select HTTP traffic in the UI

    5. Set the internal port to 8000 (GlitchTip’s default port)

    6. Add a persistent volume:

      • Mount path: /code/media
      • Size: 5GB or more (for uploaded attachments)

    7. Configure environment variables (see section 5 below)

    8. Click “Create” to deploy

    Step 4: Run Database Migrations

    After the initial deployment, you need to run Django migrations to set up the database schema:

    1. Access the Klutch.sh dashboard and navigate to your GlitchTip app
    2. Use the console or logs to execute:
      Terminal window
      ./manage.py migrate

    Alternatively, you can create a separate one-time job or initialization script that runs migrations before starting the web service.

    Step 5: Create Superuser Account

    Create an admin account to access the GlitchTip interface:

    Terminal window
    ./manage.py createsuperuser

    Follow the prompts to set up your admin username, email, and password.

    Step 6: Optional - Deploy Celery Workers

    For better performance and scalability, deploy Celery workers as separate apps:

    1. Create a new app using the same Dockerfile
    2. Select HTTP traffic in the UI
    3. Set the internal port to 8000
    4. Use the same environment variables as the web service
    5. Override the start command using environment variables:
      • Add CELERY_WORKER_CONCURRENCY=4 (adjust based on your needs)
      • The worker will automatically start if the image detects it should run workers

    Note: The official GlitchTip image can run as either a web service or worker based on configuration.

5. Environment Variables

Configure these environment variables in the Klutch.sh dashboard. Mark sensitive values as secrets to prevent them from being logged.

Required Variables

# Secret key for Django - generate a random 50+ character string
SECRET_KEY=your-very-long-random-secret-key-here


# Database configuration
DATABASE_URL=postgresql://glitchtip:your-secure-password@postgresql-app.klutch.sh:8000/glitchtip


# Email configuration for notifications
EMAIL_URL=smtp://username:password@smtp.example.com:587/?tls=True


# Default from email
GLITCHTIP_DOMAIN=https://example-app.klutch.sh
DEFAULT_FROM_EMAIL=noreply@example.com
# Redis for caching and Celery broker
REDIS_URL=redis://redis-app.klutch.sh:8000/0
CELERY_BROKER_URL=redis://redis-app.klutch.sh:8000/0


# Enable debug mode (only for development, never in production)
DEBUG=False


# Allowed hosts (your Klutch.sh domain)
ALLOWED_HOSTS=example-app.klutch.sh


# Security settings
SECURE_SSL_REDIRECT=True
SESSION_COOKIE_SECURE=True
CSRF_COOKIE_SECURE=True


# File upload settings
ENABLE_USER_REGISTRATION=False
GLITCHTIP_MAX_EVENT_LIFE_DAYS=90

Celery Worker Variables (for worker apps)

# Same variables as web service plus:
CELERY_WORKER_CONCURRENCY=4
CELERY_WORKER_MAX_TASKS_PER_CHILD=1000

Generating a Secret Key

You can generate a secure secret key using Python:

Terminal window
python -c "import secrets; print(secrets.token_urlsafe(50))"

Or use an online generator, ensuring it’s at least 50 characters long and contains a mix of letters, numbers, and special characters.

6. Persistent Storage Configuration

GlitchTip requires persistent storage for:

  1. Media Files: User uploads and attachments
  2. PostgreSQL Data: Database files (if running PostgreSQL on Klutch.sh)
  3. Redis Data (optional): For persistent caching

GlitchTip Web Service Volumes

In the Klutch.sh app settings, add a persistent volume:

  • Mount path: /code/media
  • Size: 5GB minimum (adjust based on expected upload volume)

PostgreSQL Volumes

For PostgreSQL app:

  • Mount path: /var/lib/postgresql/data
  • Size: 10GB minimum (adjust based on error volume and retention)

Redis Volumes (Optional)

For Redis app:

  • Mount path: /data
  • Size: 1-5GB (depending on cache requirements)

7. Getting Started with GlitchTip

After deployment, access your GlitchTip instance and set up error tracking:

Step 1: Access the Web Interface

Navigate to your app URL (e.g., https://example-app.klutch.sh) and log in with your superuser credentials.

Step 2: Create an Organization and Project

  1. Click “Create Organization” and provide a name
  2. Within the organization, create a new project
  3. Select the platform/language you’ll be monitoring (e.g., Python, JavaScript, etc.)

Step 3: Get Your DSN

After creating a project, GlitchTip will provide a DSN (Data Source Name). This is the connection string your applications will use to send errors to GlitchTip.

Example DSN format:

https://<public_key>@example-app.klutch.sh/<project_id>

Step 4: Install Sentry SDK in Your Application

GlitchTip is compatible with Sentry SDKs. Install the appropriate SDK for your platform:

Python:

Terminal window
pip install sentry-sdk
import sentry_sdk


sentry_sdk.init(
    dsn="https://<public_key>@example-app.klutch.sh/<project_id>",
    traces_sample_rate=1.0,
)

JavaScript/Node.js:

Terminal window
npm install @sentry/node
const Sentry = require("@sentry/node");


Sentry.init({
  dsn: "https://<public_key>@example-app.klutch.sh/<project_id>",
  tracesSampleRate: 1.0,
});

Other Languages:

Visit the Sentry SDK documentation for integration guides for your specific language or framework.

Step 5: Test Error Tracking

Send a test error to verify the integration:

Python:

try:
    1 / 0
except Exception as e:
    sentry_sdk.capture_exception(e)

JavaScript:

try {
  throw new Error("Test error");
} catch (e) {
  Sentry.captureException(e);
}

Check your GlitchTip dashboard to see the error appear.

8. Production Best Practices

Security

  • Never commit secrets: Store all sensitive data in Klutch.sh environment variables marked as secrets
  • Use strong passwords: Generate secure passwords for database and admin accounts
  • Enable HTTPS only: Set SECURE_SSL_REDIRECT=True and related security headers
  • Restrict registration: Set ENABLE_USER_REGISTRATION=False unless you need public signups
  • Regular updates: Keep GlitchTip updated by pulling the latest Docker image tags

Performance

  • Deploy Celery workers: Separate worker processes improve response time and reliability
  • Use Redis: Enable caching and async task processing with Redis
  • Configure retention: Set GLITCHTIP_MAX_EVENT_LIFE_DAYS to automatically clean up old events
  • Monitor resources: Watch CPU, memory, and disk usage; scale instances as needed
  • Database indexing: Ensure PostgreSQL is properly tuned for your workload

Reliability

  • Database backups: Regularly backup your PostgreSQL database
  • Volume backups: Back up the media volume containing uploads
  • Health checks: Monitor GlitchTip’s health endpoint at /api/health/
  • Separate environments: Use different GlitchTip instances for development, staging, and production
  • Multi-instance deployment: Run multiple web service instances for high availability

Monitoring

  • Set up uptime monitoring: Use GlitchTip’s own uptime monitoring features
  • Configure email alerts: Set up email notifications for critical errors
  • Monitor disk usage: Events and media files can grow quickly; monitor volume usage
  • Track performance: Use GlitchTip’s performance monitoring to identify slow transactions

Maintenance

  • Regular cleanup: Run periodic database maintenance and remove old events
  • Update images: Periodically update to newer GlitchTip versions
  • Review logs: Check application logs for warnings or issues
  • Optimize database: Run PostgreSQL VACUUM and ANALYZE commands periodically

9. Troubleshooting

Common Issues

Database Connection Errors:

  • Verify DATABASE_URL is correctly formatted
  • Ensure PostgreSQL app is running and accessible on port 8000
  • Check that the database, user, and password match your PostgreSQL configuration

Static Files Not Loading:

  • Run ./manage.py collectstatic to collect static files
  • Verify persistent volume is mounted at /code/media

Celery Tasks Not Processing:

  • Verify CELERY_BROKER_URL points to your Redis instance
  • Ensure Redis app is running and accessible
  • Check Celery worker logs for errors

Email Notifications Not Sending:

  • Verify EMAIL_URL is correctly formatted
  • Test SMTP credentials and connectivity
  • Check firewall rules if using external SMTP server

High Memory Usage:

  • Reduce Celery worker concurrency
  • Optimize database queries and indexes
  • Increase instance resources or scale horizontally

10. Scaling GlitchTip

As your error volume grows, consider these scaling strategies:

Horizontal Scaling

  • Deploy multiple web service instances behind Klutch.sh’s load balancing
  • Run multiple Celery worker instances for parallel event processing
  • Use separate workers for different task types (events, uptime monitoring, etc.)

Vertical Scaling

  • Increase CPU and memory allocation for database and web services
  • Use larger persistent volumes for growing data
  • Optimize PostgreSQL configuration for higher throughput

External Services

  • Use managed PostgreSQL (AWS RDS, Digital Ocean) for better performance
  • Use managed Redis (AWS ElastiCache, Redis Cloud) for reliability
  • Consider object storage (S3) for media files in very large deployments

11. Migration from Sentry

If you’re migrating from Sentry to GlitchTip:

  1. Update SDKs: No changes needed - GlitchTip uses the same Sentry SDK
  2. Update DSN: Replace your Sentry DSN with your GlitchTip DSN in your applications
  3. Export data: Sentry doesn’t provide direct export; historical data will start fresh in GlitchTip
  4. Recreate projects: Set up your project structure in GlitchTip to match your Sentry organization
  5. Configure alerts: Set up notification rules in GlitchTip to match your previous alerts

12. Resources

Summary

Deploying GlitchTip on Klutch.sh provides you with a powerful, self-hosted error tracking solution that’s compatible with Sentry SDKs. With support for persistent storage, horizontal scaling, and seamless integration with your CI/CD pipeline through GitHub, you can maintain full control over your error tracking infrastructure while keeping costs predictable.

This guide covered everything from initial deployment with Docker to production best practices, environment configuration, and scaling strategies. With GlitchTip running on Klutch.sh, you have a robust foundation for monitoring your applications and catching errors before they impact your users.