Skip to main content

Overview

GlitchTip is open-source, Sentry-API-compatible error tracking — applications report crashes and exceptions with standard Sentry SDKs pointed at a GlitchTip DSN, and GlitchTip groups them into issues with alerting. It is fully MIT-licensed with nothing feature-gated; there is no paid tier. This template deploys GlitchTip backed by a highly available PostgreSQL cluster and a Redis/Sentinel queue by default. The web UI and SDK event-ingest endpoint are served on one public HTTPS endpoint, and self-signup is closed by default. The Django signing key and the initial superuser login are not template values. They come from a dictionary secret you create before installing, so they never pass through Helm and never land in the release.
Template version 1.1.0 is a breaking change. django.secretKey, admin.email and admin.password moved into a prerequisite secret, and resources.cpu / resources.memory / worker.resources.cpu / worker.resources.memory were renamed. An install or upgrade that still sets any of them fails at render. If you are running 1.0.x, read Upgrading From Earlier Versions first.

Architecture

  • GlitchTip web — A stateless standard workload (default 1 replica, replicas knob for more) serving the UI, API, and SDK event ingest on port 8000.
  • GlitchTip worker — A single-replica standard workload running the background task worker and scheduler; it also runs database migrations and the superuser bootstrap at boot. It is a fixed singleton and is not scaled.
  • PostgreSQL (HA, default) — The postgres-highly-available template as a subchart: 3× Patroni PostgreSQL, 3× etcd, and a HAProxy leader-routing endpoint GlitchTip connects through. Holds all issue and event data.
  • PostgreSQL (dev/lightweight, optional) — The single-instance postgres template instead, for lighter non-HA deployments.
  • Redis + Sentinel (default, optional) — The redis template in Sentinel mode: the task queue, cache, and sessions. Disable it to run those on PostgreSQL instead (a lighter dev shape).

What Gets Created

  • Standard GlitchTip Web Workload — (RELEASE_NAME-glitchtip): the stateless web tier serving the UI, API, and SDK event ingest on port 8000 (replicas controls its scale).
  • Standard GlitchTip Worker Workload — (RELEASE_NAME-glitchtip-worker): a single-replica worker plus scheduler that runs migrations and the admin bootstrap at boot.
  • Database Workloads — HA mode: a stateful Patroni PostgreSQL workload, a stateful etcd workload, and a standard HAProxy leader-routing workload. Single mode: one stateful PostgreSQL workload.
  • Redis Workloads (default) — A master-replica Redis deployment with Sentinel for failover. Omitted when redis.enabled is false.
  • Volume Sets — The database subchart’s persistent volumes (10 GiB per replica by default), plus Redis persistence when enabled. The GlitchTip web and worker tiers have no volumes of their own.
  • Secrets — Two start scripts, plus the database and Redis credentials from the subcharts. The template creates no credential secret of its own: the signing key and admin login come from the secret you create.
  • Identity & Policy — A shared identity for the web and worker workloads and a least-privilege policy granting it reveal on exactly the secrets it uses, including your auth secret by name and the optional email secret when configured.
This template does not create a GVC. You must deploy it into an existing GVC.

Upgrading From Earlier Versions

Template version 1.0.x carried the Django signing key and the superuser login as plain Helm values, with published defaults for both. Each removed or renamed key is rejected at render with a message naming its replacement, so a failing upgrade leaves the running release untouched. There are no compatibility fallbacks.
Put your existing secretKey into the secret rather than generating a new one. It signs live sessions and tokens: a new value logs every user out and invalidates password-reset links already in flight. Nothing is corrupted, but everyone has to sign in again.If your install is still carrying the published 1.0.x default, its sessions and tokens are signed with a value printed in a public repository. Rotating it is the fix and the cost is exactly that one forced sign-out, so plan the upgrade for a quiet window rather than skipping it. Change the admin password in the UI at the same time.
The resource keys were renamed because both blocks expose a reservation as well as a limit, and a bare cpu sitting next to minCpu does not say which one it is. maxCpu and maxMemory map onto the platform’s cpu and memory fields.

Prerequisites

One secret must exist before you install. Its values never pass through Helm, so they never land in the release. Secrets are org-level, so no GVC flag is involved.
1

Create the auth secret

A dictionary secret holding exactly three keys:
Set auth.secretName to the name you used. Nothing else is required for a default install.
2

Read the secret back later

The -o yaml is required — plain cpln secret reveal prints only a summary table, not the values:
3

Optional: create the email secret

For member invites, alert notifications, and password-reset mail, create an opaque secret with encoding plain whose payload is a full email URL — for example smtp://user:password@smtp.example.com:587. Set email.secretName to its name before installing. Leave it empty to run without outbound email.
4

Optional: set up backup storage

