Skip to content
Klutch.sh Docs

Deploying a Bugsink App

Introduction

Bugsink is a self-hosted, open-source error tracking platform that is Sentry-SDK compatible. It provides a scalable and reliable way to monitor and track errors in your applications. Deploying Bugsink on Klutch.sh gives you complete control over your error tracking infrastructure with automatic HTTPS, persistent storage for your error data, and seamless scaling capabilities.

This comprehensive guide walks you through deploying Bugsink on Klutch.sh using a Dockerfile, setting up persistent storage for your database and media files, configuring environment variables, connecting to PostgreSQL, and following production best practices for a robust error tracking system.

Prerequisites

Before you begin, ensure you have:

  • A Klutch.sh account
  • A GitHub repository for your Bugsink deployment
  • Basic knowledge of Docker, error tracking systems, and environment variables
  • (Optional, recommended for production) A managed PostgreSQL database or Klutch.sh PostgreSQL instance

Project Structure

A minimal repository layout for deploying Bugsink on Klutch.sh:

bugsink-deploy/
├── Dockerfile
├── bugsink_conf.py (optional custom configuration)
├── .dockerignore
└── README.md

For quick testing, you can use the official Bugsink Docker image. For production deployments with custom configurations, you may want to extend the base image.

Step 1: Prepare Your Bugsink Repository

  1. Create a new GitHub repository or fork an existing one for your Bugsink deployment. If you’re creating a new repository, initialize it with a README.

  2. Clone your repository locally:

    Terminal window
    git clone https://github.com/yourusername/bugsink-deploy.git
    cd bugsink-deploy

  3. Ensure sensitive data like database credentials and secret keys are never committed to the repository. These will be configured as environment variables in Klutch.sh.

For more information on connecting your GitHub repository, see the Klutch.sh Quick Start Guide.

Step 2: Create the Dockerfile

Bugsink provides an official Docker image that can be used directly. Create a Dockerfile in your repository root:

FROM bugsink/bugsink:latest


# The official image already includes all necessary dependencies
# Default port is 8000
EXPOSE 8000

Option B: Custom Build with PostgreSQL Support

For production deployments with PostgreSQL and custom configurations:

ARG PYTHON_VERSION=3.12


# Build image for creating wheels
FROM python:${PYTHON_VERSION} AS build


# Build mysqlclient wheel (useful if you might switch to MySQL later)
RUN --mount=type=cache,target=/var/cache/buildkit/pip \
    pip wheel --wheel-dir /wheels mysqlclient


# Production image
FROM python:${PYTHON_VERSION}-slim


ENV PYTHONUNBUFFERED=1
ENV PORT=8000


WORKDIR /app


