So you want traffic stats for your `~/public_html` site, This stats system generates a **sanitized** report per user from the server’s nginx logs, then lets you publish it *only if you choose to*.
* Optionally: a nice HTML dashboard generated by `goaccess`
No raw IPs are shown in the report.
## Opt-in (required)
Nothing is generated for you unless you opt in.
Create the opt-in flag:
```sh
mkdir -p ~/.config/tilde-stats
touch ~/.config/tilde-stats/enabled
```
That’s it. The nightly job will include you from then on.
## Where the files are written
Reports are generated into:
*`~/.local/share/tilde-stats/index.html`
*`~/.local/share/tilde-stats/stats.json`
These files are **not automatically public**.
## Publishing the report on your website
There are two ways to publish the report:
* **Copy (recommended)**: keeps `~/.local` private and uses normal web permissions.
* **Symlink (works, but requires permissions)**: points your website at `~/.local/...`, which means nginx must be able to traverse those dot-directories.
*`711` is better than `755` for dot-directories since it allows traversal but not directory listing.
* If the generator writes the files with private permissions, you may need to re-apply the `chmod 644` on the two report files after regeneration if you are serving them directly from `~/.local`.
## Updating / regenerating
Stats are generated by an admin-run job (typically nightly). You don’t need to run anything manually.
If you publish via **copy**, re-run the copy commands after the nightly update to refresh the public version.
If you publish via **symlink**, the page updates automatically (as long as permissions allow nginx to read it).
## Disabling / opting out
Remove the opt-in flag:
```sh
rm -f ~/.config/tilde-stats/enabled
```
No new reports will be generated for you after that.
(Any old published copies or symlinks you created are your responsibility to delete.)
## Troubleshooting
### “My stats page 403s / 404s”
* Confirm the public files exist:
```sh
ls -l ~/public_html/stats/
```
* Confirm permissions all the way down the path:
```sh
namei -l ~/public_html/stats/index.html
```
If you’re using symlinks into `~/.local`, also check the target path:
```sh
namei -l ~/.local/share/tilde-stats/index.html
```
Every directory in that output should have `x` for others (traversable), and the file should have `r` for others.
### “The report exists in ~/.local/share but isn’t public”
That’s expected. It’s private until you copy or link it into `~/public_html`.
### “My report is empty”
Either:
* No traffic in the selected window, or
* You opted in recently and the next scheduled run hasn’t happened yet.