Only if you plan to enable database backups — see Backing Up.
Create the auth secret before installing. A name pointing at a secret that does not exist installs “successfully” and then wedges both workloads: every resource reports created, neither becomes ready, and cpln logs returns zero lines because no container ever starts. The only diagnostic is status.versions[].message:
It names the missing secret: The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed. The command is get-deployments — plain cpln workload get has no versions key at all. Creating the secret recovers the workloads on their own: poll for 5.5 to 10.5 minutes rather than time-boxing it. cpln workload force-redeployment RELEASE_NAME-glitchtip --gvc GVC_NAME cuts that to roughly 90 seconds; the worker needs the same treatment.

Installation

To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Choosing a Database Mode

Exactly one of the two database modes must be enabled — the chart enforces this at render and fails the install with a clear message otherwise.
The HA stack takes about six and a half minutes to converge, and it looks broken while it does. The worker crash-loops throughout with django.db.utils.OperationalError: pool error: ... Connection reset by peer while Patroni elects a leader and the HAProxy endpoint waits for Patroni to answer. This is expected and self-correcting — do not treat it as a failed install, and do not start changing values in the middle of it. If it has not settled after roughly ten minutes, check the worker logs first, not the web logs.

Choosing a Queue Mode

By default the redis template is deployed and GlitchTip runs its task queue, cache, and sessions through Redis Sentinel. Set redis.enabled: false to run those on PostgreSQL instead — a lighter shape with no Redis workloads, at lower throughput. Both modes are supported upstream.

Configuration

The default values.yaml for this template:

GlitchTip

  • image — The GlitchTip container image, used by both the web and worker workloads.
  • replicas — Web-tier replica count. The web tier is stateless (all state is in PostgreSQL and Redis), so scaling to 2 or more gives high availability. The default 1 is the proven single-replica shape.
  • resources — Reservation and limit for the web container (minCpu / maxCpu / minMemory / maxMemory).
  • worker.resources — The same four keys for the worker container.
  • worker.concurrency — Number of async tasks the worker processes in parallel (VTASKS_CONCURRENCY).
  • auth.secretName — Name of the prerequisite dictionary secret holding secretKey, adminEmail and adminPassword. It must exist before you install.
  • registration.enabled — Open self-signup on the endpoint. Default false (closed) — admin-created users and invites still work either way. See Onboarding Users.

Email

  • email.secretName — Name of your pre-created opaque secret whose payload is an EMAIL_URL (see Prerequisites). Empty (default) turns outbound email off. Member invites, alert notifications, and password-reset mail all require it.
  • email.fromAddress — The From address on outbound mail; applied only when email.secretName is set.

