# Installation

Insights is distributed as a single binary with no external dependencies beyond a NATS server to monitor, and as container images and a Helm chart. You can also use the built-in simulator to explore Insights without any existing NATS infrastructure. A trial runs a separate build; see [Trial](/insights/1.2/trial.md).

## Upgrading

Moving an existing 0.1.10 deployment to 1.2.2? Read [Upgrading to v1.2](/insights/1.2/release-notes/v1.2.0-upgrade.md) before you install.

## Prerequisites

* A running NATS Server 2.10.27 or later with system account access (for monitoring real deployments), **or** use the built-in simulator for evaluation and development

## System requirements

Insights ships as a single, fully static binary. The Linux builds bundle everything they need, including the embedded database engine, and link no system libraries at runtime, so there is no minimum glibc version and no dependency on the host's C library. The same binary runs unchanged across distributions.

**Platforms:** Linux (`amd64`, `arm64`), macOS (`amd64`, `arm64`), and Windows (`amd64`).

**Linux:**

* **Kernel** 3.2 or newer, which any distribution released in roughly the last decade meets.
* **CPU** any 64-bit x86 or ARM processor (ARMv8-A for `arm64`). No special instruction-set extensions such as AVX are required.
* **C library** none. Because the binary is fully static it runs on glibc distributions (Debian, Ubuntu, RHEL, Amazon Linux, SUSE, …), on musl distributions (Alpine), and in minimal or `scratch`/distroless images with no libc at all.

On a **minimal or `scratch` container image**, the binary runs, but the base provides no ambient files it would otherwise read from the host. Add these if your deployment needs them:

* **CA certificates** (e.g. `/etc/ssl/certs/ca-certificates.crt`): required for outbound TLS, such as a TLS-secured NATS server or webhook endpoint.
* **Time zone data** (`/usr/share/zoneinfo`): required only if you configure a non-UTC time zone; UTC always works.

DNS resolution uses `/etc/resolv.conf` and `/etc/hosts`, which are present on any normal base image. Insights uses its own resolver rather than the system one, so multicast DNS (`.local`) names don't resolve: refer to NATS servers by IP address or DNS name. The official Linux images are built on `gcr.io/distroless/static-debian13`, which includes CA certificates and time zone data, so TLS works out of the box. They contain no shell: to inspect a running container, attach a debug container (for example with `kubectl debug`) rather than `exec` into it.

## Download

Release archives are distributed from `artifacts.synadia.io`, using the credentials Synadia issues to you. Each release has one archive per platform, named for the product version:

| Archive                                        | Contains                                                                                                                                                 |
| ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insights-v1.2.2-<os>-<arch>.tar.gz`           | The full `insights` binary                                                                                                                               |
| `insights-collector-v1.2.2-<os>-<arch>.tar.gz` | The DuckDB-free `insights-collector` binary, needed only for a [federated deployment](/insights/1.2/guides/federated-deployment.md) that uses collectors |

`<os>` is `linux`, `darwin`, or `windows`, and `<arch>` is `amd64` or `arm64` (Windows is `amd64` only, packaged as `.zip`). Trial builds are not downloaded from here; see [Trial](/insights/1.2/trial.md#what-the-trial-includes).

Download an archive with those credentials; each release lives under `insights/v<version>/`:

```
curl -fLO -u <user>:<password> \

  https://artifacts.synadia.io/insights/v1.2.2/insights-v1.2.2-linux-amd64.tar.gz
```

Each archive extracts to a directory of the same name:

```
# Example: Linux amd64

tar -xzf insights-v1.2.2-linux-amd64.tar.gz

cd insights-v1.2.2-linux-amd64

./insights --version
```

`--version` prints the product version, `1.2.2`.

The collector binary carries only the `serve` (its default), `config`, `system list`, `node list`, and `ops pprof` commands. It connects to an external NATS server for its stream and needs a full Insights node elsewhere to index and serve what it collects.

## Docker

Images are published to `registry.synadia.io`, which requires the registry credentials Synadia issues to you:

```
docker login registry.synadia.io
```

| Image                                          | Contains                                                       |
| ---------------------------------------------- | -------------------------------------------------------------- |
| `registry.synadia.io/insights:1.2.2`           | The `insights` binary (`linux/amd64`, `linux/arm64`)           |
| `registry.synadia.io/insights:1.2.2-collector` | The `insights-collector` binary (`linux/amd64`, `linux/arm64`) |
| `registry.synadia.io/insights:1.2.2-windows`   | The `insights` binary for Windows (`amd64`)                    |

The Linux images run as UID and GID 1000, with the binary as the entrypoint and `/` as the working directory.

Run Insights in a container with the simulator enabled:

```
docker run -p 8080:8080 registry.synadia.io/insights:1.2.2 --simulator --web.hostname 0.0.0.0
```

Or monitor a real NATS deployment, keeping data across container restarts in a named volume:

```
docker run -p 8080:8080 \

  -v insights-data:/var/lib/insights \

  -v /path/to/sys.creds:/etc/insights/sys.creds:ro \

  registry.synadia.io/insights:1.2.2 \

  --sys.server nats://your-nats:4222 \

  --sys.creds /etc/insights/sys.creds \

  --data-dir /var/lib/insights \

  --web.hostname 0.0.0.0
```

Mount the data volume at `/var/lib/insights`. The image creates that directory owned by UID 1000, so a new named volume there inherits the ownership. A named volume mounted at any other path starts out owned by root, and a bind mount or a volume populated by an earlier root-owned image keeps whatever ownership it has; Insights exits with `permission denied` on any of them that UID 1000 cannot write. Give such a directory to that UID before starting the container:

```
chown -R 1000:1000 /path/to/insights-data
```

The collector image needs no data volume. Mount a directory holding the [collector config](/insights/1.2/guides/federated-deployment.md#collector-config) and the credentials files it names, and point the collector at the config:

```
docker run -v /path/to/collector:/etc/insights:ro \

  registry.synadia.io/insights:1.2.2-collector \

  -c /etc/insights/collector.yaml
```

## Kubernetes with Helm

Synadia's public Helm repository includes a minimal chart for a single persistent Insights instance. Application settings live below `config` and are written directly to the mounted `config.yaml`.

The chart pulls from `registry.synadia.io`, so create a pull secret from your registry credentials first:

```
kubectl create secret docker-registry synadia-registry \

  --docker-server registry.synadia.io \

  --docker-username <username> \

  --docker-password <password>
```

```
helm repo add synadia https://synadia-io.github.io/helm-charts

helm repo update synadia

helm upgrade --install insights synadia/insights \

  --set image.tag=1.2.2 \

  --set config.simulator.enabled=true \

  --set image.pullSecrets[0].name=synadia-registry

kubectl port-forward service/insights 8080:8080
```

The `--set config.simulator.enabled` is required, not decoration. When the chart builds the config it refuses to render unless that config observes a system, so one of `config.simulator.enabled`, `config.sys`, or `config.systems` must be set. To monitor a real system, replace the simulator with `config.sys`.

The chart deploys `registry.synadia.io/insights`. The image tag defaults to the chart's `appVersion`, so set `image.tag` to pin the Insights version, as the command above does, and `image.registry` for a mirror.

The pod runs as UID and GID 1000 with a matching `fsGroup`, so the persistent volume is writable without extra configuration. See the [chart README](https://github.com/synadia-io/helm-charts/tree/main/charts/insights) for credentials, external Secrets, and persistence.

## Next steps

* [Quick Start](/insights/1.2/getting-started/quickstart.md): run Insights with the built-in simulator
* [Deployment Guide](/insights/1.2/guides/deployment.md): production deployment options and configuration
