Install SigNoz on Docker Standalone - Self-Host Guide

SigNoz released a self-host guide for installing its open-source observability platform on Docker standalone using Docker Compose. The guide walks users through installing foundryctl, creating a casting.yaml configuration file, and deploying the stack to run SigNoz on a single machine. The installation includes components like ClickHouse, PostgreSQL, and the SigNoz UI, with optional support for an MCP server to enable AI client queries.

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 Engine https://docs.docker.com/engine/install/ 20.10+ or Docker Desktop with the Docker Compose https://docs.docker.com/compose/install/ v2 plugin.- At least 4GB of memory allocated to Docker. - Open ports: 8080 SigNoz UI , 4317 and 4318 OTLP ingestion , and 8000 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 https://github.com/SigNoz/foundry/blob/main/docs/getting-started.md . 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 https://github.com/SigNoz/foundry/blob/main/docs/reference/casting-file.md and the Docker Compose example https://github.com/SigNoz/foundry/tree/main/docs/examples/docker/compose . 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 https://github.com/SigNoz/foundry/blob/main/docs/concepts/mcp-server.md alongside the stack so AI clients can query your telemetry. It is disabled by default. - Add an mcp block under spec in casting.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 port 8000 : foundryctl cast -f casting.yaml Verify it is live: curl -fsS localhost:8000/livez && echo " OK" - Create an API key from a service account https://signoz.io/docs/manage/administrator-guide/iam/service-accounts/ 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 the signoz server is listed as connected. For other clients and example workflows, see SigNoz MCP Server https://signoz.io/docs/ai/signoz-mcp-server/ and AI use cases https://signoz.io/docs/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's spec . 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 : add patches https://github.com/SigNoz/foundry/blob/main/docs/concepts/patches.md under spec.patches . Do not edit the generated files in pours/ by hand, since forge overwrites them. Troubleshooting 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 https://signoz.io/docs/userguide/retention-period/ .