PRE-RELEASE 0.9.1: Makefile, Debian packaging, versioned UDP

Build and release tooling:
- Makefile with help as default; targets: build/build-amd64/build-arm64,
  test, lint, proto, pkg-deb, docker, docker-push, clean, plus
  install-deps (+ three sub-targets for apt / Go toolchain / Go tools).
- internal/version package; -ldflags -X injects Version/Commit/Date into
  every binary. -version flag on all four binaries (nginx-logtail version
  for the CLI).
- Dockerfile takes VERSION/COMMIT/DATE build-args and forwards them.
- .deb output lands in build/; .gitignore ignores /build/.

Debian package:
- debian/build-deb.sh packages all four static binaries into a single
  nginx-logtail_<ver>_<arch>.deb using dpkg-deb.
- Binary layout: /usr/sbin/nginx-logtail-{collector,aggregator,frontend}
  and /usr/bin/nginx-logtail.
- nginx-logtail(8) manpage.
- Three systemd units (collector, aggregator, frontend) shipped under
  /lib/systemd/system/. Installed but never enabled or started — the
  operator opts in per host.
- Collector runs as _logtail:www-data (log access); aggregator and
  frontend as _logtail:_logtail. postinst creates the system user/group
  idempotently.
- Single shared env file /etc/default/nginx-logtail rendered from a
  template at first install with %HOSTNAME% substituted. Sensible
  defaults for every COLLECTOR_*, AGGREGATOR_*, FRONTEND_* variable;
  plus COLLECTOR_ARGS / AGGREGATOR_ARGS / FRONTEND_ARGS escape hatches
  appended to ExecStart. Not a dpkg conffile: operator edits survive
  upgrades and dpkg --purge removes it.

Versioned UDP wire format:
- ParseUDPLine dispatches on a leading "v<N>\t" tag; v1 routes to the
  existing 12-field parser. Unknown/missing versions fail closed so
  future v2 parsers can land before emitters are upgraded.
- Tests updated; design.md FR-2.2 rewritten to make the version tag
  normative.

Docs:
- README.md gains a Quick Start (Debian / Docker Compose / from source).
- user-guide.md rewritten around Installation and Configuration: full
  env-var table, UDP-only default explained, precise file/UDP log_format
  layouts, note that operators can emit "0" for unknown \$is_tor / \$asn.
- Drilldown cycle, frontend filter table, and CLI --group-by list all
  include source_tag. UDP counters documented in the Prometheus section.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

debian/build-deb.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# Build a minimal .deb for nginx-logtail containing the four static binaries.
+# Expects `make build-<arch>` to have already populated build/<arch>/.
+#
+# Usage: debian/build-deb.sh <arch> <version>
+#   arch:    amd64 | arm64
+#   version: e.g. 0.9.1
+
+set -euo pipefail
+
+if [ "$#" -ne 2 ]; then
+    echo "usage: $0 <arch> <version>" >&2
+    exit 1
+fi
+
+ARCH="$1"
+VERSION="$2"
+PKG="nginx-logtail"
+STAGE="$(mktemp -d)"
+chmod 0755 "$STAGE"
+
+# Output into build/ alongside the per-arch binary trees so `make clean`
+# wipes everything in one rm and .gitignore only needs to ignore build/.
+OUT_DIR="build"
+mkdir -p "${OUT_DIR}"
+OUT="${OUT_DIR}/${PKG}_${VERSION}_${ARCH}.deb"
+
+trap 'rm -rf "$STAGE"' EXIT
+
+BUILD_DIR="build/${ARCH}"
+for b in collector aggregator frontend cli; do
+    if [ ! -x "${BUILD_DIR}/${b}" ]; then
+        echo "error: ${BUILD_DIR}/${b} not found — run 'make build-${ARCH}' first" >&2
+        exit 1
+    fi
+done
+
+install -d -m 0755 \
+    "${STAGE}/DEBIAN" \
+    "${STAGE}/usr/sbin" \
+    "${STAGE}/usr/bin" \
+    "${STAGE}/usr/share/doc/${PKG}" \
+    "${STAGE}/usr/share/man/man8" \
+    "${STAGE}/usr/share/${PKG}" \
+    "${STAGE}/lib/systemd/system"
+
+install -m 0755 "${BUILD_DIR}/collector"  "${STAGE}/usr/sbin/nginx-logtail-collector"
+install -m 0755 "${BUILD_DIR}/aggregator" "${STAGE}/usr/sbin/nginx-logtail-aggregator"
+install -m 0755 "${BUILD_DIR}/frontend"   "${STAGE}/usr/sbin/nginx-logtail-frontend"
+install -m 0755 "${BUILD_DIR}/cli"        "${STAGE}/usr/bin/nginx-logtail"
+
+install -m 0644 LICENSE                   "${STAGE}/usr/share/doc/${PKG}/copyright"
+install -m 0644 README.md                 "${STAGE}/usr/share/doc/${PKG}/README.md"
+
+# Manpage: gzip per Debian policy (lintian only checks for .gz).
+gzip -n -9 -c debian/nginx-logtail.8 > "${STAGE}/usr/share/man/man8/nginx-logtail.8.gz"
+chmod 0644 "${STAGE}/usr/share/man/man8/nginx-logtail.8.gz"
+
+# systemd units. Installed, not enabled or started — operator opts in.
+install -m 0644 debian/nginx-logtail-collector.service  "${STAGE}/lib/systemd/system/"
+install -m 0644 debian/nginx-logtail-aggregator.service "${STAGE}/lib/systemd/system/"
+install -m 0644 debian/nginx-logtail-frontend.service   "${STAGE}/lib/systemd/system/"
+
+# Defaults template. postinst renders this to /etc/default/nginx-logtail on
+# first install with %HOSTNAME% substituted. Not a dpkg conffile — operator
+# edits survive upgrades because postinst only writes when the file is absent.
+install -m 0644 debian/default.template "${STAGE}/usr/share/${PKG}/default.template"
+
+# Maintainer scripts: postinst creates _logtail user and renders defaults;
+# prerm stops running services; postrm reloads systemd and removes the
+# generated defaults file on purge.
+install -m 0755 debian/postinst "${STAGE}/DEBIAN/postinst"
+install -m 0755 debian/postrm   "${STAGE}/DEBIAN/postrm"
+install -m 0755 debian/prerm    "${STAGE}/DEBIAN/prerm"
+
+cat > "${STAGE}/DEBIAN/control" <<EOF
+Package: ${PKG}
+Version: ${VERSION}
+Section: net
+Priority: optional
+Architecture: ${ARCH}
+Maintainer: Pim van Pelt <pim@ipng.ch>
+Homepage: https://git.ipng.ch/ipng/nginx-logtail
+Description: Real-time top-K traffic analysis for nginx clusters
+ nginx-logtail is a four-binary Go system that ingests nginx access
+ logs (from files or UDP) and answers ranked top-K queries over
+ configurable time windows. See /usr/share/doc/nginx-logtail/README.md.
+EOF
+
+dpkg-deb --build --root-owner-group "${STAGE}" "${OUT}"
+echo "built ${OUT}"