Userdir traffic stats


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