Install SigNoz on Docker Standalone - Self-Host Guide

This guide explains how to install SigNoz on Docker using Docker Compose. It runs all the components SigNoz requires on a single machine, making it the quickest way to get started with SigNoz.

Prerequisites

• A Linux or macOS machine. Microsoft Windo

ws is not officially supported. Docker Engine20.10+ (or Docker Desktop) with theDocker Composev2 plugin.- At least 4GB of memory allocated to Docker.

• Open ports: 8080

(SigNoz UI),4317

and4318

(OTLP ingestion), and8000

if you enable the MCP server.

Install SigNoz

Step 1: Install foundryctl

curl -fsSL https://signoz.io/foundry.sh | bash

For manual install (Windows PowerShell, air-gapped, etc.) or PATH setup, see the foundry getting-started guide.

Step 2: Create casting.yaml

Create a casting file that targets Docker with flavor: compose

and mode: docker

:

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

For all configuration options, see the casting file reference and the Docker Compose example.

Step 3: Deploy

foundryctl cast -f casting.yaml

cast

validates Docker, generates the Compose files into pours/deployment/

, and starts the containers.

Step 4: Verify the installation

Check that the containers are running:

docker ps

The output should look similar to the following:

CONTAINER ID   IMAGE                                 COMMAND                  CREATED              STATUS                        PORTS                                                             NAMES
315e746cf0ff   clickhouse/clickhouse-server:25.5.6   "/entrypoint.sh"         About a minute ago   Up About a minute (healthy)   8123/tcp, 9000/tcp, 9009/tcp                                      signoz-telemetrystore-clickhouse-0-0
066dc6f6346f   postgres:16                           "docker-entrypoint.s…"   About a minute ago   Up About a minute (healthy)   5432/tcp                                                          signoz-metastore-postgres-0
e3b456480fe4   clickhouse/clickhouse-keeper:25.5.6   "/usr/bin/clickhouse…"   About a minute ago   Up About a minute (healthy)   2181/tcp, 9181/tcp, 10181/tcp, 44444/tcp                          signoz-telemetrykeeper-clickhousekeeper-0
51f763006ae0   signoz/signoz-otel-collector:latest   "/bin/sh -c '/signoz…"   About a minute ago   Up About a minute             0.0.0.0:4317-4318->4317-4318/tcp, [::]:4317-4318->4317-4318/tcp   signoz-ingester-1
c7550a1412d4   signoz/signoz:latest                  "./signoz server"        About a minute ago   Up About a minute (healthy)   0.0.0.0:8080->8080/tcp, [::]:8080->8080/tcp                       signoz-signoz-0

Once all containers are running, point your browser to http://<IP-ADDRESS>:8080/

to access the SigNoz UI (use http://localhost:8080/

when SigNoz runs on your local machine).

Step 5: Enable the SigNoz MCP server (optional)

Foundry can also deploy the SigNoz MCP server alongside the stack so AI clients can query your telemetry. It is disabled by default.

Add an

mcp

block underspec

incasting.yaml

:

apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: compose
    mode: docker
  mcp:
    spec:
      enabled: true

Re-run cast to add the

signoz-mcp

service on port8000

:

foundryctl cast -f casting.yaml

Verify it is live:

curl -fsS localhost:8000/livez && echo " OK"

Create an API key from a

service account(Settings → Service Accounts, requires** Admin**role). - Add the server to your AI client. For example, with Claude Code:

claude mcp add --scope user --transport http signoz http://localhost:8000/mcp \
  --header "SIGNOZ-API-KEY: <your-api-key>"

<your-api-key>

: the key from step 3

To confirm the connection, run

/mcp

inside Claude Code and check that thesignoz

server is listed as connected.

For other clients and example workflows, see SigNoz MCP Server and AI use cases.

Customize the installation

Every change follows the same loop: update casting.yaml

, then re-run foundryctl cast

to apply it.

Component settings(image, replicas, environment): set them in the component'sspec

. For example, to pin SigNoz to a specific release, set its image to a version tag:

spec:
  signoz:
    spec:
      image: signoz/signoz:v0.128.0

Anything Foundry does not model(memory limits, networks, volumes): addpatchesunderspec.patches

. Do not edit the generated files inpours/

by hand, since forge overwrites them.

Troubleshooting

Troubleshooting

foundryctl fails

Re-run the failing command with --debug

for verbose logs.

A container is unhealthy or the UI does not load

Check the component's logs using the generated Compose file:

docker compose -f pours/deployment/compose.yaml logs -f signoz-signoz-0

Containers keep restarting

Increase the memory allocated to Docker. SigNoz needs at least 4GB.

By default, retention period is set to 7 days for logs and traces, and 30 days for metrics. To change this, navigate to the General tab on the Settings page of SigNoz UI.

For more details, refer to the retention period guide.

source & further reading

signoz.io — original article Send Metrics from Java Application using OpenTelemetry Tomcat OpenTelemetry Instrumentation Guide Splunk vs Dynatrace - Which Tool To Choose? [2026 Guide]