Skip to content
Klutch.sh Docs

Deploying a SigNoz App

Introduction

SigNoz is an open-source observability platform for traces, metrics, and logs. Deploying SigNoz with a Dockerfile on Klutch.sh provides reproducible builds, managed secrets, and persistent storage—all configured from klutch.sh/app. This guide focuses on a single-node backend and UI reachable over HTTP.

Prerequisites

  • A Klutch.sh account (sign up)
  • A GitHub repository containing your SigNoz Dockerfile (GitHub is the only supported git source)
  • External ClickHouse cluster/instance (required for SigNoz data)
  • Optional: external object storage for long-term log retention

For onboarding, see the Quick Start.

Architecture and ports

  • SigNoz UI/API listens on internal port 3301. Choose HTTP traffic and set the internal port to 3301.
  • Persistent storage is required for UI/query metadata; traces/metrics/logs live in ClickHouse.

Repository layout

signoz/
├── Dockerfile              # Must be at repo root for auto-detection
└── README.md

Keep secrets out of Git; store them in Klutch.sh environment variables.

Installation (local) and starter commands

Build and run locally (ensure ClickHouse is reachable):

Terminal window
docker build -t signoz-local .
docker run -p 3301:3301 \
  -e CLICKHOUSE_ADDRESS=clickhouse://localhost:9000 \
  -e CLICKHOUSE_USER=default \
  -e CLICKHOUSE_PASSWORD= \
  -e CLICKHOUSE_DATABASE=signoz \
  signoz-local

Dockerfile for SigNoz (production-ready)

Place this at the repo root; Klutch.sh auto-detects Dockerfiles.

FROM signoz/signoz:latest


ENV LISTEN_PORT=3301


EXPOSE 3301
CMD ["./signoz"]

Notes:

  • Pin to a specific tag (e.g., signoz/signoz:0.36.0) for stability.
  • The image expects a ClickHouse backend via environment variables.

Environment variables (Klutch.sh)

Configure these before deploying:

  • PORT=3301
  • LISTEN_PORT=3301
  • CLICKHOUSE_ADDRESS=clickhouse://<host>:9000
  • CLICKHOUSE_USER=<user>
  • CLICKHOUSE_PASSWORD=<password>
  • CLICKHOUSE_DATABASE=signoz
  • Optional: storage/retention tuning variables supported by your SigNoz version

If deploying without the Dockerfile and relying on Nixpacks:

  • NIXPACKS_START_CMD=./signoz

Attach persistent volumes

Add storage in Klutch.sh (path and size only):

  • /var/lib/signoz — UI/query metadata and local cache.

Ensure the path is writable inside the container.

Deploy SigNoz on Klutch.sh (Dockerfile workflow)

  1. Push your repository—with the Dockerfile at the root—to GitHub.
  2. Open klutch.sh/app, create a project, and add an app.
  3. Select HTTP traffic and set the internal port to 3301.
  4. Add the environment variables above (ClickHouse endpoint, credentials, database).
  5. Attach a volume at /var/lib/signoz sized for metadata/cache.
  6. Deploy. Access the UI at https://example-app.klutch.sh and configure ingest endpoints for your services.

Sample checks

UI reachability:

Terminal window
curl -I https://example-app.klutch.sh

If a health endpoint is available (replace if different):

Terminal window
curl -I https://example-app.klutch.sh/health

Health checks and production tips

  • Add an HTTP readiness probe to / or your health endpoint.
  • Keep ClickHouse credentials in Klutch.sh secrets; rotate regularly.
  • Pin image versions and test config changes in staging before production rollout.
  • Monitor volume usage on /var/lib/signoz and ClickHouse storage; resize proactively.

SigNoz on Klutch.sh delivers reproducible Docker builds, managed secrets, and persistent metadata—without extra YAML or CI steps. Configure ports, ClickHouse access, and storage, then start collecting telemetry.