Deploying Uptrace with Docker

This guide provides step-by-step instructions for deploying Uptrace, an open-source APM and observability platform, using Docker and Docker Compose. This method is ideal for quick setup, local development, testing environments, and small-scale production deployments. Uptrace supports distributed tracing, metrics, and log management to help you monitor your applications effectively.

When to Use Docker Deployment

Docker deployment is best suited for:

• Quick evaluation: Test Uptrace features before committing to production
• Local development: Run Uptrace locally for application development
• Small teams: Simple deployment for teams getting started with observability
• Testing environments: Isolated environments for testing configurations

For production deployments at scale, consider the Kubernetes deployment or Ansible deployment options.

Prerequisites

Before proceeding with this guide, ensure you have:

1. Docker installed on your system - Follow the official installation guide
2. Docker Compose - Typically included with Docker Desktop, or install separately for Linux
3. Git - For cloning the repository
4. Minimum system requirements:
   • 2+ CPU cores
   • 4GB+ RAM
   • 10GB+ disk space for initial setup

Verify Docker Installation

Check that Docker and Docker Compose are properly installed:

docker --version
docker compose version

Quick Start Installation

Step 1: Clone the Repository

Clone the Uptrace repository and navigate to the Docker example directory:

git clone https://github.com/uptrace/uptrace.git
cd uptrace/example/docker

Step 2: Pull Container Images

Download all required container images before starting the services:

docker compose pull

This command pulls the following images:

• Uptrace - The main application
• ClickHouse - Time-series database for observability data
• PostgreSQL - Relational database for metadata
• Redis - In-memory cache
• OpenTelemetry Collector - Telemetry data collection and processing
• Mailpit - Email testing tool
• Grafana, Prometheus, node_exporter, and Vector - Optional demo integrations that query or send data to Uptrace

Step 3: Start Services

Launch all services in detached mode (running in the background):

docker compose up -d

Docker Compose will:

1. Create a dedicated network for the services
2. Wait for ClickHouse, PostgreSQL, and Redis to become healthy
3. Start Uptrace, which runs database migrations and creates the default user and project
4. Start the OpenTelemetry Collector and the other demo services

If a container fails with port is already allocated, another program uses one of the ports listed in Services Architecture. Stop that program or change the host port in docker-compose.yml.

Step 4: Verify Installation

Check that all services are running correctly:

docker compose ps

All services should show a status of "Up" or "running".

View Uptrace application logs to confirm successful startup:

docker compose logs uptrace

Look for log messages indicating that Uptrace has successfully connected to ClickHouse and PostgreSQL, and is ready to accept connections. You can also check the readiness endpoint:

curl http://localhost:14318/health/ready

Accessing Uptrace

Web Interface

Once all services are running, access the Uptrace web interface:

• URL: http://localhost:14318
• Email: admin@uptrace.local
• Password: admin

First Login

After logging in with the default credentials:

1. Change the default password immediately for security
2. Explore the interface and familiarize yourself with the dashboard
3. Create a new project for your application

Understanding the Docker Setup

Services Architecture

The Docker Compose configuration includes the following services:

Uptrace Application

• Port: 14318 (HTTP), 14317 (gRPC)
• Purpose: Main application server providing the web UI, API, and OTLP ingestion
• Dependencies: ClickHouse, PostgreSQL, Redis

ClickHouse

• Port: 9000 (native), 8123 (HTTP)
• Purpose: Stores all observability data (spans, logs, metrics, events)
• Data retention: 14 days; see Configure Data Retention

PostgreSQL

• Port: 5432
• Purpose: Stores metadata (users, projects, monitors, alert configurations)
• Database: uptrace

Redis

• Port: Not exposed on the host
• Purpose: In-memory caching for improved query performance
• Persistence: Disabled by default (ephemeral cache)

OpenTelemetry Collector

• Port: 4317 (gRPC), 4318 (HTTP)
• Purpose: Collects telemetry data from applications and forwards to Uptrace
• Monitoring: Pre-configured to monitor host metrics and PostgreSQL

