# Deploy Uptrace with Easypanel

URL: /templates/uptrace

Uptrace is an open-source APM platform for traces, metrics, and logs using OpenTelemetry, with ClickHouse storage and PostgreSQL metadata. This template follows the official example/docker compose stack (Uptrace, ClickHouse, Postgres, Redis, OTel Collector, Vector, Grafana, Prometheus, Alertmanager, Mailpit). The Vector image uses timberio/vector:0.28.X-alpine to match that upstream example (legacy Docker Hub namespace); migrate to distroless/vector only when you intentionally diverge from upstream.

## Installation notes

Login; Use the admin name/email/password from the template form (password is random if left blank). The project DSN token is generated once per deploy and embedded in `/etc/uptrace/config.yml`, OTel Collector, Grafana datasource, Prometheus remote_write, and Vector—keep file mounts stable or regenerate configs together. Ingestion; Published host ports match the upstream example—14317→4317 (Uptrace gRPC, referenced in `site.ingest_url`), 4317/4318 (OTLP on the collector). On shared hosts these can conflict; change published ports in Easypanel and update `ingest_url` / client endpoints accordingly. Grafana & Mailpit use separate app domains on ports 3000 and 8025; assign subdomains or paths in Easypanel as needed. TLS; Upstream compose mounts TLS certs; this template omits them for HTTPS termination at the proxy—see Uptrace docs if you need in-container TLS.

## Benefits

### All-in-One Observability

Single UI for distributed traces, metrics, and logs with 50+ pre-built dashboards that auto-create when metrics start flowing.

### Cost-Effective at Scale

Process billions of spans on a single server using ClickHouse's efficient columnar storage with ZSTD compression (1KB span compresses to ~40 bytes).

### OpenTelemetry Native

Built on the OpenTelemetry standard with support for OTLP, Prometheus, Vector, FluentBit, and CloudWatch ingestion.

### Self-Hosted & Open Source

Full control over your observability data with no vendor lock-in. Deploy on your own infrastructure with complete data sovereignty.

## Features

### Distributed Tracing

Visualize request flows across services with service graphs, faceted filters, and SQL-like query language for span analysis.

### Metrics & Dashboards

PromQL-like language for metrics aggregation with 50+ auto-created dashboards and chart annotations.

### Alerting & Notifications

Monitor spans, logs, and metrics with alerts via Email, Slack, Telegram, WebHook, and AlertManager integration.

### Grafana Compatible

Use Uptrace as a Tempo and Prometheus datasource in Grafana for seamless integration with existing dashboards.

### Multi-Tenant Support

Manage multiple organizations and projects with SSO support via OpenID Connect (Keycloak, Google, Cloudflare).

### High Performance

More than 10K spans/second on a single core with excellent on-disk compression for cost-effective long-term retention.

## Configuration

- `appServiceName` (App Service Name, required): uptrace

- `appServiceImage` (Uptrace Image, required): uptrace/uptrace:2.1.0-beta.5 — Pinned to the tag used in github.com/uptrace/uptrace example/docker docker-compose.yml; bump only with a tested exact tag.

- `adminName` (Admin Name): Admin

- `adminEmail` (Admin Email): admin@uptrace.local

- `adminPassword` (Admin Password): Set during installation — Generated randomly if not provided.

- `grafanaAdminPassword` (Grafana admin password): Set during installation — Grafana login user is admin. Leave empty for a random password (written to grafana.ini), or set explicitly.

- `orgName` (Organization Name): Org1

- `projectName` (Project Name): Project1

## Services

- uptrace: app (uptrace/uptrace:2.1.0-beta.5)

- uptrace-clickhouse: app (clickhouse/clickhouse-server:25.8.15.35)

- uptrace-db: postgres

- uptrace-redis: redis

- uptrace-otelcol: app (otel/opentelemetry-collector-contrib:0.123.0)

- uptrace-alertmanager: app (prom/alertmanager:v0.24.0)

- uptrace-vector: app (timberio/vector:0.28.1-alpine)

- uptrace-grafana: app (grafana/grafana:12.0.0)

- uptrace-prometheus: app (prom/prometheus:v2.36.2)

- uptrace-mailpit: app (axllent/mailpit:v1.29.4)

## Resources

- [Website](https://uptrace.dev)

- [GitHub](https://github.com/uptrace/uptrace)

- [Documentation](https://uptrace.dev/get)

- [Template source](https://github.com/easypanel-io/templates/tree/main/templates/uptrace)