# Install SigNoz on Docker Standalone - Self-Host Guide

Learn how to install SigNoz on Docker. Self-host guide for macOS, Linux, and Windows (WSL 2), from setup to verifying the install in the SigNoz UI.

> For the complete documentation index, see [llms.txt](https://signoz.io/llms.txt). Markdown versions are also available by appending `.md` to documentation URLs.

Tags: Self-Hosted Community

## Hosting Options

- [Compare Self Host vs Cloud](/blog/cloud-vs-self-hosted-deployment-guide/)
- [Get Started - Free](/teams/)

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.

> **Warning: Migrating from the install script or bundled Docker Compose?**
>
> The legacy install script (`install.sh`) and the Docker Compose files bundled under `deploy/` in the SigNoz repository are deprecated as of [SigNoz v0.130.0](https://github.com/SigNoz/signoz/releases/tag/v0.130.0) and are no longer maintained or distributed. Foundry, documented below, is now the supported way to install and manage SigNoz, Docker Compose included.
>
> If you have an existing install-script or Compose deployment, follow the [migration guide](https://github.com/SigNoz/signoz/blob/main/deploy/MIGRATION.md) to move to Foundry without losing your data.

## Prerequisites

- A Linux or macOS machine. On Microsoft Windows, use WSL 2 with Docker Engine installed inside WSL (see the note below).
- [Docker Engine](https://docs.docker.com/engine/install/) 20.10+ (or Docker Desktop on macOS/Linux) 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.

> **Info: Running SigNoz on Windows (WSL 2)**
>
> On Windows, run everything inside a [WSL 2](https://learn.microsoft.com/en-us/windows/wsl/install) distribution with Docker Engine installed natively in WSL, not Docker Desktop. ClickHouse Keeper has been reported to crash in a restart loop with segmentation faults (exit code 139) under Docker Desktop's virtualization layer on Windows.
>
> 1. Install Docker Engine inside your WSL distribution (for example, Ubuntu):
>
>    ```
>    curl -fsSL https://get.docker.com | sh
>    ```
>
> 2. Allow your user to run Docker without sudo, then close and reopen the WSL shell:
>
>    ```
>    sudo usermod -aG docker $USER
>    ```
>
>    If `docker ps` fails with `Cannot connect to the Docker daemon`, start the daemon with `sudo service docker start` (needed on distributions without systemd enabled).
>
> 3. If Docker Desktop is installed, disable its WSL integration for the distribution (**Settings → Resources → WSL integration**) so `docker` inside WSL uses the native engine.
>
> 4. Follow the rest of this guide from the WSL shell.

## Install SigNoz

> **Info: What is Foundry?**
>
> Foundry is an open-source CLI that runs your self-hosted observability stack as code. One declarative config provisions the infrastructure, installs the SigNoz backend, and sets up OpenTelemetry collection on bare metal, containers, or Kubernetes. Learn more about [Foundry](https://github.com/SigNoz/foundry).

### 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.

> **Tip: Skip cast and run docker compose directly**
>
> `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](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.

1. 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
   ```

2. 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"
   ```

3. Create an API key from a [service account](https://signoz.io/docs/manage/administrator-guide/iam/service-accounts/) (**Settings → Service Accounts**, requires **Admin** role).

4. 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

### 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.

### clickhouse-keeper keeps restarting with exit code 139 on Windows

Exit code 139 is a segmentation fault. ClickHouse Keeper segfaults under Docker Desktop's virtualization layer on Windows. Run the stack with native Docker Engine inside WSL 2 instead, as described in [Prerequisites](#prerequisites).

Component: RetentionInfo

## Next Steps

- [Collect Telemetry from your Docker Clusters](https://signoz.io/docs/opentelemetry-collection-agents/docker/install/)
- [Instrument Your Application](https://signoz.io/docs/instrumentation/overview/)
- [Send Sample Telemetry with OpenTelemetry Demo Lite](https://github.com/SigNoz/opentelemetry-demo-lite)

More docs: /docs/sitemap.md