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),4317and4318(OTLP ingestion).
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 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
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: activemeans Swarm mode is on. If it readsinactive, initialize it withdocker swarm init(or join an existing swarm).Manager: truemeans this node is a manager. If it readsfalse, 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.