Mailpit

• Web UI Port: 8025
• SMTP Port: 1025
• Purpose: Captures emails sent by Uptrace, such as alert notifications

Demo Integrations

• Grafana (port 3000, admin / admin): comes with Uptrace Tempo and Prometheus data sources
• Prometheus: scrapes node_exporter and sends metrics to Uptrace with remote write
• node_exporter: exports host metrics for Prometheus
• Vector: generates demo logs and sends them to Uptrace

You can remove these services from docker-compose.yml if you don't need them.

Data Persistence

By default, the Docker setup uses named volumes for data persistence. Docker Compose prefixes the volume names with the project name, which is the directory name (docker):

• docker_ch_data - ClickHouse database files
• docker_pg_data3 - PostgreSQL database files
• docker_mailpit_data - Mailpit emails
• docker_prometheus_data - Prometheus data

Data persists across container restarts and recreations.

Monitoring and Testing

Self-Monitoring

Uptrace monitors itself using the uptrace-go OpenTelemetry distribution. After starting the services:

1. Wait approximately 30 seconds
2. Refresh the Uptrace web interface several times
3. Navigate to your project dashboard
4. You should see traces and metrics from Uptrace itself

This self-monitoring demonstrates that:

• OpenTelemetry instrumentation is working
• Data is flowing through the collector
• ClickHouse is storing data correctly
• The web interface can query and display data

Email Testing with Mailpit

Mailpit captures all emails sent by Uptrace, making it easy to test notifications and alerts without sending real emails.

Access the Mailpit web interface at http://localhost:8025.

Testing email notifications:

1. Configure an alert or monitor in Uptrace
2. Trigger the alert condition
3. Check Mailpit to see the notification email

Note: In production environments, configure a real SMTP server instead of Mailpit.

Configuration and Customization

Configuration File Location

The main Uptrace configuration file is located at:

uptrace/example/docker/uptrace.yml

Common Customizations

Change HTTP Port

To run Uptrace on a different port, edit the docker-compose.yml file:

services:
  uptrace:
    ports:
      - '8080:80' # Change 8080 to your preferred host port

Then restart the service:

docker compose up -d uptrace

Configure Data Retention

The Community edition keeps data for 14 days, and you cannot change it. With a Premium license, each project can have its own retention, which you set in the project settings or with Terraform. The retention section of uptrace.yml sets the limits of that retention:

retention:
  # A project that has no custom retention keeps data this long. It is also the
  # lowest custom retention.
  min: 336h # 14 days
  # The longest retention a project can have.
  max: 2160h # 90 days
  # The step of the retention picker in the project settings.
  unit: 24h # 1 day

Without a Premium license, Uptrace ignores this section.

Restart Uptrace after making changes:

docker compose restart uptrace

Adjust Resource Limits

Limit memory and CPU usage for containers by adding resource constraints to docker-compose.yml:

services:
  clickhouse:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          memory: 1G

When the uptrace container has a memory limit, Uptrace sets the soft memory limit of the Go runtime to service.memory_limit_ratio (default 0.9) × that limit, and caps the default buffer of each pipeline at a quarter of it.

For detailed configuration options, see the Configuration guide.

Instrumenting Your Applications

To send telemetry data from your applications to Uptrace:

Step 1: Get OpenTelemetry Endpoint

Your applications should send data to the OpenTelemetry Collector:

• gRPC endpoint: http://localhost:4317
• HTTP endpoint: http://localhost:4318

The collector adds the project DSN, so your application doesn't need it. To send data to Uptrace directly instead, use http://localhost:14317 (gRPC) or http://localhost:14318 (HTTP) and pass the DSN in the uptrace-dsn header:

export OTEL_EXPORTER_OTLP_HEADERS=uptrace-dsn=http://project1_secret@localhost:14318?grpc=14317

Step 2: Configure Your Application

