compose

Docker Compose

Field	Value
Mode	docker
Flavor	compose
Platform	-

Overview

Deploys SigNoz using Docker Compose with all Foundry defaults. This is the simplest way to run SigNoz locally or on a single node.

Prerequisites

• Docker Engine 20.10+
• Docker Compose v2

Configuration

apiVersion: v1alpha1
metadata:
  name: signoz
spec:
  deployment:
    flavor: compose
    mode: docker

Telemetry keeper kinds

The telemetry keeper defaults to ClickHouse Keeper. To use ZooKeeper instead, set the kind and Foundry resolves the right image and configuration for it:

spec:
  telemetrykeeper:
    kind: zookeeper
    spec:
      cluster:
        replicas: 1

Deploy

foundryctl cast -f casting.yaml

Or step by step:

# Validate prerequisites
foundryctl gauge -f casting.yaml

# Generate compose files
foundryctl forge -f casting.yaml

# Start the stack
cd pours/deployment && docker compose up -d

Important

Upgrading an existing installation: re-running cast regenerates the config files, but Docker Compose does not restart containers when only mounted file contents change. Recreate the stack so the new configs take effect:

docker compose -f pours/deployment/compose.yaml up -d --force-recreate

Recreate all services in one command rather than restarting them individually. Restarting only the keeper leaves ClickHouse unable to reconnect until it is restarted as well. Telemetry data is stored in volumes and is not affected.

Generated output

pours/deployment/
  compose.yaml
  configs/
    ingester/
      ingester.yaml
      opamp.yaml
    telemetrykeeper/
      clickhousekeeper/
        keeper-0.yaml
    telemetrystore/
      clickhouse/
        config.yaml
        functions.yaml

After deployment

# Check running containers
docker ps

# View logs for a specific service
docker compose -f pours/deployment/compose.yaml logs -f signoz

# Stop the stack
cd pours/deployment && docker compose down

Note

• foundryctl cast detects whether docker compose (v2 plugin) or docker-compose (legacy standalone) is available and uses whichever it finds, preferring the v2 plugin.

MCP server (optional)

Foundry can deploy the SigNoz MCP server alongside the stack so AI clients can query your telemetry. It is disabled by default; enable it in the casting:

spec:
  deployment:
    mode: docker
    flavor: compose
  mcp:
    spec:
      enabled: true

foundryctl cast -f casting.yaml

This adds a signoz-mcp service on port 8000:

docker ps | grep signoz-mcp
curl -fsS localhost:8000/livez && echo " OK"   # -> 200

To connect an AI client (mint an API key, configure Claude Code or Claude Desktop), see MCP server.

Customization

Override component images, replicas, or environment variables in the casting spec. For platform-level changes to the generated compose.yaml (memory limits, networks, volumes), use patches.

Warning

Compose cannot publish a host port for a scaled service. With more than one ingester or MCP replica, the OTLP (4317/4318) and MCP (8000) endpoints are reachable only on the compose network, not from the host; run your own proxy in front if you need host access. Use the swarm or kubernetes casting for load-balanced replicas.