# Install SigNoz on Docker Standalone - Self-Host Guide

> Source: <https://signoz.io/docs/install/docker>
> Published: 2026-06-24 00:00:00+00:00

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/).