Install SigNoz on Docker Swarm - Self-Hosted Setup

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 a Docker Swarm cluster. Foundry generates a stack Compose file from your configuration and deploys it across the swarm with docker stack deploy.

Prerequisites

A Docker Swarm cluster with Swarm mode initialized (docker swarm init) and at least one manager node.
Docker Engine 20.10+ on each node.
At least 4GB of memory available per node.
Open ports: 8080 (SigNoz UI), 4317 and 4318 (OTLP ingestion).

Install SigNoz

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.

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 Swarm with flavor: swarm and mode: docker:

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

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

Step 3: Deploy

Run this on a swarm manager node:

foundryctl cast -f casting.yaml

cast chains Foundry's three stages:

gauge checks your environment
forge renders the Compose files into pours/ (with your SELinux labels applied) 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 (labels included)
cd pours/deployment && docker stack deploy -c pours/deployment/compose.yaml signoz   # deploy it as the "signoz" stack

Step 4: Verify the installation

Monitor the stack until the long-running services report their full replica count:

docker stack services signoz

The output should look similar to the following:

ID             NAME                                                   MODE         REPLICAS   IMAGE                                 PORTS
umo0h2zcccyl   signoz_ingester                                        replicated   1/1        signoz/signoz-otel-collector:latest   *:4317-4318->4317-4318/tcp
9nrnfpyx7ioc   signoz_signoz-metastore-postgres-0                     replicated   1/1        postgres:16
h6obimnoj110   signoz_signoz-signoz-0                                 replicated   1/1        signoz/signoz:latest                  *:8080->8080/tcp
gyf7woac9m4p   signoz_signoz-telemetrykeeper-clickhousekeeper-0       replicated   1/1        clickhouse/clickhouse-keeper:25.5.6
oxx2l13lvwdd   signoz_signoz-telemetrystore-clickhouse-0-0            replicated   1/1        clickhouse/clickhouse-server:25.5.6
e65ymxjial3p   signoz_signoz-telemetrystore-clickhouse-user-scripts   global       0/0        clickhouse/clickhouse-server:25.5.6
pofn1bs2qzpj   signoz_signoz-telemetrystore-migrator                  replicated   0/1        signoz/signoz-otel-collector:latest

Docker prefixes every service with the stack name (signoz_). The five long-running services should reach 1/1. The two bootstrap jobs run once and then stop, which is expected: …clickhouse-user-scripts runs in global mode and shows 0/0 after finishing, and …migrator shows 0/1 after its run. Confirm it finished without errors (see Troubleshooting).

Confirm the SigNoz backend is healthy:

curl http://localhost:8080/api/v1/health

A healthy backend returns {"status":"ok"}. Because Swarm publishes the port through its routing mesh, the UI is reachable on port 8080 of any node in the swarm. Open http://<NODE-IP>:8080/ (use http://localhost:8080/ on a single-node swarm).

Troubleshooting

`foundryctl cast` or `docker stack deploy` fails to deploy the stack

Deploying a stack requires Docker to be running, Swarm mode to be active, and the command to run on a manager node; a non-manager node fails with this node is not a swarm manager. Check all three at once:

docker info --format 'Swarm: {{.Swarm.LocalNodeState}} | Manager: {{.Swarm.ControlAvailable}}'

Swarm: active means Swarm mode is on. If it reads inactive, initialize it with docker swarm init (or join an existing swarm).
Manager: true means this node is a manager. If it reads false, run the deploy from a manager node instead.

A service keeps restarting right after deploy

Docker Swarm starts every service in parallel and does not honor depends_on. Until ClickHouse and Postgres are ready, dependent services such as signoz_signoz-signoz-0 and signoz_signoz-telemetrystore-migrator may fail and restart a few times before they settle. Inspect any service that does not recover:

docker stack ps signoz                                       # per-task state and last error
docker service logs signoz_signoz-telemetrystore-migrator    # full logs for one service

To redeploy from a clean slate, remove the stack and run cast again (this keeps the named data volumes):

docker stack rm signoz
foundryctl cast -f casting.yaml

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.