Error Observability

Self-hosted error tracking solution based on Bugsink - a lightweight, Sentry-compatible error monitoring platform.

Features

Sentry SDK Compatible - Works with all official Sentry SDKs (Python, JavaScript, PHP, Go, Ruby, Java, .NET, Rust, etc.)
Self-Hosted - Your data stays on your infrastructure
PostgreSQL 18 - Performance-tuned database with SSD/NVMe optimizations
Multi-Project Support - Optimized for ~100 projects per instance
Traefik Integration - Automatic HTTPS with Let's Encrypt
Dual-Stack Networking - IPv4 + IPv6 support

Quick Start

1. Generate Configuration

# Windows
tools\run.cmd
./scripts/generate-secrets.sh

# Linux/macOS
./tools/run.sh
./scripts/generate-secrets.sh

This creates .env from .env.example with secure random values for:

SECRET_KEY - Django secret key
DATABASE_PASSWORD - PostgreSQL password
CREATE_SUPERUSER - Initial admin credentials

2. Configure Environment

Edit .env and update:

# Required
SERVICE_HOSTNAME=errors.your-domain.com
PRIVATESUBNET=252  # Unique subnet ID (1-254)

# SMTP (for notifications)
EMAIL_HOST=smtp.your-domain.com
EMAIL_HOST_USER=your-smtp-user
EMAIL_HOST_PASSWORD=your-smtp-password

3. Deploy

With Traefik (recommended):

docker compose -f docker-compose.traefik.yml up -d

Standalone (without reverse proxy):

docker compose up -d

Local Development (port 8000 exposed):

docker compose -f docker-compose.development.yml up -d

4. Access

Open https://errors.your-domain.com and login with the credentials from .env:

Email: admin@example.com (or your configured email)
Password: (shown during secret generation)

