Install SigNoz on Linux with systemd - Self-Host Guide

Choose SigNoz Cloud for ease, or self-host for control—with the freedom to switch as your needs grow.

Use this page to install SigNoz on a Linux host that runs systemd. The recommended path uses Foundry to create and manage the systemd units for SigNoz, ClickHouse, ClickHouse Keeper, PostgreSQL, the SigNoz OTel Collector, and the database migrator. If you need full control over every service unit and config, use the Manual tab instead.

Prerequisites

A Linux host with systemd.
Root access or a user with sudo privileges.
Open inbound ports: 8080 for the SigNoz UI, and 4317 and 4318 for OpenTelemetry Protocol (OTLP) ingestion.
At least 4 GB of memory for a small test installation. For production sizing, see resource planning.

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

Run the installer on the Linux host:

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: Install host dependencies

Install ClickHouse with the official ClickHouse installation guide. The single clickhouse binary serves both the telemetry store and the keeper, so no separate Keeper package is needed. Foundry manages the ClickHouse services after deployment, so stop any package-managed services:

sudo systemctl disable --now clickhouse-server.service clickhouse-keeper.service 2>/dev/null || true

Install PostgreSQL with the official PostgreSQL Linux installation guide, then stop the package-managed service:

sudo systemctl disable --now postgresql.service

PostgreSQL packages install the server binary outside /usr/bin on most distros. Debian and Ubuntu use /usr/lib/postgresql/<version>/bin; RHEL and Fedora use /usr/pgsql-<version>/bin. Note the path to your postgres binary; you point Foundry at it in Step 4.

Step 3: Download SigNoz binaries

Download the SigNoz and SigNoz OTel Collector release archives into the paths that the Foundry systemd casting uses:

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

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

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

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.

foundryctl cast creates the signoz service user and the data directories automatically.

Step 4: Create casting.yaml

Create a working directory outside /root so the generated pours/ files remain readable by the signoz system user:

sudo mkdir -p /opt/signoz-foundry
sudo chown "$(id -u):$(id -g)" /opt/signoz-foundry
cd /opt/signoz-foundry

Create casting.yaml for the systemd binary deployment:

cat <<'EOF' > casting.yaml
apiVersion: v1alpha1
kind: Installation
metadata:
  name: signoz
spec:
  deployment:
    flavor: binary
    mode: systemd
EOF

If your postgres binary is not at /usr/bin/postgres (Step 2), point Foundry at it with a binary-path annotation under metadata. The directory must also contain initdb:

metadata:
  name: signoz
  annotations:
    foundry.signoz.io/metastore-postgres-binary-path: /usr/lib/postgresql/16/bin/postgres

See the Foundry systemd binary example for all binary-path annotations.

Step 5: Deploy with Foundry

Run the full deployment pipeline:

sudo foundryctl cast -f casting.yaml

foundryctl cast validates dependencies, generates service files and configs under pours/, installs systemd units, and starts the SigNoz services.

foundryctl cast needs sudo because it writes to system directories and manages systemd services.

Step 6: Validate the installation

Check that the main services are running:

systemctl status signoz-signoz.service
systemctl status signoz-ingester.service
systemctl status signoz-telemetrystore-clickhouse-0-0.service
systemctl status signoz-telemetrykeeper-clickhousekeeper-0.service
systemctl status signoz-metastore-postgres.service

Each service should show active (running).

View logs for all SigNoz services:

journalctl -u 'signoz-*' -f

View logs for one service:

journalctl -u signoz-signoz.service -f

Open http://<your-server-ip>:8080/ in a browser. The SigNoz setup screen should load.

Step 7: Enable the SigNoz MCP server (optional)

Foundry can also deploy the SigNoz MCP server alongside the stack so AI clients can query your telemetry. It is disabled by default.

Download the MCP server binary into the path the casting expects:

ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
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

Add an mcp block under spec in casting.yaml:

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

Re-run cast to add the MCP service on port 8000:

sudo foundryctl cast -f casting.yaml

Verify it is live:

curl -fsS localhost:8000/livez && echo " OK"