Access

  • publicAccess.enabled — Serve the UI and SDK event ingest (the DSN endpoint) on the canonical *.cpln.app HTTPS endpoint.
  • domain — Full URL (for example https://errors.example.com) embedded in DSNs and email links. Empty (default) uses the canonical endpoint, derived automatically at boot.
  • internalAccess.type — Internal firewall scope of the web workload:
Public access is on by default, deliberately. Browser SDKs and applications outside the GVC have to reach the ingest endpoint or they cannot report anything, and both the legacy store API and the modern envelope API are proven to accept events from outside the GVC against this template. Self-signup is closed by default, and after 1.1.0 there is no published default credential to protect against.Set publicAccess.enabled: false for in-GVC reporters only, and reach the UI with cpln port-forward RELEASE_NAME-glitchtip 8000:8000 --gvc GVC_NAME. A firewall change takes roughly 30 seconds to 5 minutes to propagate, so re-test rather than trusting the first response.

Task Queue and Cache

  • redis.enabled — Deploy the Redis subchart in Sentinel mode for the task queue, cache, and sessions (default). Set to false to carry those on PostgreSQL instead — see Choosing a Queue Mode.
  • redis.redis.replicas — Redis master-replica count.
  • redis.redis.auth.password.value — The Redis password. Required when Redis is enabled (the chart enforces it). Change it before installing — any characters are fine, the boot script percent-encodes it into the connection URL.
  • redis.sentinel.replicas — Number of Sentinel instances. Sentinel authentication must stay disabled — GlitchTip cannot send a Sentinel password; the same-GVC firewall is the boundary there.
  • redis.redis.persistence.enabled / redis.sentinel.persistence.enabled — Persistent storage for Redis and Sentinel.
  • redis.redis.firewall.internal_inboundAllowType / redis.sentinel.firewall.internal_inboundAllowType — Internal firewall scope of the Redis and Sentinel workloads.

Database

Enable exactly one of postgresHA (production, default) or postgres (dev/lightweight) — see Choosing a Database Mode. GlitchTip is wired to the active database automatically: the HAProxy leader endpoint in HA mode, or the single instance directly in dev mode. Both database passwords are bundled plumbing — the database serves GlitchTip only and is unreachable from outside the GVC — but they are used as-is, so change postgres.credentials.password or postgres.credentials.password before installing. The shipped change-me-glitchtip-db is a published placeholder. If you run more than one release of this template in the same organization, give each its own postgres.config.credentialsSecretName. Secret names are organization-wide, so a second release left on the default name is refused at install and creates nothing — the first release is unaffected.
Template version 1.0.0 did not compact the etcd cluster inside the bundled highly available database, so etcd’s backend grows with time alone and goes read-only once it reaches its 2 GiB quota — after roughly 110 days — taking PostgreSQL failover with it. Only installs running the HA database are affected (postgresHA.enabled, the default here); see etcd History Compaction for the mechanism and the symptoms. Version 1.0.1 and later turn compaction on: that stops further growth but cannot shrink a backend that has already grown, and a cluster that has already raised a NOSPACE alarm needs operator recovery rather than an upgrade.

Onboarding Users

Registration is closed by default (registration.enabled: false) — an override of GlitchTip’s upstream open-signup default. With registration closed, invites only work for accounts that already exist: create teammate accounts first through the Django admin at https://<canonical>.cpln.app/admin/ (log in with the superuser account), then invite them to your organization. Invite, alert, and password-reset emails require email.secretName to be set. To allow open self-signup instead, set registration.enabled: true.

Connecting

Reporting Errors

Point any Sentry SDK at your project’s DSN. The DSN is issued in the UI under project → Settings → DSN and embeds the public endpoint, so no extra configuration is needed. Existing @sentry/* SDK setups keep working — only the DSN changes. SDKs running inside the same GVC can send events to the internal endpoint per internalAccess.

Backing Up

Database backups are optional and disabled by default. They cover the PostgreSQL database — the issues, events, and users that make up your GlitchTip instance. Enable them with postgresHA.backup.enabled or postgres.backup.enabled (matching your database mode), and complete the storage setup for your provider before installing. The values below are shown under backup.* — set them within the enabled database block.
1

Create a bucket

Create an S3 bucket. Set backup.aws.bucket and backup.aws.region to match.
2

Set up a Cloud Account

If you do not have one, create a Cloud Account for your AWS account. Set backup.aws.cloudAccountName to its name.
3

Create a bucket-scoped IAM policy

Create an AWS IAM policy with the JSON below (replace YOUR_BUCKET), then set backup.aws.policyName to the policy’s name:
In HA mode, backup.mode selects logical (scheduled pg_dump via a cron workload) or wal-g (continuous WAL archiving). The single-instance mode takes scheduled logical dumps.

Important Notes

  • The auth secret must exist before you install. Without it both workloads wedge with no log output at all; see Prerequisites for the one diagnostic that names it.
  • The HA database takes about six and a half minutes to converge on a fresh install, with the worker crash-looping on Connection reset by peer throughout. It is self-correcting and indistinguishable from a failed install — wait it out.
  • Rotating secretKey logs every user out and invalidates password-reset links in flight. Nothing is corrupted, but do it deliberately.
  • Change the database password and the Redis password before installing — both are bundled plumbing used as-is.
  • Do not scale the worker — it is a fixed singleton (scheduler plus boot-time migrations). Web replicas is the scaling knob; a worker outage pauses processing but ingest keeps accepting events and catches up when the worker returns.
  • First boot: the web tier stays not-ready until the worker finishes migrations. If it seems stuck, check the worker logs first, not the web logs.
  • With registration closed (default), invites only work for accounts that already exist — create teammate accounts first at /admin/, then invite them. Invite and alert emails require email.secretName. See Onboarding Users.
  • Editing the auth secret after first boot does not change the existing superuser account — it is seeded once. Change the password in the UI.
  • The first Helm upgrade after an install re-applies resources even with identical values, which can briefly bounce the bundled datastores. Later upgrades are clean.
  • DSNs embed the endpoint URL — if you add a custom domain later, set domain, run a Helm upgrade, and update the DSNs in your apps.
  • Source-map / artifact uploads are ephemeral (local disk) — lost on restart and not shared across web replicas. Error ingest itself is unaffected; events go to PostgreSQL.
  • Uninstall deletes the database volume sets — all issues, events, and users. Enable backups if the data matters.

External References

GlitchTip Documentation

Official GlitchTip documentation

Installation Reference

Installation and configuration reference

Sentry SDKs

Client setup for the Sentry SDKs GlitchTip is compatible with

GlitchTip 6 Release Notes

What changed in the GlitchTip 6 release line

GlitchTip Backend Source

Upstream GlitchTip backend source

GlitchTip Template

View the source files, default values, and chart definition