site/wiki/source/user_statistics.md

title, category

title	category
Userdir traffic stats (sanitized analytics)	Software

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:

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/

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)

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:

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:

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:

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:

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:

ls -l ~/public_html/stats/

• Confirm permissions all the way down the path:

namei -l ~/public_html/stats/index.html

If you’re using symlinks into ~/.local, also check the target path:

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.)