# Install MySQL client libraries (even if using PostgreSQL)
RUN apt-get update && \
    apt-get install -y default-libmysqlclient-dev git && \
    rm -rf /var/lib/apt/lists/*


# Copy and install wheels
COPY --from=build /wheels /wheels
RUN --mount=type=cache,target=/var/cache/buildkit/pip \
    pip install --find-links /wheels --no-index mysqlclient


# Install PostgreSQL adapter
RUN --mount=type=cache,target=/var/cache/buildkit/pip \
    pip install "psycopg[binary]"


# Install Bugsink
RUN --mount=type=cache,target=/var/cache/buildkit/pip \
    pip install bugsink


# Create bugsink user and data directory
RUN groupadd --gid 14237 bugsink && \
    useradd --uid 14237 --gid 14237 bugsink && \
    mkdir -p /data && \
    chown -R bugsink:bugsink /data


USER bugsink


# Health check
HEALTHCHECK CMD python -c 'import requests; requests.get("http://localhost:8000/health/ready").raise_for_status()'


# Start Bugsink with gunicorn
CMD ["sh", "-c", "bugsink-manage migrate && bugsink-manage migrate snappea --database=snappea && gunicorn --bind=0.0.0.0:$PORT --access-logfile - bugsink.wsgi"]


EXPOSE 8000

Create a .dockerignore File

Create a .dockerignore file to exclude unnecessary files from the Docker build:

.git
.github
*.md
.gitignore
.env
.env.*
*.pyc
__pycache__
.pytest_cache
*.log

Step 3: Set Up Persistent Storage

Bugsink requires persistent storage for its database (if using SQLite) and media files. Even when using an external PostgreSQL database, you’ll need storage for uploaded files and static assets.

  1. In the Klutch.sh dashboard, navigate to your project.

  2. Create a new volume for Bugsink data storage. Recommended size: Start with 10GB and scale up based on usage.

  3. When configuring your app deployment, attach the volume with the following mount path:

    /data

    This path will store:

    • SQLite database file (if not using PostgreSQL)
    • Uploaded media files
    • Static assets
    • Cache files

For more details on managing volumes, see the Klutch.sh Volumes Guide.

Step 4: Configure Environment Variables

Bugsink requires several environment variables for proper operation. Configure these in the Klutch.sh dashboard under your app’s environment settings.

Required Environment Variables

  1. SECRET_KEY (Required)

    Django secret key for cryptographic signing. Generate a secure random string of at least 50 characters:

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

    Set in Klutch.sh as a secret environment variable.

  2. PORT (Auto-configured)

    Bugsink listens on port 8000 by default. Configure your app in Klutch.sh to route HTTP traffic to port 8000.

  3. CREATE_SUPERUSER (Optional, for first-time setup)

    Format: username:password

    Example: admin:yourStrongPassword123

    This creates the initial admin user on first startup. Remove this variable after the first deployment for security.

Database Configuration (PostgreSQL - Recommended for Production)

For production deployments, use PostgreSQL instead of SQLite:

  1. DATABASE_URL (Recommended)

    The easiest way to configure PostgreSQL:

    postgresql://username:password@hostname:5432/database_name

    Example:

    postgresql://bugsink:secure_password@postgres.example.com:5432/bugsink_db

  2. Alternative: Individual database environment variables:

    DB_ENGINE=django.db.backends.postgresql
    DB_NAME=bugsink_db
    DB_USER=bugsink
    DB_PASSWORD=your_secure_password
    DB_HOST=postgres.example.com
    DB_PORT=5432

Optional Environment Variables

  • ALLOWED_HOSTS: Comma-separated list of allowed hostnames (e.g., example-app.klutch.sh,bugsink.example.com)
  • DEBUG: Set to false for production (default is false)
  • CSRF_TRUSTED_ORIGINS: Comma-separated list of trusted origins for CSRF protection
  • EMAIL_HOST: SMTP host for sending email notifications
  • EMAIL_PORT: SMTP port (default: 587)
  • EMAIL_HOST_USER: SMTP username
  • EMAIL_HOST_PASSWORD: SMTP password
  • EMAIL_USE_TLS: Set to true to use TLS (recommended)

Example Environment Configuration

For a production deployment with PostgreSQL:

SECRET_KEY=your-super-secret-key-of-at-least-50-characters-here
DATABASE_URL=postgresql://bugsink:secure_password@postgres-host:5432/bugsink
ALLOWED_HOSTS=example-app.klutch.sh,bugsink.yourdomain.com
DEBUG=false
CSRF_TRUSTED_ORIGINS=https://example-app.klutch.sh,https://bugsink.yourdomain.com
EMAIL_HOST=smtp.sendgrid.net
EMAIL_PORT=587
EMAIL_HOST_USER=apikey
EMAIL_HOST_PASSWORD=your_sendgrid_api_key
EMAIL_USE_TLS=true

⚠️ Important: Always mark sensitive variables (SECRET_KEY, passwords, API keys) as secret in the Klutch.sh dashboard to prevent them from being exposed in logs.

Step 5: Deploy to Klutch.sh

  1. Push your Dockerfile and any configuration files to your GitHub repository:

    Terminal window
    git add Dockerfile .dockerignore
    git commit -m "Add Bugsink Dockerfile configuration"
    git push origin main

  2. Log in to the Klutch.sh dashboard.

  3. Create a new app and connect your GitHub repository containing the Bugsink Dockerfile. Klutch.sh will automatically detect the Dockerfile in your repository root.

  4. Configure the deployment settings:

    • Traffic Type: Select HTTP
    • Internal Port: Set to 8000 (Bugsink’s default port)
    • Build Context: Leave as root (.) unless your Dockerfile is in a subdirectory

  5. Add all required environment variables as configured in Step 4. Make sure to mark sensitive values as secrets.

  6. Attach the persistent volume you created in Step 3 to mount path /data.

  7. (Optional) If you need to customize the build or start commands, you can set Nixpacks environment variables:

    • NIXPACKS_BUILD_CMD: Custom build command (if needed)
    • NIXPACKS_START_CMD: Custom start command (if needed)

    For Dockerfile deployments, these are typically not necessary as the Dockerfile defines the build and start process.

  8. Click “Deploy” to start the build and deployment process. Klutch.sh will:

    • Build your Docker image
    • Push it to the registry
    • Deploy the container
    • Set up HTTPS routing automatically

  9. Monitor the build logs in the Klutch.sh dashboard. The initial deployment may take a few minutes.

Once deployment is complete, your Bugsink instance will be available at https://example-app.klutch.sh (replace with your actual app URL).

Step 6: Initial Setup and Configuration

  1. Visit your Bugsink app URL (e.g., https://example-app.klutch.sh).

  2. If you set the CREATE_SUPERUSER environment variable, log in with those credentials. Otherwise, you’ll need to create a superuser through the Django admin interface.

  3. After logging in, navigate to the admin interface to:

    • Create your first project
    • Configure error tracking settings
    • Set up notification preferences
    • Generate DSN (Data Source Name) for connecting your applications

  4. Follow the Bugsink quickstart guide to configure your applications to send errors to your Bugsink instance.

  5. Remove the CREATE_SUPERUSER environment variable from your Klutch.sh app settings after the initial setup for security.

Step 7: Set Up PostgreSQL Database (Production)

For production deployments, using PostgreSQL instead of SQLite is highly recommended for better performance, reliability, and concurrent access.

  1. Provision a PostgreSQL database. You have several options:

    • Use a managed PostgreSQL service (recommended)
    • Deploy PostgreSQL on Klutch.sh as a separate app
    • Use an external PostgreSQL provider

  2. Create a dedicated database and user for Bugsink:

    CREATE DATABASE bugsink_db;
    CREATE USER bugsink WITH PASSWORD 'your_secure_password';
    GRANT ALL PRIVILEGES ON DATABASE bugsink_db TO bugsink;
    ALTER DATABASE bugsink_db OWNER TO bugsink;

  3. If your PostgreSQL database requires TCP traffic (common for database deployments on Klutch.sh), ensure your database app is configured for TCP traffic on port 8000. You’ll connect to it using the internal port 5432 within the application.

  4. Update your Bugsink app’s environment variables with the PostgreSQL connection details (as shown in Step 4).

  5. Redeploy your Bugsink app to apply the database configuration. Bugsink will automatically run migrations on startup.

Step 8: Production Best Practices

Security Hardening

  1. Strong SECRET_KEY: Use a cryptographically secure random key of at least 50 characters. Never commit it to version control.

  2. Database Credentials: Use strong, unique passwords for database users. Store all credentials as secret environment variables in Klutch.sh.

  3. HTTPS Only: Ensure CSRF_TRUSTED_ORIGINS includes only HTTPS URLs. Klutch.sh provides automatic HTTPS for all apps.

  4. Disable DEBUG: Always set DEBUG=false in production to prevent information disclosure.

  5. Regular Updates: Keep Bugsink updated by pulling the latest Docker image or updating the version tag in your Dockerfile.

  6. Access Control: Use strong passwords for admin accounts and consider implementing two-factor authentication if supported.

Performance Optimization

  • Database Indexing: Ensure proper database indexes are in place for frequently queried fields
  • Connection Pooling: PostgreSQL connection pooling can improve performance under load
  • Cache Configuration: Configure Django’s cache backend (Redis recommended) for better performance
  • Media Storage: For high-traffic instances, consider using object storage (S3-compatible) for media files

Backup Strategy

  1. Database Backups: Set up automated PostgreSQL backups using your database provider’s backup solution or pg_dump:

    Terminal window
    pg_dump -h postgres-host -U bugsink bugsink_db > bugsink-backup-$(date +%Y%m%d).sql

  2. Volume Backups: Regularly back up the /data volume containing uploaded files and configuration.

  3. Backup Testing: Periodically test your backups by restoring to a test environment.

Monitoring and Maintenance

  • Resource Monitoring: Monitor CPU, memory, and disk usage through the Klutch.sh dashboard
  • Log Monitoring: Regularly review application logs for errors and warnings
  • Health Checks: Bugsink includes a /health/ready endpoint for health checking
  • Database Maintenance: Perform regular PostgreSQL maintenance (VACUUM, ANALYZE)
  • Error Retention: Configure retention policies to prevent unlimited error data growth

Step 9: Troubleshooting

Common Issues and Solutions

Application Won’t Start

  1. Check the deployment logs in the Klutch.sh dashboard for error messages

  2. Verify all required environment variables are set correctly

  3. Ensure SECRET_KEY is at least 50 characters long

  4. Check that the internal port is set to 8000

Database Connection Errors

  1. Verify PostgreSQL credentials are correct

  2. Ensure the PostgreSQL host is accessible from your Bugsink app

  3. Check that the database exists and the user has proper permissions

  4. For Klutch.sh PostgreSQL deployments, ensure TCP traffic is properly configured

502 Bad Gateway or 503 Service Unavailable

  1. Check that your app is listening on 0.0.0.0:8000 (not just localhost)

  2. Review application logs for startup errors

  3. Ensure the health check endpoint is responding

  4. Verify environment variables are not causing startup failures

Permission Errors with Persistent Storage

  1. Ensure the container user has write permissions to /data

  2. Check that the volume is properly mounted

  3. Review file ownership within the container (should be owned by the bugsink user)

CSRF Verification Failed

  1. Ensure CSRF_TRUSTED_ORIGINS includes your app’s domain with https:// prefix

  2. Verify ALLOWED_HOSTS includes your domain

  3. Check that cookies are not being blocked by browser settings

Debug Commands

To inspect your deployment:

Terminal window
# View application logs
# (Use the Klutch.sh dashboard logs viewer)


# Check database connectivity (from a debug container)
psql -h postgres-host -U bugsink -d bugsink_db -c "SELECT version();"


# Verify Django settings (add to Dockerfile temporarily)
python manage.py check --deploy

Step 10: Connecting Applications to Bugsink

After deploying Bugsink, connect your applications to start tracking errors:

  1. Log in to your Bugsink dashboard and create a new project.

  2. Copy the DSN (Data Source Name) provided for your project.

  3. Install the Sentry SDK in your application (Bugsink is Sentry-compatible):

    Python:

    Terminal window
    pip install sentry-sdk

    JavaScript/Node.js:

    Terminal window
    npm install @sentry/node

    Other languages: See Sentry SDK documentation for your language.

  4. Configure the SDK with your Bugsink DSN:

    Python:

    import sentry_sdk
    

    sentry_sdk.init(
        dsn="https://your-dsn@example-app.klutch.sh/project-id",
        traces_sample_rate=1.0,
    )

    JavaScript/Node.js:

    const Sentry = require("@sentry/node");
    

    Sentry.init({
      dsn: "https://your-dsn@example-app.klutch.sh/project-id",
      tracesSampleRate: 1.0,
    });

  5. Test the integration by triggering a test error in your application. It should appear in your Bugsink dashboard within seconds.

Scaling Your Bugsink Deployment

As your error tracking needs grow, consider these scaling strategies:

  • Vertical Scaling: Increase CPU and memory resources in the Klutch.sh dashboard
  • Database Optimization: Upgrade to a larger PostgreSQL instance with more resources
  • Storage Expansion: Increase the size of your persistent volume as error data grows
  • Load Balancing: Deploy multiple Bugsink instances behind a load balancer for high availability
  • Cache Layer: Add Redis for improved performance with session and cache storage
  • Media Storage: Migrate to object storage (S3-compatible) for scalable media file storage

Resources

Deploying Bugsink on Klutch.sh provides you with a powerful, self-hosted error tracking solution that gives you complete control over your data while leveraging Klutch.sh’s managed infrastructure, automatic HTTPS, and seamless scaling capabilities. With proper configuration and following these best practices, you’ll have a production-ready error tracking system that can grow with your needs.