{"id":49034939,"url":"https://github.com/JSONbored/signoz-aio","last_synced_at":"2026-05-05T15:01:13.030Z","repository":{"id":347909695,"uuid":"1195687641","full_name":"JSONbored/signoz-aio","owner":"JSONbored","description":"All-in-one SigNoz for Unraid: a single self-hosted container bundling SigNoz UI/API, OpenTelemetry collector, ClickHouse, and ZooKeeper, with optional built-in local host monitoring for metrics, logs, Docker stats, and OTLP ingestion.","archived":false,"fork":false,"pushed_at":"2026-05-04T12:14:08.000Z","size":310,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T14:18:42.166Z","etag":null,"topics":["aio","clickhouse","containers","devops","docker","homelab","logging","metrics","monitoring","observability","opentelemetry","otlp","prometheus","self-hosted","signoz","telemetry","tracking","unraid","unraid-ca","zookeeper"],"latest_commit_sha":null,"homepage":"https://aethereal.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JSONbored.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/support-thread-template.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"github":["JSONbored"],"ko_fi":"jsonbored"}},"created_at":"2026-03-30T00:51:13.000Z","updated_at":"2026-05-02T09:03:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JSONbored/signoz-aio","commit_stats":null,"previous_names":["jsonbored/signoz-aio"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/JSONbored/signoz-aio","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSONbored%2Fsignoz-aio","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSONbored%2Fsignoz-aio/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSONbored%2Fsignoz-aio/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSONbored%2Fsignoz-aio/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JSONbored","download_url":"https://codeload.github.com/JSONbored/signoz-aio/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JSONbored%2Fsignoz-aio/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32654618,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aio","clickhouse","containers","devops","docker","homelab","logging","metrics","monitoring","observability","opentelemetry","otlp","prometheus","self-hosted","signoz","telemetry","tracking","unraid","unraid-ca","zookeeper"],"created_at":"2026-04-19T11:00:24.245Z","updated_at":"2026-05-05T15:01:13.003Z","avatar_url":"https://github.com/JSONbored.png","language":"Python","funding_links":["https://github.com/sponsors/JSONbored","https://ko-fi.com/jsonbored"],"categories":["In Progress"],"sub_categories":[],"readme":"# SigNoz Unraid Suite\n\n![signoz-aio](https://socialify.git.ci/JSONbored/signoz-aio/image?custom_description=All-in-one+SigNoz+for+Unraid%3A+a+single+self-hosted+container+bundling+SigNoz+UI%2FAPI%2C+OpenTelemetry+collector%2C+ClickHouse%2C+and+ZooKeeper.\u0026custom_language=Dockerfile\u0026description=1\u0026font=Raleway\u0026forks=1\u0026issues=1\u0026language=1\u0026logo=https%3A%2F%2Favatars.githubusercontent.com%2Fu%2F76905799%3Fs%3D200%26v%3D4\u0026name=1\u0026owner=1\u0026pattern=Formal+Invitation\u0026pulls=1\u0026stargazers=1\u0026theme=Light)\n\nThis repo packages two Unraid Community Applications for SigNoz:\n\n- `signoz-aio`: the full self-hosted backend, UI, collector, ClickHouse, and ZooKeeper stack.\n- `signoz-agent`: a lightweight OpenTelemetry Collector companion for remote hosts, stricter separation, and custom edge collection.\n\nBoth templates use the same support surface: [JSONbored/signoz-aio issues](https://github.com/JSONbored/signoz-aio/issues).\n\n## Templates\n\n### signoz-aio\n\n`signoz-aio` packages the full self-hosted SigNoz stack into a single Unraid-friendly image and CA app template.\n\nThe image follows the current official SigNoz Docker deployment instead of inventing a custom rewrite. It supervises the services SigNoz currently expects for a complete small-to-medium self-hosted install:\n\n- `signoz`\n- `signoz-otel-collector`\n- `clickhouse`\n- `zookeeper`\n\n### signoz-agent\n\n`signoz-agent` packages the official OpenTelemetry Collector Contrib collector as a SigNoz-focused Unraid companion app.\n\nUse it when you want to:\n\n- collect telemetry from remote machines and forward it to `signoz-aio`\n- keep host/Docker mounts out of the main SigNoz backend container\n- run advanced collector pipelines without replacing the backend AIO template\n\nThe agent defaults to no host root, Docker socket, or Docker log mounts. Those are advanced opt-in settings only.\n\n## What Is Inside The Image\n\nThe image includes all of the stateful pieces needed for a self-contained SigNoz install:\n\n- `signoz`\n  - the main SigNoz UI and API service\n  - stores application metadata in an internal SQLite database persisted under `/appdata/signoz`\n- `signoz-otel-collector`\n  - receives OTLP data on `4317` and `4318`\n  - runs the telemetry-store migrations SigNoz needs in ClickHouse\n- `clickhouse`\n  - the primary telemetry database for traces, logs, metrics, and derived telemetry tables\n- `zookeeper`\n  - internal coordination layer used by the official SigNoz ClickHouse deployment\n\nThe image does not require any separate Postgres, TimescaleDB, or Redis sidecars. SigNoz's long-term telemetry data lives in ClickHouse, while SigNoz's app/config metadata in this AIO image lives in SQLite.\n\n## Advanced Database Options\n\nThe default install is fully self-contained and uses:\n\n- SQLite for SigNoz metadata\n- bundled ClickHouse for telemetry storage\n- bundled ZooKeeper for ClickHouse coordination\n\nFor power users, the advanced app settings also support:\n\n- external PostgreSQL for SigNoz metadata\n- root user provisioning through official SigNoz environment variables\n- external ClickHouse endpoints for advanced deployments\n\nImportant limitation:\n\n- PostgreSQL can replace SQLite for metadata\n- PostgreSQL does not replace ClickHouse for traces, metrics, and logs\n- if you move to external ClickHouse, you are moving into a more advanced deployment model and should already understand your ClickHouse and ZooKeeper topology\n\n## Architecture\n\n```mermaid\nflowchart LR\n    A[\"Apps / SDKs / Agents\"] --\u003e|\"OTLP gRPC :4317\"| B[\"signoz-otel-collector\"]\n    A --\u003e|\"OTLP HTTP :4318\"| B\n    B --\u003e|\"metrics / logs / traces\"| C[\"ClickHouse\"]\n    D[\"SigNoz UI/API :8080\"] --\u003e|\"query + metadata reads\"| C\n    D --\u003e|\"app metadata\"| E[\"SQLite (/appdata/signoz/signoz.db)\"]\n    C --\u003e|\"cluster coordination\"| F[\"ZooKeeper\"]\n    G[\"/appdata\"] --\u003e C\n    G --\u003e E\n    G --\u003e F\n    G --\u003e H[\"generated.env / runtime config\"]\n```\n\n## Persistence Layout\n\nThe Unraid app intentionally keeps the mount surface simple by using one root path:\n\n- `/appdata`\n\nInside that mount, the container manages:\n\n- `/appdata/clickhouse`\n- `/appdata/signoz`\n- `/appdata/zookeeper`\n- `/appdata/config`\n- `/appdata/tmp`\n\n## Current Status\n\nThe single-image runtime is implemented and validated.\n\n- the image supervises `signoz`, `signoz-otel-collector`, `clickhouse`, and `zookeeper`\n- `linux/amd64` build passes\n- pytest-backed Docker integration testing covers:\n  - first boot\n  - telemetry-store migrations\n  - OTLP listener readiness\n  - restart and persistence\n  - advanced runtime preflight paths\n- `signoz-agent` has a separate image, template, generated collector config, and Docker-backed integration tests for forwarding, Prometheus scraping, and fail-fast security checks\n\n## First-Run Notes\n\n- first startup is heavier than a typical single-service app because ClickHouse, ZooKeeper, SigNoz, and the collector all need to initialize\n- expect more RAM and disk use than lighter AIO images\n- the default setup keeps things intentionally simple:\n  - one `/appdata` root\n  - one UI port\n  - two OTLP ingest ports\n  - sane advanced defaults for the collector and internal ZooKeeper housekeeping\n\n## Getting Data Into SigNoz\n\nSigNoz is only useful once something is sending telemetry into it. This image gives you ready OTLP endpoints, but it does not automatically reach out and scrape your entire server by default.\n\nThe easiest ingestion paths are:\n\n- instrument applications with OpenTelemetry and send directly to:\n  - `http://YOUR-UNRAID-IP:4317` for OTLP gRPC\n  - `http://YOUR-UNRAID-IP:4318` for OTLP HTTP\n- run a separate OpenTelemetry Collector or Alloy agent on the Unraid host\n- run `signoz-agent` on this host or another machine\n- configure that agent to:\n  - scrape Prometheus endpoints\n  - collect Docker container metrics\n  - tail Docker or file-based logs\n  - forward everything into this `signoz-aio` container\n\nWhy keep the host agent separate?\n\n- it avoids giving the main SigNoz container broad access to the Docker socket\n- it avoids mounting host `/proc`, `/sys`, and container log directories into the main UI/database image\n- it keeps the AIO install safe and beginner-friendly while still giving power users a clean upgrade path\n\n## Recommended Monitoring Layout For Unraid\n\n```mermaid\nflowchart LR\n    A[\"Unraid host\"] --\u003e|\"host metrics\"| B[\"Optional built-in host agent\"]\n    C[\"Docker containers\"] --\u003e|\"docker stats + logs\"| B\n    D[\"Apps with OTel SDKs\"] --\u003e|\"direct OTLP or via agent\"| B\n    E[\"Apps with Prometheus endpoints\"] --\u003e|\"optional scrape targets\"| B\n    B --\u003e|\"local OTLP\"| F[\"SigNoz internal collector\"]\n    F --\u003e G[\"SigNoz UI\"]\n    F --\u003e H[\"ClickHouse + SQLite + ZooKeeper\"]\n```\n\nFor most single-host users, this is the sweet spot:\n\n- `signoz-aio` stays the central backend and UI\n- the optional built-in local host agent can handle host collection on the same Unraid machine\n- instrumented apps can either send directly to SigNoz or rely on the local host agent for extra collection\n\nFor remote hosts or stricter separation, run `signoz-agent` and point it at the `signoz-aio` OTLP endpoint.\n\n## Releases\n\n`signoz-aio` uses upstream-version-plus-AIO-revision releases such as `v0.120.0-aio.1`.\n\n`signoz-agent` uses upstream-collector-version-plus-agent-revision releases such as `0.139.0-agent.1`.\n\nEvery `main` build publishes `latest`, the exact pinned upstream version, an explicit packaging line tag, and `sha-\u003ccommit\u003e`.\n\nSee [docs/releases.md](docs/releases.md) for the central release process details.\n\nThe CA templates use the Docker Hub image names:\n\n- `jsonbored/signoz-aio`\n- `jsonbored/signoz-agent`\n\n## Quick Start Paths\n\n### 1. Instrumented apps\n\nIf an app already supports OpenTelemetry, point it at:\n\n- `OTEL_EXPORTER_OTLP_ENDPOINT=http://YOUR-UNRAID-IP:4317`\n  for gRPC exporters\n- `OTEL_EXPORTER_OTLP_ENDPOINT=http://YOUR-UNRAID-IP:4318`\n  for HTTP exporters\n\nThen verify in SigNoz:\n\n- traces appear in APM / Traces\n- application metrics appear in Metrics Explorer\n- application logs appear in Logs if the app also exports logs\n\n### 2. Prometheus scrape targets\n\nIf an app exposes a `/metrics` endpoint, use a host collector to scrape it and forward to SigNoz.\n\nStarter example:\n\n- [Prometheus scrape collector example](docs/examples/otelcol-prometheus-scrape.yaml)\n\n### 3. Unraid host + Docker telemetry\n\nIf you want host metrics, Docker container metrics, and container logs from the same Unraid machine, enable the built-in local host agent in the app settings and explicitly fill only the advanced host/Docker path fields you want to use.\n\nStarter example:\n\n- [Docker / host collector example](docs/examples/otelcol-docker-host-agent.yaml)\n\nThe built-in host agent is auto-generated from the mounts and variables you provide. A default install does not mount the host root, Docker socket, or Docker log directory. When you opt in, it can enable:\n\n- Unraid CPU, memory, disk, and filesystem metrics\n- Docker container resource metrics\n- Docker stdout/stderr logs\n- optional Prometheus scrape targets you define\n\nCommon explicit path values are:\n\n- Host Root Path: `/`\n- Docker Socket: `/var/run/docker.sock`\n- Docker Container Logs Path: `/var/lib/docker/containers`\n\nThis is the best fit for users who want:\n\n- one main AIO install\n- minimal extra setup\n- local Unraid and Docker observability without a second app\n\n## What We Recommend Newcomers Do First\n\n1. Get `signoz-aio` running with defaults.\n2. Verify the UI loads on port `8080`.\n3. Point one app or one collector at OTLP `4317` or `4318`.\n4. Confirm data appears in SigNoz.\n5. Only then expand into Prometheus scraping, host metrics, and container logs.\n\n## What This AIO Does Not Bundle\n\nThis image is self-contained for the SigNoz backend stack, but observability data still has to come from somewhere. It does not automatically collect telemetry from every remote host or every service you run.\n\nThat means you still need to connect senders such as:\n\n- OpenTelemetry SDKs inside apps\n- OpenTelemetry Collector agents\n- Prometheus scrape pipelines\n- log shippers or agent-based host collectors\n\nThe optional built-in local host agent can collect from the same Unraid machine when you explicitly populate the advanced mounts, including the Docker socket. That is useful, but it is also a security tradeoff and it does not replace proper agents for remote systems.\n\n## Docs And Examples\n\n- [Ingestion guide](docs/ingestion-guide.md)\n- [Configuration matrix](docs/configuration-matrix.md)\n- [signoz-agent component README](components/signoz-agent/README.md)\n- [Docker / host collector example](docs/examples/otelcol-docker-host-agent.yaml)\n- [Prometheus scrape collector example](docs/examples/otelcol-prometheus-scrape.yaml)\n\n## Helpful References\n\n- [SigNoz self-host Docker docs](https://signoz.io/docs/install/docker/)\n- [SigNoz Docker Collection Agent overview](https://signoz.io/docs/opentelemetry-collection-agents/docker/overview/)\n- [SigNoz Docker Collection Agent configuration](https://signoz.io/docs/opentelemetry-collection-agents/docker/configure/)\n- [SigNoz Prometheus metrics guide](https://signoz.io/docs/userguide/prometheus-metrics)\n- [SigNoz deployment README](https://github.com/SigNoz/signoz/tree/main/deploy)\n- [SigNoz single-binary consolidation issue](https://github.com/SigNoz/signoz/issues/7309)\n\n## Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=JSONbored/signoz-aio\u0026type=date\u0026legend=top-left)](https://www.star-history.com/#JSONbored/signoz-aio\u0026Date)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJSONbored%2Fsignoz-aio","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJSONbored%2Fsignoz-aio","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJSONbored%2Fsignoz-aio/lists"}