Telebugs Installation Expectations | Self-Hosted Setup Guide

Q: What should I back up?

Run telebugs data backup. Its verified archive contains all Telebugs SQLite databases, attachments, source maps, configuration, keys, secrets, and immutable image identity. Store it securely off the server and test telebugs data restore on an isolated host that cannot reach production notification destinations until they have been replaced with safe test endpoints.

A realistic checklist before you run your own error tracker

Telebugs is intentionally small, but self-hosting still means owning a few operational decisions. This page sets expectations for install, networking, updates, backups, storage, and evaluation. For a security review path, use the security review checklist. For a go-live review, use the installation readiness checklist.

Short version

The common Telebugs install path is Docker-based on a server you control. You choose the domain, TLS setup, SMTP or notification channels, retention policy, backup destination, and update cadence. Telebugs keeps the app side focused; your infrastructure choices still matter. When those choices are mostly known, use the installation readiness checklist to confirm owners, evidence, staging validation, and rollback.

What you need before installing

A Linux server, VM, VPS, private-cloud instance, or internal host that can run Docker.
For the standard install, a domain pointing directly to the server, without CDN or DNS proxying.
Inbound TCP ports 80 and 443 so Telebugs can terminate TLS and renew its certificate automatically.
Outbound network access for initial downloads and any enabled update checks or external notifications; legacy receipt migration also needs one-time access.
A backup plan for the database, uploaded artifacts, configuration, and restore process.
An owner for updates, retention settings, access review, and incident behavior during error storms.

Environment options

Environment	Good fit	Watch-outs
Small VPS	Bootstrapped teams, agencies, internal tools, and modest production volume.	Set retention, backups, disk monitoring, and ingest protection early.
Private cloud	Teams with existing infrastructure, logging, backups, and access control.	Coordinate DNS, TLS, firewall rules, and outbound notification destinations.
Internal network	On-prem, regulated, customer-controlled, or isolated environments.	Plan manual updates, internal certificates, and how apps reach the ingestion endpoint.
Kubernetes	Teams already standardized on Kubernetes operations.	Keep persistence, backups, ingress, and upgrades boring; do not add platform complexity if you do not need it.

Networking and TLS

Your application SDKs need to reach the Telebugs DSN. Your team needs to reach the web UI. Those may be public, VPN-only, private network, or customer-environment routes depending on your requirements.

The standard single-server installation expects direct DNS, inbound ports 80 and 443, and no CDN or DNS proxy; Telebugs terminates TLS and renews its certificate. Custom TLS termination is available for teams that deliberately operate a reverse proxy or internal certificate path. For browser-based apps, make sure the DSN endpoint is reachable and trusted from the browser environment where errors happen.

Email, notifications, and integrations

Decide which notification channels are allowed before production: email, PWA push, Teams, Discord, webhook endpoints, or custom integrations. If the instance is isolated, avoid depending on external notification services unless your firewall rules explicitly allow them.

See notifications and rules for the product workflow and security and trust for the access-boundary view.

Updates, backups, and storage

Updates within 1.x are included. If the server has internet access, Telebugs can check for updates. If not, disable automatic update checks and update manually according to your internal process.

Storage grows with accepted errors, retention periods, source maps, artifacts, and background work. Use retention policies, artifact cleanup, and ingest protection before a noisy deploy turns into a disk problem. The Telebugs CLI can stop a running instance and create one verified archive containing all three SQLite databases, attachments, source maps, configuration, keys, secrets, and the exact application image identity. It remains stopped during validation, archiving, and verification, so schedule a maintenance window for a large data set. Store that sensitive archive off-server and prove it with a restore drill whose outbound network cannot reach production notification destinations until they have been replaced with safe test endpoints. See the backup and restore runbook.

A fresh replacement server gets only the recovery CLI with bash -c "$(curl -fsSL https://auth.telebugs.com/restore)". Do not run normal telebugs setup there. Restore uses the exact licensed domain and recovery identity in the archive and never offers a domain override. On Linux, restore installs Docker when it is missing. On macOS, install and start Docker before running restore. After local readiness succeeds, you still own direct DNS cutover, unproxied ports 80/443, public TLS verification, and rollback to the old IP. A ready container does not prove the public route or certificate.

Updates do not silently create backups, and image rollback does not reverse database migrations. Use an explicit pre-update backup when your change window needs a data restore point. For monitoring, use the fixed /up and /ready checks with the system you already operate; Telebugs does not add a monitoring platform to the app.

Evaluation checklist

Can a staging app send a test error to Telebugs?
Can the team log in through the intended network route?
Is TLS valid for SDKs, browsers, and internal tools?
Do notifications reach the right channel?
Is sensitive data scrubbed before storage?
Are retention and artifact cleanup configured?
Does telebugs data verify pass, is the archive off-server, and has anyone completed a restore drill?
Does telebugs status report both liveness and readiness?
Is there a named owner for updates and access review?
Does the rollback plan preserve the old DSN if you are migrating from Sentry?
Has the team completed the installation readiness checklist before production rollout?
Has the team reviewed security ownership, access, integrations, and application data?

When to use a private demo

Use a private demo when the team needs to evaluate workflows before touching infrastructure: project creation, user access, notifications, error context, MCP access, and source map behavior. Use your own installation when the main question is network fit: internal DNS, TLS, firewall rules, backups, and update process.

Frequently asked questions

Do I need Kubernetes?

No. Use Kubernetes only if your team already operates it comfortably. The common path is Docker on a server or VM.

Can I install Telebugs on an internal network?

Yes. Make sure your apps can reach the DSN endpoint and your team can reach the UI. Disable automatic update checks if outbound internet is not allowed.

What should I back up?

Run telebugs data backup. Its verified archive contains all Telebugs SQLite databases, attachments, source maps, configuration, keys, secrets, and immutable image identity. Store it securely off the server and test telebugs data restore on an isolated host that cannot reach production notification destinations until they have been replaced with safe test endpoints.

How should I evaluate before buying?

Use the live demo for a quick tour, request a private demo for team workflow testing, and review this page with whoever owns infrastructure.