Use the appropriate OpenTelemetry SDK for your programming language. Here are quick examples:

import (
    "go.opentelemetry.io/otel"
    "go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc"
)

exporter, err := otlptracegrpc.New(ctx,
    otlptracegrpc.WithEndpoint("localhost:4317"),
    otlptracegrpc.WithInsecure(),
)

from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

otlp_exporter = OTLPSpanExporter(
    endpoint="http://localhost:4317",
    insecure=True
)

const { OTLPTraceExporter } = require('@opentelemetry/exporter-trace-otlp-grpc');

const exporter = new OTLPTraceExporter({
  url: 'http://localhost:4317',
});

import io.opentelemetry.exporter.otlp.trace.OtlpGrpcSpanExporter;

OtlpGrpcSpanExporter spanExporter = OtlpGrpcSpanExporter.builder()
    .setEndpoint("http://localhost:4317")
    .build();

Step 3: View Your Data

After instrumenting your application:

1. Run your application
2. Generate some traffic or activity
3. Open the Uptrace web interface
4. Navigate to your project
5. View traces, metrics, and logs in real-time

For framework-specific guides, see the instrumentation guides.

Managing Services

View Service Status

Check the status of all services:

docker compose ps

View Logs

View logs for all services:

docker compose logs

View logs for a specific service:

docker compose logs uptrace
docker compose logs clickhouse

Follow logs in real-time:

docker compose logs -f uptrace

Restart Services

Restart all services:

docker compose restart

Restart a specific service:

docker compose restart uptrace

Stop Services

Stop all services without removing containers:

docker compose stop

Start Stopped Services

Start previously stopped services:

docker compose start

Upgrading Uptrace

Check the supported upgrade paths first.

To upgrade Uptrace:

1. Back up your databases. Create backups of both PostgreSQL and ClickHouse before proceeding. See Backup and Restore for details.
2. Update the example files. Pull the new docker-compose.yml, which also sets the ClickHouse and PostgreSQL versions the new release needs. Keep your changes to uptrace.yml:
   shell

   cd uptrace/example/docker
   cp uptrace.yml uptrace.yml.bak
   git stash && git pull && git stash pop
   

3. Set a secret. If service.secret in uptrace.yml is still FIXME, set it to the output of openssl rand -hex 32. The new release refuses to start with the placeholder.
4. Pull the new images:
   shell

   docker compose pull
   

5. Rewrite deprecated options with the new image. Print the fixes first, then apply them:
   shell

   docker compose run --rm uptrace config fix
   docker compose run --rm uptrace config fix --write
   

6. Recreate the containers:
   shell

   docker compose up -d
   

   
   The new container runs uptrace migrate up and uptrace db seed, and then starts the server. Docker stops the old container first, so Uptrace does not accept telemetry while the migrations run. The first upgrade from v2.0 or a v2.1 beta also takes over the migration records of that release.
7. Check the result:
   shell

   docker compose logs uptrace
   docker compose run --rm uptrace migrate status
   

If the container exits, docker compose logs uptrace shows the reason, for example a config option or a migration that failed. To recover from a failed migration or to roll back, see upgrading Uptrace.

Troubleshooting

Common Issues and Solutions

Services Won't Start

Problem: Containers fail to start or immediately exit

Solutions:

# Check detailed logs
docker compose logs

# Check for port conflicts
sudo lsof -i :14318
sudo lsof -i :4317

# Check available disk space
df -h

# Check Docker daemon status
sudo systemctl status docker

Cannot Connect to Uptrace

Problem: Web interface is not accessible at localhost:14318

Solutions:

1. Verify the container is running:
   shell

   docker compose ps uptrace
   

2. Check if the port is exposed correctly:
   shell

   docker compose port uptrace 80
   

3. Test with curl:
   shell

   curl -f http://localhost:14318/health/ready
   

4. Check firewall rules if accessing from another machine

Database Connection Errors

Problem: Uptrace logs show database connection failures

Solutions:

