Install SigNoz on Docker Standalone - Self-Host Guide

Choose SigNoz Cloud for ease, or self-host for control—with the freedom to switch as your needs grow.

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 Windows is not officially supported.
Docker Engine 20.10+ (or Docker Desktop) with the Docker Compose 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.

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.

cast chains Foundry's three stages:

gauge checks your environment
forge renders the Compose files into pours/ and writes casting.yaml.lock
cast starts the stack

If you prefer to manage the containers yourself, render the files with forge, inspect them, and bring the stack up with Docker Compose:

foundryctl gauge -f casting.yaml   # validate prerequisites
foundryctl forge -f casting.yaml   # generate compose files
cd pours/deployment && docker compose up -d

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 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 (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 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'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 under spec.patches. Do not edit the generated files in pours/ by hand, since forge overwrites them.

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.