death-notifier/README.md

# Death Notifier
Get notified when a famous person dies.

Wikipedia's editors [are known](https://knowyourmeme.com/memes/wikipedia-editors-when-someone-dies) for updating pages
as soon as someone has died.
Why not turn that into a service?
This tool regularly checks if people are still alive according to Wikipedia, and emails you as soon as that changes.


## Development
### Requirements
* PHP 8.1+ (i.e. `apt install php php-cgi`)
  * [PHP cURL](https://www.php.net/manual/en/book.curl.php) (i.e. `apt install php-curl`)
  * [PHP DOM](https://www.php.net/manual/en/book.dom.php) (i.e. `apt install php-dom`)
  * [PHP SQLite 3](https://www.php.net/manual/en/book.sqlite3.php) (i.e. `apt install php-sqlite3`)
* [composer](https://getcomposer.org/) (make sure `composer.phar` is on your path)
* [npm](https://www.npmjs.com/)

### Setting up
Install the latest dependencies.
Run this after cloning the repo, and each time after pulling new commits.
```shell
composer.phar install
npm ci
```

### Building
* Build the tool in `dist/` for development
  ```shell
  npm run dev
  ```
* Same as above, but automatically rebuild whenever source code is changed
  ```shell
  npm run dev:server
  ```
* Build the tool in `dist/` for deployment
  ```shell
  npm run deploy
  ```

### Pre-commit
If you changed the version number or updated any dependencies, update the lock files:
```shell
composer.phar update
npm install
```

### Static analysis
* Run static analysis
  ```shell
  npm run analyze
  ```
* Run all tests
  ```shell
  npm run test
  ```
* Run all tests in package
  ```shell
  npm run test -- --test-target=com/fwdekker/deathnotifier/wikipedia/
  ```
* Run static analysis and tests
  ```shell
  npm run check
  ```


## Deployment
### Build
Build the software and move it to the right directory.
```shell
npm run deploy
mv dist/ /var/www/death-notifier/
```

### Configuration
Inside the installation directory, create `config.ini.php` and use it to override values from `config.default.ini.php`.
Make sure only the user that runs PHP can read/write `config.ini.php`.

### Cron jobs
You should run the `process-email-queue` and `update-all-trackings` actions regularly;
recommended is every minute and every five minutes, respectively.
For example, you can add the following lines to your crontab (e.g. using `sudo -u www crontab -e`):
```
* * * * * cd /var/www/death-notifier && php /var/www/death-notifier/api.php action=process-email-queue password=secret_password
*/5 * * * * cd /var/www/death-notifier && php /var/www/death-notifier/api.php action=update-all-trackings password=secret_password
```
Replace `secret_password` with the password you configured in `config.ini.php`.

### Logs
It is recommended to also use a tool such as `newsyslog` to manage log rotation.
For example, create the file `/etc/newsyslog.conf.d/death-notifier.conf` with the following contents:
```
/var/www/death-notifier/.death-notifier.log www:www 644 7 * @T00 JpE
```

### Initialize
Open `index.html` in an interactive browser to initialize the database.
Make sure only the user that runs PHP can read/write `.death-notifier.db`.

### Inspection
You can use a tool such as [VisiData](https://www.visidata.org/) to manually inspect the database contents on the
command line.