mirror of
https://github.com/tildeclub/site.git
synced 2026-08-25 19:59:24 +00:00
49bcc06b56
Software words and website words are capitalized (or, as another option, all caps), articles in the "tilde.club" category must have most words capitalized (may capitalize word in case of doubt), and the rest of the titles must have first word, of the title, capitalized, with the rest of the (non-software) words, of the title, all lowercase. Signed-off-by: keyboardan <keyboardan@tilde.club>
178 lines
5.0 KiB
Markdown
178 lines
5.0 KiB
Markdown
---
|
||
title: Userdir traffic stats (tilde.club)
|
||
category: software
|
||
Author: deepend
|
||
---
|
||
|
||
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*.
|
||
|
||
## What this gives you
|
||
|
||
* Daily totals: requests, pageviews, unique visitors (hashed per-day), bytes
|
||
* “Top pages” list (query strings removed)
|
||
* Referrers by **domain only** (no full URLs)
|
||
* Browser/user-agent buckets (Chrome/Firefox/Bot/etc.)
|
||
* HTTP status code counts
|
||
* 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.
|
||
|
||
Your stats page will be:
|
||
|
||
* `https://tilde.club/~YOURNAME/stats/`
|
||
|
||
### Recommended: copy into `~/public_html/stats/`
|
||
|
||
```sh
|
||
mkdir -p ~/public_html/stats
|
||
cp -f ~/.local/share/tilde-stats/index.html ~/public_html/stats/index.html
|
||
cp -f ~/.local/share/tilde-stats/stats.json ~/public_html/stats/stats.json
|
||
chmod 644 ~/public_html/stats/index.html ~/public_html/stats/stats.json
|
||
```
|
||
|
||
### Alternative: symlink into `~/public_html/stats/` (requires permissions)
|
||
|
||
```sh
|
||
mkdir -p ~/public_html/stats
|
||
ln -sf ~/.local/share/tilde-stats/index.html ~/public_html/stats/index.html
|
||
ln -sf ~/.local/share/tilde-stats/stats.json ~/public_html/stats/stats.json
|
||
```
|
||
|
||
If you use symlinks, nginx must be able to **traverse** the real path under `~/.local/...` (see permissions below).
|
||
|
||
## Permissions (important, because Linux will happily sabotage you)
|
||
|
||
For nginx to serve a file, it must be able to:
|
||
|
||
* **traverse** every directory in the path (execute bit, `+x`)
|
||
* **read** the file (`+r`)
|
||
|
||
### Minimum permissions for userdir websites
|
||
|
||
If your `~/public_html` site already works, you probably already have this, but here’s the standard expectation:
|
||
|
||
```sh
|
||
chmod 711 ~
|
||
```
|
||
|
||
`chmod 711 ~` lets the web server traverse your home directory without listing it.
|
||
|
||
### If you are COPYING files (recommended)
|
||
|
||
Make sure your published files are world-readable:
|
||
|
||
```sh
|
||
chmod 644 ~/public_html/stats/index.html ~/public_html/stats/stats.json
|
||
```
|
||
|
||
Your `~/.local/share/tilde-stats/` directory can stay private.
|
||
|
||
### If you are SYMLINKING to `~/.local/share/tilde-stats/` (current reality)
|
||
|
||
Because the report lives in a dot-directory path, nginx must be able to traverse:
|
||
|
||
* `~`
|
||
* `~/.local`
|
||
* `~/.local/share`
|
||
* `~/.local/share/tilde-stats`
|
||
|
||
And it must be able to read the report files themselves.
|
||
|
||
Use these permissions:
|
||
|
||
```sh
|
||
chmod 711 ~/.local ~/.local/share ~/.local/share/tilde-stats
|
||
chmod 644 ~/.local/share/tilde-stats/index.html ~/.local/share/tilde-stats/stats.json
|
||
```
|
||
|
||
Notes:
|
||
|
||
* `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.
|
||
|
||
(Servers do not read minds, only logs.)
|