Merge develop — Release v0.7.5: per-IP rate limiting

Author: hrodrig

.env.example

@@ -64,3 +64,10 @@ GGHSTATS_ENABLED_LOCALES=en,es,de,fr,pt-br
 # Spanish-first example:
 # GGHSTATS_DEFAULT_LOCALE=es
 # GGHSTATS_ENABLED_LOCALES=en,es,de
+
+# --- Rate limiting (enabled by default) ---
+# GGHSTATS_RATE_LIMIT_ENABLED=true
+# GGHSTATS_RATE_LIMIT_REQUESTS=120
+# GGHSTATS_RATE_LIMIT_PERIOD=1m
+# GGHSTATS_RATE_LIMIT_BURST=20
+

.gitignore

@@ -27,6 +27,10 @@
 !go.mod
 !go.sum
 
+# Install script (curl | sh from GitHub raw)
+!scripts/
+!scripts/**
+
 # Allowlist: source trees
 !cmd/
 !cmd/**

CHANGELOG.md

@@ -5,7 +5,16 @@ All notable changes to this project are documented in this file.
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.7.5] - 2026-06-14
+
+### Added
+
+- **`scripts/install.sh`:** one-liner install from GitHub releases (`curl -fsSL https://raw.githubusercontent.com/hrodrig/gghstats/main/scripts/install.sh | sh`).
+- **Per-IP rate limiting:** protects the HTTP server from abuse with a configurable token-bucket middleware. Enabled by default (120 req/min, burst 20). Skipped for `/metrics` and `/api/v1/healthz`. Configure via `GGHSTATS_RATE_LIMIT_*` env vars; set `GGHSTATS_RATE_LIMIT_ENABLED=false` to disable.
+
+### Security
+
+- Rate limiting mitigates M7 from the professionalism audit (no protection on `POST /api/v1/sync`).
 
 ## [0.7.4] - 2026-06-10
 

Dockerfile

@@ -21,7 +21,7 @@ RUN go build -ldflags "-s -w \
     -o gghstats ./cmd/gghstats
 
 # Alpine 3.22+: fresher busybox/ca-certificates vs Grype noise on 3.21; apk upgrade pulls security revisions.
-FROM alpine:3.22
+FROM alpine:3.24
 RUN apk update \
     && apk add --no-cache ca-certificates \
     && apk upgrade --no-cache \

README.md

@@ -118,11 +118,13 @@ Tap: [homebrew-gghstats](https://github.com/hrodrig/homebrew-gghstats). The cask
 ### Local binary (fastest try)
 
 ```bash
-# From Releases: extract gghstats_*_linux_* archive, or: go install github.com/hrodrig/gghstats/cmd/gghstats@latest
+curl -fsSL https://raw.githubusercontent.com/hrodrig/gghstats/main/scripts/install.sh | sh
 export GGHSTATS_GITHUB_TOKEN=ghp_xxx
 gghstats run --open
 ```
 
+Or extract a [Release](https://github.com/hrodrig/gghstats/releases) tarball, or `go install github.com/hrodrig/gghstats/cmd/gghstats@latest`. Pin a version: `VERSION=v0.7.4 curl -fsSL …/install.sh | sh`.
+
 Open <http://localhost:8080> if you did not use **`--open`**. Data is stored in `./data/gghstats.db` (override with `GGHSTATS_DB`). A first sync may take a while if the default filter includes many repositories — narrow `GGHSTATS_FILTER` in [Configuration](#configuration) when you move beyond this smoke test.
 
 ### Docker (one command, no clone — UI smoke test)
@@ -159,6 +161,14 @@ Open <http://localhost:8080>. The template [`.env.example`](.env.example) docume
 
 **Quick install** — get the binary on your machine. **Configuration on a server, systemd, `.deb`/`.rpm` setup, Compose, Traefik, Helm, env files, and VPS deployment** are documented only in **[gghstats-selfhosted](https://github.com/hrodrig/gghstats-selfhosted)** ([`run/`](https://github.com/hrodrig/gghstats-selfhosted/tree/main/run), [`run/standalone/linux/`](https://github.com/hrodrig/gghstats-selfhosted/blob/main/run/standalone/linux/README.md) for Linux packages and systemd).
 
+**One-liner (Linux, macOS, BSD — no Docker):**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/hrodrig/gghstats/main/scripts/install.sh | sh
+```
+
+Downloads the latest [release](https://github.com/hrodrig/gghstats/releases) archive for your OS/arch into `/usr/local/bin` (override with `BINDIR=~/bin`). Review [`scripts/install.sh`](scripts/install.sh) before piping to `sh`; pin with `VERSION=v0.7.4`.
+
 **From source (recommended for developers):**
 
 ```bash
@@ -361,6 +371,10 @@ Copy [`.env.example`](.env.example) → `.env` in this repository when running `
 | `GGHSTATS_CUSTOM_CSS` | (none) | Optional **regular** `.css` file: loaded **after** built-in `app.css` at `/theme/custom.css` so you can tone down neo-brutalism or replace accents (see [Custom UI theme](#custom-ui-theme-optional)) |
 | `GGHSTATS_DEFAULT_LOCALE` | `en` | Default **dashboard** language when no cookie, `?lang=`, or `Accept-Language` match (see [Web UI languages](#web-ui-languages-i18n)) |
 | `GGHSTATS_ENABLED_LOCALES` | `en,es,de` | Comma-separated locales shown in the sidebar selector and accepted from `?lang=` / cookie |
+| `GGHSTATS_RATE_LIMIT_ENABLED` | `true` | Set to `false` to disable per-IP rate limiting |
+| `GGHSTATS_RATE_LIMIT_REQUESTS` | `120` | Requests per time window before limiting (per IP) |
+| `GGHSTATS_RATE_LIMIT_PERIOD` | `1m` | Time window for rate limiting (Go duration, e.g. `30s`, `5m`) |
+| `GGHSTATS_RATE_LIMIT_BURST` | `20` | Maximum burst of requests allowed before smoothing kicks in |
 
 ### Web UI languages (i18n)
 

VERSION

@@ -1 +1 @@
-0.7.4
+0.7.5

cmd/gghstats/serve.go

@@ -127,6 +127,11 @@ func runServe(args []string) error {
 		gh.SetMetrics(domainMetrics)
 	}
 
+	rateLimiter := setupRateLimiter()
+	if rateLimiter != nil {
+		defer rateLimiter.Shutdown()
+	}
+
 	syncOpts := sync.Options{
 		IncludePrivate: cfg.IncludePrivate,
 		Filter:         cfg.Filter,
@@ -142,11 +147,7 @@ func runServe(args []string) error {
 	defer cancel()
 	go startScheduler(ctx, coord, cfg.SyncInterval, cfg.SyncOnStartup)
 
-	cssAbs, cssQuery := server.ResolveCustomCSS(os.Getenv("GGHSTATS_CUSTOM_CSS"))
-	if strings.TrimSpace(os.Getenv("GGHSTATS_CUSTOM_CSS")) != "" && cssAbs == "" {
-		slog.Warn("GGHSTATS_CUSTOM_CSS ignored: path is missing or not a regular file",
-			"GGHSTATS_CUSTOM_CSS", os.Getenv("GGHSTATS_CUSTOM_CSS"))
-	}
+	cssAbs, cssQuery := resolveCSSPath()
 
 	// Start HTTP server
 	handler := server.New(server.Config{
@@ -163,6 +164,7 @@ func runServe(args []string) error {
 		CustomCSSQuery:   cssQuery,
 		DefaultLocale:    i18n.EnvDefaultLocale(),
 		EnabledLocales:   i18n.EnvEnabledLocales(),
+		RateLimiter:      rateLimiter,
 	})
 
 	addr := cfg.Host + ":" + cfg.Port
@@ -238,3 +240,26 @@ func startScheduler(ctx context.Context, coord *sync.Coordinator, interval time.
 		}
 	}
 }
+
+func resolveCSSPath() (cssAbs, cssQuery string) {
+	cssAbs, cssQuery = server.ResolveCustomCSS(os.Getenv("GGHSTATS_CUSTOM_CSS"))
+	if strings.TrimSpace(os.Getenv("GGHSTATS_CUSTOM_CSS")) != "" && cssAbs == "" {
+		slog.Warn("GGHSTATS_CUSTOM_CSS ignored: path is missing or not a regular file",
+			"GGHSTATS_CUSTOM_CSS", os.Getenv("GGHSTATS_CUSTOM_CSS"))
+	}
+	return
+}
+
+func setupRateLimiter() *server.RateLimiter {
+	rlCfg := server.ParseRateLimitEnv()
+	if !rlCfg.Enabled {
+		return nil
+	}
+	rl := server.NewRateLimiter(rlCfg)
+	slog.Info("rate limiter enabled",
+		"requests", rlCfg.Requests,
+		"period", rlCfg.Period,
+		"burst", rlCfg.Burst,
+	)
+	return rl
+}

contrib/freebsd/Makefile

@@ -1,5 +1,5 @@
 PORTNAME=	gghstats
-PORTVERSION=	0.7.4
+PORTVERSION=	0.7.5
 DISTVERSIONPREFIX=	v
 CATEGORIES=	sysutils
 # Local test before release: copy the tarball into DISTDIR (see `make -V DISTDIR`

contrib/gghstats.env.example

@@ -39,3 +39,9 @@ GGHSTATS_DEFAULT_LOCALE=en
 GGHSTATS_ENABLED_LOCALES=en,es,de,fr,pt-br
 
 # GGHSTATS_LOG_LEVEL=info
+
+# Rate limiting (enabled by default; set to false to disable)
+# GGHSTATS_RATE_LIMIT_ENABLED=true
+# GGHSTATS_RATE_LIMIT_REQUESTS=120
+# GGHSTATS_RATE_LIMIT_PERIOD=1m
+# GGHSTATS_RATE_LIMIT_BURST=20

contrib/man/man1/gghstats.1

@@ -1,5 +1,5 @@
 .\" Man page for gghstats(1)
-.TH GGHSTATS 1 "June 2026" "gghstats v0.7.4" "User Commands"
+.TH GGHSTATS 1 "June 2026" "gghstats v0.7.5" "User Commands"
 .SH NAME
 gghstats \- self-hosted GitHub repository traffic dashboard and CLI
 .SH SYNOPSIS
@@ -104,6 +104,18 @@ Allow public badge SVG URLs (default: \fBtrue\fR).
 .TP
 .B GGHSTATS_METRICS
 Set to \fBfalse\fR to disable Prometheus \fB/metrics\fR.
+.TP
+.B GGHSTATS_RATE_LIMIT_ENABLED
+Set to \fBfalse\fR to disable per-IP rate limiting (default: \fBtrue\fR).
+.TP
+.B GGHSTATS_RATE_LIMIT_REQUESTS
+Requests per time window before limiting per IP (default: \fB120\fR).
+.TP
+.B GGHSTATS_RATE_LIMIT_PERIOD
+Time window for rate limiting as a Go duration (default: \fB1m\fR).
+.TP
+.B GGHSTATS_RATE_LIMIT_BURST
+Maximum burst of requests before smoothing (default: \fB20\fR).
 .SH EXAMPLES
 .TP
 Run the dashboard locally: