forgery/README.md

# spam management for forgejo

## Usage

- remove `model.json` if you want to start with no pre-existing model of what is
  spam or not. Or keep it to use the current classifier. The file gets updated
  when using the tool: the classifier learns from spam/legit decisions and
  should get progressively better at identifying spam.
- run: `cargo run`
- classify users as spam/not spam. By default the classification is stored
  locally in `db.json`, no concrete action is taken. (see the
  `ACTUALLY_BAN_USERS` environment variable below.)

## Configuration

Forgery reads the following environment variables:
- `FORGEJO_API_TOKEN`: Forgejo API token *granting admin access*. Required. You
  can generate an API token using the Forgejo web interface in `Settings ->
  Applications -> Generate New Token`.
- `ACTUALLY_BAN_USERS`: define it (e.g. to `true`) to actually lock user
  accounts, send notification emails and eventually delete user accounts. If not
  defined (the default), no actual action is taken, spammers are only listed in
  the database. The variable should be set in production, but probably not for
  testing.

Environment variables that are relevant when `ACTUALLY_BAN_USERS=true`:
- `SMTP_ADDRESS`: address of the SMTP relay used to send email notifications
- `SMTP_USERNAME`: SMTP username
- `SMTP_PASSWORD`: SMTP password

## Todos

- discuss the current design choices for when locking the account/sending a
  notification email fails.
  (Current behavior is to periodically retry, avoid deleting if the account
   could not be locked, but delete the account after the grace period even if
   the email could not be sent…)
- add backend to store data on garage instead of local files
- improve error handling 
- bundle auxiliary files (templates, css) in the binary for easy deployment?