SigNoz Deployment & Usage Guide

1. Prerequisites

Before deploying SigNoz, ensure you have the following:

System Requirements:

Docker & Docker Compose: Required for containerized deployment
Kubernetes cluster (for Kubernetes deployment) with:
- kubectl configured
- Helm 3.8+ (for Helm chart installation)
Node.js 18+ (for development/build purposes)
Git for cloning the repository
Minimum 4GB RAM (8GB+ recommended for production)
20GB+ free disk space

Accounts & Services:

Docker Hub account (optional, for custom images)
Kubernetes cluster access (for cloud deployments)
OpenTelemetry collector access for your applications

2. Installation

Quick Start with Docker Compose (Recommended for local testing)

# Clone the repository
git clone https://github.com/SigNoz/signoz.git
cd signoz

# Deploy using Docker Compose
docker-compose -f deploy/docker/clickhouse-setup/docker-compose.yaml up -d

Kubernetes Deployment with Helm

# Add SigNoz Helm repository
helm repo add signoz https://charts.signoz.io
helm repo update

# Create namespace
kubectl create namespace platform

# Install SigNoz
helm install my-signoz signoz/signoz -n platform

Development Installation

# Clone the repository
git clone https://github.com/SigNoz/signoz.git
cd signoz

# Install dependencies
npm install
# or
yarn install

# Set up environment
cp .env.example .env

3. Configuration

Environment Variables

Create a .env file in the root directory with the following variables:

# Database Configuration
CLICKHOUSE_HOST=localhost
CLICKHOUSE_PORT=9000
CLICKHOUSE_DB=signoz
CLICKHOUSE_USER=default
CLICKHOUSE_PASSWORD=

# Application Configuration
NODE_ENV=production
API_PORT=8080
FRONTEND_PORT=3301
QUERY_SERVICE_PORT=8080
ALERTMANAGER_PORT=9093

# OpenTelemetry Collector
OTEL_COLLECTOR_PORT=4317
OTEL_COLLECTOR_HTTP_PORT=4318

# Authentication
JWT_SECRET=your-secret-key-here
ENCRYPTION_KEY=your-encryption-key-here

Kubernetes Configuration

For Kubernetes deployments, configure values in deploy/kubernetes/platform/values.yaml:

global:
  storageClass: "standard"
  clickhouse:
    persistence:
      size: "100Gi"
  
frontend:
  replicaCount: 2
  resources:
    requests:
      memory: "512Mi"
      cpu: "250m"
  
queryService:
  replicaCount: 3
  resources:
    requests:
      memory: "1Gi"
      cpu: "500m"

OpenTelemetry Configuration

Configure your applications to send data to SigNoz:

# OpenTelemetry Collector Configuration (otel-collector-config.yaml)
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  clickhouse:
    endpoint: tcp://clickhouse:9000
    database: signoz
    username: default
    password: ""
    timeout: 5s

service:
  pipelines:
    traces:
      receivers: [otlp]
      exporters: [clickhouse]
    metrics:
      receivers: [otlp]
      exporters: [clickhouse]
    logs:
      receivers: [otlp]
      exporters: [clickhouse]

4. Build & Run

Development Mode

# Install dependencies
yarn install

# Start frontend development server
cd frontend
yarn start
# Server runs on http://localhost:3301

# Start backend services
cd ../backend
yarn dev
# API runs on http://localhost:8080

Production Build

# Build frontend
cd frontend
yarn build

# Build Docker images
docker build -t signoz/frontend:latest -f deploy/docker/frontend/Dockerfile .
docker build -t signoz/query-service:latest -f deploy/docker/query-service/Dockerfile .

# Run with Docker Compose
docker-compose -f deploy/docker/clickhouse-setup/docker-compose.yaml up -d

Running Tests

# Run unit tests
yarn test

# Run integration tests
yarn test:integration

# Run with coverage
yarn test:coverage

5. Deployment

Cloud Platforms

AWS EKS:

# Deploy using EKS
eksctl create cluster --name signoz-cluster --nodes 3 --node-type t3.medium
helm install signoz signoz/signoz -n platform

Google Cloud GKE:

# Create GKE cluster
gcloud container clusters create signoz-cluster --num-nodes=3 --machine-type=e2-medium
helm install signoz signoz/signoz -n platform

Azure AKS:

# Create AKS cluster
az aks create --resource-group signoz-rg --name signoz-cluster --node-count 3 --node-vm-size Standard_D2s_v3
helm install signoz signoz/signoz -n platform

Production Considerations

High Availability:
- Deploy at least 3 replicas of each service
- Use persistent volumes for ClickHouse data
- Configure pod anti-affinity rules
Monitoring SigNoz itself:
- Deploy SigNoz in a separate cluster or namespace
- Configure external monitoring for the monitoring platform

Backup Strategy:

# Backup ClickHouse data
clickhouse-client --query="BACKUP DATABASE signoz TO Disk('backup', 'signoz_backup')"

# Schedule regular backups
kubectl create cronjob signoz-backup --image=clickhouse/clickhouse-server \
  --schedule="0 2 * * *" -- \
  clickhouse-client --query="BACKUP DATABASE signoz TO S3('https://your-bucket.s3.amazonaws.com/backups')"

Scaling:
- Horizontal scaling for query-service based on QPS
- Vertical scaling for ClickHouse based on data volume
- Consider separating hot and cold data storage

6. Troubleshooting

Common Issues and Solutions

Issue: ClickHouse connection failures

# Check ClickHouse status
docker ps | grep clickhouse
docker logs signoz-clickhouse

# Test connection
clickhouse-client --host localhost --port 9000 --user default --query="SHOW DATABASES"

Issue: Frontend not loading

# Check frontend logs
docker logs signoz-frontend

# Verify API connectivity
curl http://localhost:8080/api/v1/status

Issue: No data appearing in UI

# Check OpenTelemetry collector
docker logs signoz-otel-collector

# Verify data is reaching ClickHouse
clickhouse-client --query="SELECT count() FROM signoz.traces"

Issue: High memory usage

# Adjust ClickHouse memory limits in docker-compose.yaml
clickhouse:
  environment:
    - MAX_MEMORY_USAGE=40000000000  # 40GB
    - MAX_QUERY_MEMORY=20000000000   # 20GB

Issue: Kubernetes pods crashing

# Check pod status
kubectl get pods -n platform

# View pod logs
kubectl logs -n platform deployment/signoz-query-service

# Check resource limits
kubectl describe pod -n platform signoz-query-service-xxx

# Increase resources if needed
helm upgrade signoz signoz/signoz -n platform \
  --set queryService.resources.requests.memory="2Gi" \
  --set queryService.resources.limits.memory="4Gi"

Issue: Slow query performance

-- Optimize ClickHouse tables
OPTIMIZE TABLE signoz.traces FINAL;

-- Check table sizes
SELECT 
    table,
    formatReadableSize(sum(bytes)) AS size,
    sum(rows) AS rows
FROM system.parts
WHERE database = 'signoz'
GROUP BY table
ORDER BY sum(bytes) DESC;

Getting Help

Check Logs:

# Docker Compose
docker-compose logs -f

# Kubernetes
kubectl logs -n platform -l app.kubernetes.io/name=signoz --tail=100

Community Support:
- Join SigNoz Slack Community
- Check GitHub Issues
- Review Documentation

Debug Mode:

# Enable debug logging
export LOG_LEVEL=debug
docker-compose up

Health Checks:

# API health
curl http://localhost:8080/health

# Frontend health
curl http://localhost:3301/health

# ClickHouse health
curl http://localhost:8123/ping

How to Deploy & Use signoz