Create an API key from a service account (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 4
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 and AI use cases.

Customize the installation

Every change follows the same loop: edit casting.yaml, then re-run foundryctl cast to apply it.

Binary locations: if a component lives outside its default path, point Foundry at it with a binary-path annotation under metadata.annotations. The systemd binary example lists every annotation.
Anything Foundry does not model: add patches under spec.patches. Do not edit the generated files in pours/ by hand, since forge overwrites them.
Pin a version: download a specific SigNoz or SigNoz OTel Collector release in Step 3 instead of latest.

Troubleshooting

`foundryctl cast` fails

Re-run the failing command with --debug for verbose logs:

sudo foundryctl cast -f casting.yaml --debug

`sudo` cannot find `foundryctl`

Run foundryctl through sudo with your current PATH:

sudo env "PATH=$PATH" foundryctl cast -f casting.yaml

You can also install foundryctl into a system path such as /usr/local/bin.

ClickHouse cannot connect to Keeper on Ubuntu

On some Ubuntu hosts, localhost resolves to ::1 first while ClickHouse Keeper listens on IPv4. If signoz-telemetrystore-clickhouse-0-0.service fails to start, replace localhost with 127.0.0.1 in the generated config:

sudo sed -i 's/host: localhost/host: 127.0.0.1/' /etc/clickhouse-server/config-0-0.yaml
sudo systemctl restart signoz-telemetrystore-clickhouse-0-0.service

Check the service logs again:

journalctl -u signoz-telemetrystore-clickhouse-0-0.service -f

foundryctl cast regenerates the ClickHouse config and overwrites this change, so a later cast (for example, enabling the MCP server in Step 7) reintroduces the failure. To persist the fix, set the Keeper host to 127.0.0.1 through the ClickHouse component's config.data in casting.yaml so forge writes it on every run. See the Foundry config and patches guide. If you keep the manual edit, re-run the sed command after every foundryctl cast.

A SigNoz service fails after cast

Inspect the unit and logs for the failing service:

systemctl status <service-name>
journalctl -u <service-name> -n 200 --no-pager

The manual path installs ClickHouse, ZooKeeper, SigNoz, and the SigNoz OTel Collector as separate systemd services. Use it when you need to own every config file and service unit. The Foundry path handles more of this work for you.

These commands use Debian and Ubuntu package commands. Adapt package-manager commands for another Linux distribution.

Step 1: Install ClickHouse

Install ClickHouse with the official ClickHouse installation guide.

Do not start clickhouse-server.service yet. Start it after you configure ZooKeeper.

During installation, ClickHouse prompts for a password for the default user. If you leave it empty, the DSN strings below work as written. If you set a password, add it as a password query parameter to each DSN below, after the database path where one is present. Use tcp://localhost:9000?password=<your-password> for a DSN with no database path, and tcp://localhost:9000/signoz_traces?password=<your-password> when a database path is present.

<your-password>: the password you set for the ClickHouse default user.

Step 2: Install ZooKeeper

ClickHouse uses ZooKeeper for distributed coordination. A single ZooKeeper instance is enough for this single-node ClickHouse setup.

Install Java:

sudo apt update
sudo apt install -y default-jdk

Download and extract ZooKeeper:

ZOOKEEPER_VERSION=3.9.5
curl -L "https://archive.apache.org/dist/zookeeper/zookeeper-${ZOOKEEPER_VERSION}/apache-zookeeper-${ZOOKEEPER_VERSION}-bin.tar.gz" -o zookeeper.tar.gz
tar -xzf zookeeper.tar.gz

Create ZooKeeper directories and copy the extracted files:

ZOOKEEPER_VERSION=3.9.5
sudo mkdir -p /opt/zookeeper /var/lib/zookeeper /var/log/zookeeper
sudo cp -R "apache-zookeeper-${ZOOKEEPER_VERSION}-bin/"* /opt/zookeeper/

Create the ZooKeeper config file:

sudo bash -c 'cat <<EOF > /opt/zookeeper/conf/zoo.cfg
tickTime=2000
dataDir=/var/lib/zookeeper
clientPort=2181
admin.serverPort=3181
EOF'

Create the ZooKeeper systemd environment file:

sudo bash -c 'cat <<EOF > /opt/zookeeper/conf/zoo.env
ZOO_LOG_DIR=/var/log/zookeeper
EOF'

Create the zookeeper user and give it ownership of the ZooKeeper directories:

getent passwd zookeeper >/dev/null || sudo useradd --system --home /opt/zookeeper --no-create-home --user-group --shell /sbin/nologin zookeeper
sudo chown -R zookeeper:zookeeper /opt/zookeeper /var/lib/zookeeper /var/log/zookeeper

Create the ZooKeeper systemd service:

sudo bash -c 'cat <<EOF > /etc/systemd/system/zookeeper.service
[Unit]
Description=ZooKeeper
Documentation=https://zookeeper.apache.org/

[Service]
EnvironmentFile=/opt/zookeeper/conf/zoo.env
Type=forking
WorkingDirectory=/opt/zookeeper
User=zookeeper
Group=zookeeper
ExecStart=/opt/zookeeper/bin/zkServer.sh start /opt/zookeeper/conf/zoo.cfg
ExecStop=/opt/zookeeper/bin/zkServer.sh stop /opt/zookeeper/conf/zoo.cfg
ExecReload=/opt/zookeeper/bin/zkServer.sh restart /opt/zookeeper/conf/zoo.cfg
TimeoutSec=30
Restart=on-failure

[Install]
WantedBy=multi-user.target
EOF'

Start ZooKeeper:

sudo systemctl daemon-reload
sudo systemctl enable --now zookeeper.service

Configure ClickHouse to use ZooKeeper and start ClickHouse:

sudo bash -c 'cat <<EOF > /etc/clickhouse-server/config.d/cluster.xml
<clickhouse replace="true">
    <distributed_ddl>
        <path>/clickhouse/task_queue/ddl</path>
    </distributed_ddl>
    <remote_servers>
        <cluster>
            <shard>
                <replica>
                    <host>127.0.0.1</host>
                    <port>9000</port>
                </replica>
            </shard>
        </cluster>
    </remote_servers>
    <zookeeper>
        <node>
            <host>127.0.0.1</host>
            <port>2181</port>
        </node>
    </zookeeper>
    <macros>
        <shard>01</shard>
        <replica>01</replica>
    </macros>
</clickhouse>
EOF'
sudo chown clickhouse:clickhouse /etc/clickhouse-server/config.d/cluster.xml
sudo systemctl enable --now clickhouse-server.service

Verify both services:

systemctl is-active clickhouse-server.service
systemctl is-active zookeeper.service

Both commands should print active.

Step 3: Run ClickHouse migrations

Download the SigNoz OTel Collector binary and run the ClickHouse migrations:

ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
curl -L "https://github.com/SigNoz/signoz-otel-collector/releases/latest/download/signoz-otel-collector_linux_${ARCH}.tar.gz" -o signoz-otel-collector.tar.gz
tar -xzf signoz-otel-collector.tar.gz

COLLECTOR="./signoz-otel-collector_linux_${ARCH}/bin/signoz-otel-collector"
CLICKHOUSE_DSN="tcp://localhost:9000"

"$COLLECTOR" migrate bootstrap --clickhouse-dsn="$CLICKHOUSE_DSN" --clickhouse-replication=true
"$COLLECTOR" migrate sync up --clickhouse-dsn="$CLICKHOUSE_DSN" --clickhouse-replication=true
"$COLLECTOR" migrate async up --clickhouse-dsn="$CLICKHOUSE_DSN" --clickhouse-replication=true

If you set a ClickHouse password, change CLICKHOUSE_DSN to tcp://localhost:9000?password=<your-password>.

Step 4: Install SigNoz

Download and extract the SigNoz binary:

ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
curl -L "https://github.com/SigNoz/signoz/releases/latest/download/signoz_linux_${ARCH}.tar.gz" -o signoz.tar.gz
tar -xzf signoz.tar.gz

Copy the files into /opt/signoz:

sudo mkdir -p /opt/signoz /var/lib/signoz /opt/signoz/conf
sudo cp -R "signoz_linux_${ARCH}/"* /opt/signoz/

Create the SigNoz systemd environment file:

sudo bash -c 'cat <<EOF > /opt/signoz/conf/systemd.env
SIGNOZ_INSTRUMENTATION_LOGS_LEVEL=info
INVITE_EMAIL_TEMPLATE=/opt/signoz/templates/email/invitation.gotmpl
SIGNOZ_SQLSTORE_SQLITE_PATH=/var/lib/signoz/signoz.db
SIGNOZ_WEB_ENABLED=true
SIGNOZ_WEB_DIRECTORY=/opt/signoz/web
SIGNOZ_JWT_SECRET=$(openssl rand -hex 32)
SIGNOZ_ALERTMANAGER_PROVIDER=signoz
SIGNOZ_TELEMETRYSTORE_PROVIDER=clickhouse
SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN=tcp://localhost:9000
DOT_METRICS_ENABLED=true
EOF'

If you set a ClickHouse password, append the query parameter to SIGNOZ_TELEMETRYSTORE_CLICKHOUSE_DSN (this DSN has no database path): tcp://localhost:9000?password=<your-password>.

Create the signoz user and give it ownership of the SigNoz directories:

getent passwd signoz >/dev/null || sudo useradd --system --home /opt/signoz --no-create-home --user-group --shell /sbin/nologin signoz
sudo chown -R signoz:signoz /var/lib/signoz /opt/signoz

Create the SigNoz systemd service:

sudo bash -c 'cat <<EOF > /etc/systemd/system/signoz.service
[Unit]
Description=SigNoz
Documentation=https://signoz.io/docs
After=clickhouse-server.service zookeeper.service
Wants=clickhouse-server.service zookeeper.service

[Service]
User=signoz
Group=signoz
Type=simple
KillMode=mixed
Restart=on-failure
WorkingDirectory=/opt/signoz
EnvironmentFile=/opt/signoz/conf/systemd.env
ExecStart=/opt/signoz/bin/signoz server

[Install]
WantedBy=multi-user.target
EOF'

Start SigNoz:

sudo systemctl daemon-reload
sudo systemctl enable --now signoz.service

Verify SigNoz:

systemctl is-active signoz.service
curl -fsS http://localhost:8080/api/v1/health

The service check should print active, and the health endpoint should return {"status":"ok"}.

Step 5: Install the SigNoz OTel Collector

The SigNoz OTel Collector receives traces, metrics, and logs from your applications and writes them to ClickHouse.

Create the Collector directories and copy the binary files:

ARCH=$(uname -m | sed 's/x86_64/amd64/' | sed 's/aarch64/arm64/')
sudo mkdir -p /var/lib/signoz-otel-collector /opt/signoz-otel-collector /opt/signoz-otel-collector/conf
sudo cp -R "signoz-otel-collector_linux_${ARCH}/"* /opt/signoz-otel-collector/
sudo chown -R signoz:signoz /var/lib/signoz-otel-collector /opt/signoz-otel-collector

Create the Collector config file:

sudo bash -c 'cat <<EOF > /opt/signoz-otel-collector/conf/config.yaml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
        max_recv_msg_size_mib: 16
      http:
        endpoint: 0.0.0.0:4318
  jaeger:
    protocols:
      grpc:
        endpoint: 0.0.0.0:14250
      thrift_http:
        endpoint: 0.0.0.0:14268
  httplogreceiver/heroku:
    endpoint: 0.0.0.0:8081
    source: heroku
  httplogreceiver/json:
    endpoint: 0.0.0.0:8082
    source: json
processors:
  batch:
    send_batch_size: 50000
    timeout: 1s
  signozspanmetrics/delta:
    metrics_exporter: signozclickhousemetrics
    latency_histogram_buckets: [100us, 1ms, 2ms, 6ms, 10ms, 50ms, 100ms, 250ms, 500ms, 1000ms, 1400ms, 2000ms, 5s, 10s, 20s, 40s, 60s]
    dimensions_cache_size: 100000
    dimensions:
      - name: service.namespace
        default: default
      - name: deployment.environment
        default: default
      - name: signoz.collector.id
    aggregation_temporality: AGGREGATION_TEMPORALITY_DELTA
extensions:
  health_check:
    endpoint: 0.0.0.0:13133
  zpages:
    endpoint: localhost:55679
  pprof:
    endpoint: localhost:1777
exporters:
  clickhousetraces:
    datasource: tcp://localhost:9000/signoz_traces
    use_new_schema: true
  signozclickhousemetrics:
    dsn: tcp://localhost:9000/signoz_metrics
    timeout: 45s
  clickhouselogsexporter:
    dsn: tcp://localhost:9000/signoz_logs
    timeout: 10s
    use_new_schema: true
  metadataexporter:
    dsn: tcp://localhost:9000/signoz_metadata
    timeout: 10s
    tenant_id: default
    cache:
      provider: in_memory
service:
  telemetry:
    logs:
      encoding: json
  extensions: [health_check, zpages, pprof]
  pipelines:
    traces:
      receivers: [otlp, jaeger]
      processors: [signozspanmetrics/delta, batch]
      exporters: [clickhousetraces, metadataexporter]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [metadataexporter, signozclickhousemetrics]
    logs:
      receivers: [otlp, httplogreceiver/heroku, httplogreceiver/json]
      processors: [batch]
      exporters: [clickhouselogsexporter, metadataexporter]
EOF'

If you set a ClickHouse password, append the query parameter after the database path in every exporter DSN above, for example tcp://localhost:9000/signoz_traces?password=<your-password>.

Create the OpAMP config file:

sudo bash -c 'cat <<EOF > /opt/signoz-otel-collector/conf/opamp.yaml
server_endpoint: ws://127.0.0.1:4320/v1/opamp
EOF'

Create the Collector systemd service:

sudo bash -c 'cat <<EOF > /etc/systemd/system/signoz-otel-collector.service
[Unit]
Description=SigNoz OTel Collector
Documentation=https://signoz.io/docs
After=clickhouse-server.service signoz.service
Wants=clickhouse-server.service signoz.service

[Service]
User=signoz
Group=signoz
Type=simple
KillMode=mixed
Restart=on-failure
WorkingDirectory=/opt/signoz-otel-collector
ExecStart=/opt/signoz-otel-collector/bin/signoz-otel-collector --config=/opt/signoz-otel-collector/conf/config.yaml --manager-config=/opt/signoz-otel-collector/conf/opamp.yaml --copy-path=/var/lib/signoz-otel-collector/config.yaml

[Install]
WantedBy=multi-user.target
EOF'

Start the Collector:

sudo systemctl daemon-reload
sudo systemctl enable --now signoz-otel-collector.service

Verify the Collector:

systemctl is-active signoz-otel-collector.service
sudo ss -ltnp | grep -E ':4317|:4318'

The service check should print active, and ss should show listeners on 4317 and 4318.

Step 6: Open the SigNoz UI

Open http://<your-server-ip>:8080/ in a browser. The SigNoz setup screen should load.

Troubleshooting

Migrations fail

Check that ClickHouse responds:

curl -s http://localhost:8123/ping

The expected response is Ok.. If you set a ClickHouse password, confirm that every ClickHouse DSN carries password=<your-password> as a query parameter after the database path (for example tcp://localhost:9000/signoz_traces?password=<your-password>).

SigNoz health check fails

Check the SigNoz service and logs:

systemctl status signoz.service
journalctl -u signoz.service -n 200 --no-pager

Telemetry does not arrive

Check that the Collector runs and listens on the OTLP ports:

systemctl status signoz-otel-collector.service
sudo ss -ltnp | grep -E ':4317|:4318'

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.

Next Steps

Get Help

If you need help with the steps in this topic, please reach out to us on SigNoz Community Slack. If you are a SigNoz Cloud user, please use in product chat support located at the bottom right corner of your SigNoz instance or contact us at cloud-support@signoz.io.

Install SigNoz on Linux with systemd - Self-Host Guide

Prerequisites

Install SigNoz

Step 1: Install foundryctl

Step 2: Install host dependencies

Step 3: Download SigNoz binaries

Step 4: Create casting.yaml

Step 5: Deploy with Foundry

Step 6: Validate the installation

Step 7: Enable the SigNoz MCP server (optional)

Customize the installation

Troubleshooting

`foundryctl cast` fails

`sudo` cannot find `foundryctl`

ClickHouse cannot connect to Keeper on Ubuntu

A SigNoz service fails after cast

Step 1: Install ClickHouse

Step 2: Install ZooKeeper

Step 3: Run ClickHouse migrations

Step 4: Install SigNoz

Step 5: Install the SigNoz OTel Collector

Step 6: Open the SigNoz UI

Troubleshooting

Migrations fail

SigNoz health check fails

Telemetry does not arrive

Next Steps

Get Help

Was this page helpful?

Is this page helpful?

Install SigNoz on Linux with systemd - Self-Host Guide

Prerequisites

Install SigNoz

Step 1: Install foundryctl

Step 2: Install host dependencies

Step 3: Download SigNoz binaries

Step 4: Create casting.yaml

Step 5: Deploy with Foundry

Step 6: Validate the installation

Step 7: Enable the SigNoz MCP server (optional)

Customize the installation

Troubleshooting

foundryctl cast fails

sudo cannot find foundryctl

ClickHouse cannot connect to Keeper on Ubuntu

A SigNoz service fails after cast

Step 1: Install ClickHouse

Step 2: Install ZooKeeper

Step 3: Run ClickHouse migrations

Step 4: Install SigNoz

Step 5: Install the SigNoz OTel Collector

Step 6: Open the SigNoz UI

Troubleshooting

Migrations fail

SigNoz health check fails

Telemetry does not arrive

Next Steps

Get Help

Was this page helpful?

Is this page helpful?

`foundryctl cast` fails

`sudo` cannot find `foundryctl`