Important: Remove CREATE_SUPERUSER from .env after first login.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Traefik Proxy                        │
│                 (HTTPS/Let's Encrypt)                   │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│                  Bugsink Server                         │
│               (Error Processing)                        │
│                                                         │
│  - Event ingestion (Sentry protocol)                    │
│  - Issue grouping & deduplication                       │
│  - Email notifications                                  │
│  - Web UI                                               │
└─────────────────────┬───────────────────────────────────┘
                      │
┌─────────────────────▼───────────────────────────────────┐
│              PostgreSQL 18 Database                     │
│           (SSD/NVMe performance tuning)                 │
└─────────────────────────────────────────────────────────┘

Compose Files

File	Description	Use Case
`docker-compose.traefik.yml`	With Traefik labels and dynamic naming	Production with Traefik proxy
`docker-compose.yml`	Standalone with static naming	Production with custom proxy
`docker-compose.development.yml`	With exposed port 8000	Local development

SDK Integration

Bugsink is compatible with Sentry SDKs. Example DSN format:

https://<project-key>@errors.your-domain.com/<project-id>

Python Example

import sentry_sdk

sentry_sdk.init(
    dsn="https://abc123@errors.your-domain.com/1",
    send_default_pii=True,      # Safe for self-hosted
    traces_sample_rate=0,        # Bugsink doesn't support traces
    environment="production",
)

JavaScript Example

import * as Sentry from "@sentry/browser";

Sentry.init({
    dsn: "https://abc123@errors.your-domain.com/1",
    sendDefaultPii: true,
    tracesSampleRate: 0,
    environment: "production",
});

More Languages

Complete integration examples are available for 10 languages:

Language	Example
Python	examples/python_example.py
Node.js	examples/nodejs_example.js
TypeScript	examples/typescript_example.ts
Java	examples/JavaExample.java
C# / .NET	examples/DotNetExample.cs
Go	examples/go_example.go
PHP	examples/php_example.php
Ruby	examples/ruby_example.rb
Rust	examples/rust_example.rs
C / C++	examples/cpp_example.cpp

Each example includes:

Full SDK initialization with configuration
User context and breadcrumbs
Error capturing and custom messages
Performance monitoring (transactions/spans)
Framework-specific integrations

See docs/CLIENT-SDK-EXAMPLES.md for the complete integration guide.

Automated Integration (Client-Kit)

Use the Client-Kit for quick, automated SDK integration:

# In your project directory
/path/to/client-kit/install.sh --dsn "https://key@errors.your-domain.com/1"

The installer will:

Detect your project language automatically
Install the SDK dependencies
Create a minimal configuration file
Add DSN to your .env file

Three modes available:

Mode	Command	Description
New Setup	`./install.sh`	Full installation
Update DSN	`./install.sh --update-dsn`	Change endpoint URL only
Update Client	`./install.sh --update-client`	Refresh templates

See client-kit/README.md for detailed documentation.

Configuration

Environment Variables

Variable	Default	Description
`SERVICE_HOSTNAME`	-	Public hostname (DNS must resolve)
`SECRET_KEY`	-	Django secret key (generate with openssl)
`DATABASE_PASSWORD`	-	PostgreSQL password
`PRIVATESUBNET`	`254`	Unique subnet ID (1-254)
`PROXY_NETWORK`	`traefik`	External Traefik network name

User Registration

Value	Description
`CB_ANYBODY`	Anyone can sign up (dangerous!)
`CB_MEMBERS`	Existing users can invite
`CB_ADMINS`	Only admins can invite (default)
`CB_NOBODY`	Registration disabled

Rate Limits (per project)

Instance Size	Projects	Events/5min	Events/hour
Small	1-10	1000	5000
Medium	10-50	2500	15000
Large	50-200	2500	15000
XLarge	200+	1500	10000

See docs/BUGSINK-CONFIGURATION.md for complete configuration reference.

Operations

View Logs

# All services
docker compose logs -f

# Bugsink only
docker compose logs -f bugsink-server

# Database only
docker compose logs -f database-server

Backup Database

docker compose exec database-server pg_dump -U bugsink bugsink > backup.sql

Restore Database

cat backup.sql | docker compose exec -T database-server psql -U bugsink bugsink

Update

docker compose pull
docker compose up -d

Directory Structure

.
├── docker-compose.yml              # Standalone deployment
├── docker-compose.traefik.yml      # Traefik deployment
├── docker-compose.development.yml  # Local development
├── .env.example                    # Configuration template
├── .env                            # Local configuration (git-ignored)
├── docs/
│   ├── BUGSINK-CONFIGURATION.md
│   ├── BUGSINK-QUICKSTART.md
│   ├── BUGSINK-SDK-CONFIGURATION.md
│   ├── CLIENT-SDK-EXAMPLES.md      # SDK integration guide
│   ├── SENTRY-SDK-INTEGRATION.md
│   └── SENTRY-SDK-COMPLETE-REFERENCE.md
├── client-kit/                     # SDK Integration Tool
│   ├── install.py                  # Main installer (Python)
│   ├── install.sh                  # Shell wrapper
│   ├── install.ps1                 # PowerShell wrapper
│   ├── install.cmd                 # Windows batch wrapper
│   ├── templates/                  # Minimal integration templates
│   │   ├── python/
│   │   ├── nodejs/
│   │   ├── typescript/
│   │   ├── java/
│   │   ├── dotnet/
│   │   ├── go/
│   │   ├── php/
│   │   └── ruby/
│   └── README.md
├── examples/                       # Full SDK examples (reference)
│   ├── python_example.py
│   ├── nodejs_example.js
│   ├── typescript_example.ts
│   ├── JavaExample.java
│   ├── DotNetExample.cs
│   ├── go_example.go
│   ├── php_example.php
│   ├── ruby_example.rb
│   ├── rust_example.rs
│   └── cpp_example.cpp
├── tools/
│   ├── Dockerfile              # Tools container
│   ├── run.cmd                 # Windows launcher
│   ├── run.sh                  # Linux/macOS launcher
│   └── run.ps1                 # PowerShell launcher
└── scripts/
    └── generate-secrets.sh     # Secret generation script

Bugsink Compatibility

This table shows which versions of this project are compatible with which Bugsink base versions. Always check for breaking changes before upgrading.

Release	Bugsink Version	Breaking Changes	Notes
1.0.2+	2.4.0+	No (default `BUGSINK_VERSION=2` tracks the newest 2.x)	Webhook and Jira backends pin connections to the validated IP, which needs `OriginalHostnameAdapter` from Bugsink 2.4.0. Our Teams backend is labeled "Microsoft Teams (Enhanced)" because Bugsink 2.5.1 added its own `msteams` backend.
0.12.0 – 1.0.1	2.1.x	Yes	SSRF protection via `BaseWebhookBackend`, `webhook_security` module required. All custom backends updated. New settings: `ALERTS_WEBHOOK_`, `MAX_EVENT_AGE_DAYS`, `MAX_STORED_FILE_`, proxy headers.
0.9.0 – 0.11.2	2.0.12 – 2.0.x	No	Initial stable release. Custom backends use direct `requests.post()`.
0.1.0 – 0.8.x	2.0.0 – 2.0.11	No	Early development. Manual view/template patching required.

Upgrade Guide: 2.0.x → 2.1.x

When upgrading Bugsink from 2.0.x to 2.1.x, the following changes apply:

Custom backends now inherit from BaseWebhookBackend (Teams, Generic Webhook, Jira) or use validate_webhook_url() against a fixed API host (GitHub, PagerDuty) for SSRF protection.
New environment variables are available in .env — see Webhook Security, Data Retention, and Proxy Headers.
Non-global IPs are blocked by default (ALERTS_WEBHOOK_DENY_NON_GLOBAL=true). If your notification targets are on internal networks, set this to false or add them to ALERTS_WEBHOOK_ALLOW_LIST.
Database migrations run automatically on container start — no manual action required.

Key Bugsink Changes per Version

Bugsink Version	Key Changes
2.1.2	Storage capacity management (file count + byte caps)
2.1.1	Security fix for upload checksums, sourcemap null handling
2.1.0	SSRF protection (`BaseWebhookBackend`, `webhook_security`), object storage, `vacuum` command, `MAX_EVENT_AGE_DAYS`, proxy header settings
2.0.12	Last version without SSRF protection module

Documentation

Quick Start Guide
Configuration Reference
SDK Configuration
Client SDK Examples - Integration examples for 10 languages
Client-Kit - Automated SDK integration tool
Sentry SDK Integration
Complete SDK Reference
Notification Backends - Jira, GitHub, Teams, PagerDuty, Webhook

License

See LICENSE for details.

Navigation Menu

Repository navigation

About

Repository files navigation

Error Observability

Features

Quick Start

1. Generate Configuration

2. Configure Environment

3. Deploy

4. Access

Architecture

Compose Files

SDK Integration

Python Example

JavaScript Example

More Languages

Automated Integration (Client-Kit)

Configuration

Environment Variables

User Registration

Rate Limits (per project)

Operations

View Logs

Backup Database

Restore Database

Update

Directory Structure

Bugsink Compatibility

Upgrade Guide: 2.0.x → 2.1.x

Key Bugsink Changes per Version

Documentation

License

About

Releases

Packages

Used by

Contributors

Languages

Name		Name	Last commit message	Last commit date
.github		.github
client-kit		client-kit
docs		docs
examples		examples
scripts		scripts
src		src
tools		tools
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
docker-compose.development.yml		docker-compose.development.yml
docker-compose.traefik.yml		docker-compose.traefik.yml
docker-compose.yml		docker-compose.yml

Latest commit

History

Folders and files

Repository files navigation

Error Observability

Features

Quick Start

1. Generate Configuration

2. Configure Environment

3. Deploy

4. Access

Architecture

Compose Files

SDK Integration

Python Example

JavaScript Example

More Languages

Automated Integration (Client-Kit)

Configuration

Environment Variables

User Registration

Rate Limits (per project)

Operations

View Logs

Backup Database

Restore Database

Update

Directory Structure

Bugsink Compatibility

Upgrade Guide: 2.0.x → 2.1.x

Key Bugsink Changes per Version

Documentation

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages