binary

Systemd Binary Casting

Field	Value
Mode	systemd
Flavor	binary
Platform	-

Overview

Deploys SigNoz on bare metal as systemd units — one service per component (SigNoz, OTel Collector, ClickHouse, ClickHouse Keeper, and PostgreSQL when used), running under a dedicated signoz service user. foundryctl cast generates the units and starts them.

Prerequisites

Install the component binaries to their default locations; cast handles everything else. To install elsewhere, point to them with annotations.

The SigNoz binaries are GitHub release tarballs, each extracted into its /opt directory:

ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')

# SigNoz (query engine + UI)
sudo mkdir -p /opt/signoz
curl -fsSL "https://github.com/SigNoz/signoz/releases/latest/download/signoz_linux_${ARCH}.tar.gz" \
  | sudo tar -xz --strip-components=1 -C /opt/signoz

# OTel Collector (ingester)
sudo mkdir -p /opt/ingester
curl -fsSL "https://github.com/SigNoz/signoz-otel-collector/releases/latest/download/signoz-otel-collector_linux_${ARCH}.tar.gz" \
  | sudo tar -xz --strip-components=1 -C /opt/ingester

# MCP server (only when spec.mcp.spec.enabled is true)
sudo mkdir -p /opt/mcp
curl -fsSL "https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_linux_${ARCH}.tar.gz" \
  | sudo tar -xz --strip-components=1 -C /opt/mcp

Important

Extract the full SigNoz tarball; do not move the signoz binary on its own. It loads the web UI and email/alert templates relative to itself, so bin/, web/, templates/, and conf/ must stay together.

ClickHouse, PostgreSQL, and ZooKeeper are installed from their own packages:

• ClickHouse: one clickhouse binary serves both the telemetry store and the keeper
• PostgreSQL: only when metastore.kind is postgres
• Apache ZooKeeper: only when telemetrykeeper.kind is zookeeper; extract the release to /opt/zookeeper and install a Java runtime

Configuration

apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: binary
    mode: systemd

Deploy

sudo foundryctl cast -f casting.yaml

cast checks the binaries are present, then installs and starts the systemd units.

Note

cast requires sudo because it manages systemd services, creates the service users, and writes to system directories.

Important

Upgrading an existing installation: ClickHouse Keeper now stores its Raft state in /var/lib/clickhouse-keeper (created automatically by the unit's StateDirectory=) instead of /var/lib/clickhouse. Move the existing coordination data before re-running cast, otherwise the keeper starts with empty state:

sudo systemctl stop 'signoz-telemetrykeeper-*'
sudo mkdir -p /var/lib/clickhouse-keeper
sudo mv /var/lib/clickhouse/coordination /var/lib/clickhouse-keeper/
sudo chown -R clickhouse:clickhouse /var/lib/clickhouse-keeper

Fresh installations need no action.

To inspect before deploying:

# Check the orchestration tool (systemctl) is available
foundryctl gauge -f casting.yaml

# Generate the unit files and configs into pours/ without touching the host
foundryctl forge -f casting.yaml

Generated output

pours/deployment/
  signoz-ingester.service
  signoz-metastore-postgres.service
  signoz-signoz.service
  signoz-telemetrykeeper-clickhousekeeper-0.service
  signoz-telemetrystore-clickhouse-0-0.service
  signoz-telemetrystore-migrator.service
  ingester/
    ingester.yaml
    opamp.yaml
  telemetrykeeper/clickhousekeeper/
    keeper-0.yaml
  telemetrystore/clickhouse/
    config-0-0.yaml
    functions.yaml

Operating

Services are named <metadata.name>-<component>.service.

# Status of all services
systemctl status 'signoz-*'

# Follow logs for one service
journalctl -u signoz-signoz.service -f

# Follow logs for all services
journalctl -u 'signoz-*' -f

Annotations

Set an annotation only when a binary is installed outside its default location.

Annotation	Default	Binary
foundry.signoz.io/signoz-binary-path	/opt/signoz/bin/signoz	SigNoz
foundry.signoz.io/ingester-binary-path	/opt/ingester/bin/signoz-otel-collector	OTel Collector
foundry.signoz.io/metastore-postgres-binary-path	/usr/bin/postgres	PostgreSQL (its directory must also hold initdb)
foundry.signoz.io/telemetrystore-clickhouse-binary-path	/usr/bin/clickhouse	ClickHouse, run as clickhouse server
foundry.signoz.io/telemetrykeeper-clickhousekeeper-binary-path	/usr/bin/clickhouse	ClickHouse, run as clickhouse keeper
foundry.signoz.io/telemetrykeeper-zookeeper-binary-path	/opt/zookeeper/bin/zkServer.sh	Apache ZooKeeper, run as zkServer.sh start-foreground (needs Java)
foundry.signoz.io/mcp-binary-path	/opt/mcp/bin/signoz-mcp-server	SigNoz MCP server

metadata:
  annotations:
    foundry.signoz.io/signoz-binary-path: /custom/bin/signoz