1. Verify database containers are healthy:
   shell

   docker compose ps clickhouse postgres
   

2. Check database logs:
   shell

   docker compose logs clickhouse
   docker compose logs postgres
   

3. Verify network connectivity between containers:
   shell

   docker compose exec uptrace ping clickhouse
   

Out of Memory Errors

Problem: ClickHouse or other services crash with OOM errors

Solutions:

1. Increase Docker memory limit in Docker Desktop settings
2. Add memory limits to docker-compose.yml
3. Reduce data retention period
4. Clean up old data

Data Not Appearing in UI

Problem: Applications are instrumented but data doesn't show in Uptrace

Solutions:

1. Verify OpenTelemetry Collector is running:
   shell

   docker compose logs otelcol
   

2. Check that your application is sending to the correct endpoint
3. Verify network connectivity from your application to the collector
4. Check for errors in application logs
5. Wait 30-60 seconds for data to be processed and indexed

Diagnostic Commands

# Check container health
docker compose ps

# View container resource usage
docker stats

# Inspect container details
docker inspect $(docker compose ps -q uptrace)

# Execute commands inside containers
docker compose exec uptrace sh
docker compose exec clickhouse clickhouse-client -u uptrace --password uptrace

# View Docker network configuration
docker network inspect docker_default

Backup and Restore

Backing Up Data

Backup Volumes

Stop the services first so the database files are consistent, then create backups of persistent volumes:

docker compose stop

# Backup ClickHouse data
docker run --rm -v docker_ch_data:/data -v $(pwd):/backup ubuntu tar czf /backup/clickhouse-backup.tar.gz /data

# Backup PostgreSQL data
docker run --rm -v docker_pg_data3:/data -v $(pwd):/backup ubuntu tar czf /backup/postgres-backup.tar.gz /data

docker compose start

Database Dumps

Create logical backups:

# PostgreSQL dump
docker compose exec -T postgres pg_dump -U uptrace uptrace > uptrace-pg-backup.sql

The ClickHouse image doesn't include a backup tool. To back up ClickHouse without stopping it, use the BACKUP statement or clickhouse-backup.

Restoring Data

Restore from volume backups:

# Stop services
docker compose down

# Restore ClickHouse
docker run --rm -v docker_ch_data:/data -v $(pwd):/backup ubuntu tar xzf /backup/clickhouse-backup.tar.gz -C /

# Restore PostgreSQL
docker run --rm -v docker_pg_data3:/data -v $(pwd):/backup ubuntu tar xzf /backup/postgres-backup.tar.gz -C /

# Start services
docker compose up -d

Cleanup

Stop and Remove Containers

Stop all services and remove containers:

docker compose down

Remove Volumes (Delete All Data)

To completely remove all data and start fresh:

docker compose down -v

This command removes:

• All containers
• All volumes (data will be lost)
• The network

Named volumes can also be removed individually:

docker volume rm docker_ch_data
docker volume rm docker_pg_data3

Remove Images

Remove downloaded images to free up disk space:

docker compose down --rmi all

Production Considerations

Docker Compose has no built-in high availability or horizontal scaling — it's the right tool for evaluation, local development, and small deployments, not for production HA. Before going further, work through the production checklist (security, HA, performance); for HA and horizontal scaling specifically, move to the Kubernetes deployment guide or Ansible deployment guide.

Next Steps

After successful deployment:

1. Instrument your applications with OpenTelemetry - See language-specific guides
2. Create custom dashboards for your services
3. Set up monitors and alerts for critical metrics
4. Explore distributed tracing features
5. Configure log aggregation from your applications
6. Review the configuration guide for advanced options - Configuration
7. Learn about Uptrace features - Features

Alternative Deployment Methods

Docker Compose is one of several deployment options:

• DEB/RPM packages - For traditional server deployments
• Ansible - For automated bare metal deployments
• Kubernetes - For container orchestration at scale

Choose the method that best fits your infrastructure and requirements.