## PREAMBLE

Although this computer program has a permissive license (AP2.0), if you came here looking to ask
questions, you're better off just moving on :) This program is shared AS-IS and really without any
intent for anybody but IPng Networks to use it. Also, in case the structure of the repo and the
style of this README wasn't already clear, this program is 100% written and maintained by Claude
Code.

You have been warned :)

![nginx-logtail frontend](docs/frontend.png)

## What is this?

This project consists of four components:
1. A log **collector** that tails NGINX (or Apache) logs and/or receives logs over UDP from
   [`nginx-ipng-stats-plugin`](https://git.ipng.ch/ipng/nginx-ipng-stats-plugin), aggregating
   counts per website, client address, URI, status, ASN, and source tag. It buckets these into
   windows of 1m, 5m, 15m, 60m, 6h, and 24h and exposes them over gRPC.
1. An **aggregator** that subscribes to any number of collectors and serves a merged view on
   the same gRPC surface.
1. An HTTP **frontend** that renders a drilldown dashboard (zero JavaScript, server-side SVG
   sparklines) against any collector or the aggregator.
1. A **CLI** for shell queries, returning tables or JSON.

Written in Go, released under [[APACHE](LICENSE)]. Runs as `systemd` units, in Docker, or any
combination.

## Quick Start

Three deployment flavors. Pick whichever suits the host.

**Debian package.** Build once, install the `.deb` on every nginx host (for the collector) and
on one central host (for the aggregator + frontend):

```bash
make install-deps          # one-time: apt deps, Go toolchain, go tools
make pkg-deb               # produces nginx-logtail_<ver>_{amd64,arm64}.deb

# on each nginx host:
sudo dpkg -i nginx-logtail_*_amd64.deb
sudo $EDITOR /etc/default/nginx-logtail   # defaults to UDP-only on :9514; set COLLECTOR_LOGS=... to also tail files
sudo systemctl enable --now nginx-logtail-collector.service

# on the central host:
sudo dpkg -i nginx-logtail_*_amd64.deb
sudo systemctl enable --now nginx-logtail-aggregator.service nginx-logtail-frontend.service
# dashboard now at http://<central>:8080
```

Binaries land at `/usr/sbin/nginx-logtail-{collector,aggregator,frontend}` and the CLI at
`/usr/bin/nginx-logtail`. All three services run as the `_logtail` system user (collector uses
`Group=www-data` for log access). None are auto-enabled, so installing the package is safe on
any host.

**Docker Compose.** Runs the aggregator and frontend in one stack; point collectors (on each
nginx host) at the aggregator:

```bash
AGGREGATOR_COLLECTORS=nginx1:9090,nginx2:9090 docker compose up -d
# frontend on :8080, aggregator gRPC on :9091
```

**From source (`make`).**

```bash
make build                 # build/<arch>/{collector,aggregator,frontend,cli}
make test
./build/*/nginx-logtail -version
```

`make help` lists every target.

See [[User Guide](docs/user-guide.md)] for operator-facing documentation, or
[[Design](docs/design.md)] for the normative requirements and architectural rationale.