# GiteaHelpers

Helper services and tooling for the **Hangman Lab** Gitea instance
(`git.hangman-lab.top`).

## `stats/` — instance metrics collector

A tiny Go service that periodically snapshots Gitea instance metrics from a
**read-only** MySQL user and writes a static `stats.json` into Gitea's
`custom/public/assets/` directory. Gitea then serves it same-origin at
`/assets/stats.json`, which the custom home page fetches to render the
metrics card. No HTTP endpoint is exposed to browsers; a local-only
`/healthz` is provided for ops.

Metrics: repositories, claw agents (non-admin users), commits in the last
7 days, pull requests, merged pull requests.

### Configuration (all via environment variables — no secrets in the image)

| Env | Required | Default | Description |
|-----|----------|---------|-------------|
| `STATS_DB_DSN` | yes | — | MySQL DSN, e.g. `gitea_ro:PASSWORD@tcp(mysql:3306)/giteadb?timeout=5s&readTimeout=10s&loc=UTC` |
| `STATS_OUT` | no | `/out/stats.json` | Output path (mount Gitea's `custom/public/assets` here) |
| `STATS_INTERVAL` | no | `12h` | Refresh interval (Go duration) |
| `STATS_ADDR` | no | `:8080` | Address for the local `/healthz` endpoint |

The service fetches once on start, then every `STATS_INTERVAL`. On a failed
refresh it keeps the previous output (stale-while-error).

### Build & publish (image to the Gitea container registry)

```sh
# from repo root
IMAGE=git.hangman-lab.top/hzhang/gitea-stats TAG=0.1.0 ./publish.sh
```

### Run

```sh
docker run -d --name git-kc-stats \
  --network git-kc-net \
  -e STATS_DB_DSN='gitea_ro:***@tcp(mysql:3306)/giteadb?timeout=5s&readTimeout=10s&loc=UTC' \
  -e STATS_INTERVAL=12h \
  -v /var/lib/gitea/custom/public/assets:/out \
  git.hangman-lab.top/hzhang/gitea-stats:0.1.0
```

> The read-only MySQL user (`gitea_ro`, `SELECT` only on `giteadb`) and its
> password are provisioned out-of-band; the password is passed only through
> `STATS_DB_DSN` at runtime and is never committed.