coredesktop/server/report-receiver/README.md

Report receiver

Takes the error reports CoreDesktop machines send with report (see the top of ../../report for the request format) at https://federated.sh/report, and files each as an issue in the private Gitea repository Federated_Computer/coredesktop-reports, with the full log attached.

• receiver.py listens on 127.0.0.1:8650, behind Caddy. Standard library only.
• It saves each report in /var/lib/coredesktop-reports/<ID>/ before replying, so a report isn't lost if Gitea is down, and tries again every 10 minutes. Saved reports are deleted after 90 days; the Gitea issues stay.
• It turns away more than 5 reports an hour or 20 a day from one address, and more than 500 a day in all, and logs bigger than 10 MB compressed or 64 MB uncompressed.
• make test in the repository runs test_receiver.py, which sends reports with the real report client to the receiver and a fake Gitea.

Deploying on federated.sh

1. A Gitea user that can only file issues there. Gitea tokens can't be limited to one repository, so make a separate user (say coredesktop-reports-bot), add it to Federated_Computer/coredesktop-reports as a collaborator with write access, and make it a token with only the write:issue permission. Nothing else should be shared with that user.

2. Install the receiver (as root):

   install -d -m 755 /opt/coredesktop-reports
   install -m 644 receiver.py /opt/coredesktop-reports/receiver.py
   install -m 644 coredesktop-reports.service /etc/systemd/system/coredesktop-reports.service
   install -m 600 /dev/null /etc/coredesktop-reports.env
   

   Then put the settings in /etc/coredesktop-reports.env:

   GITEA_URL=https://gitea.federated.computer
   GITEA_REPO=Federated_Computer/coredesktop-reports
   GITEA_TOKEN=<the bot's token>
   

   systemctl daemon-reload
   systemctl enable --now coredesktop-reports
   curl -s http://127.0.0.1:8650/report/health    # prints ok
   

3. Route /report to it in Caddy. See Caddyfile.example: /report goes in its own handle block, and the site's existing directives go in a catch-all handle, so the installer redirect keeps working. Check with caddy validate, then systemctl reload caddy.

4. Check it end to end. curl -s https://federated.sh/report/health prints ok, wget -qO- https://federated.sh | head -3 still shows install.sh, and from a CoreDesktop machine report sends its newest log and prints an ID, which appears as a new issue in the repository.

To update it later, install the new receiver.py the same way and run systemctl restart coredesktop-reports. journalctl -u coredesktop-reports shows each report it receives and files.