123 lines
4.0 KiB
Markdown
123 lines
4.0 KiB
Markdown
# 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`) (compiled with Argon2 support)
|
|
* [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 mbstring](https://www.php.net/manual/en/book.mbstring.php) (i.e. `apt install php-mbstring`)
|
|
* [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 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 and tests
|
|
Note that PHPUnit suppresses output from `print`.
|
|
Instead, you can use `fwrite(STDERR, print_r("my message", TRUE));`.
|
|
|
|
* Run static analysis
|
|
```shell
|
|
npm run analyze
|
|
```
|
|
* Run all tests
|
|
```shell
|
|
npm run test
|
|
```
|
|
* Run only select tests
|
|
```shell
|
|
npm run test -- --test-filter="test-name file-name"
|
|
```
|
|
Note that a `test-name` of `''` and a `file-name` of `.` matches all tests.
|
|
|
|
* Run all tests in package
|
|
```shell
|
|
npm run test -- --test-filter="'' com/fwdekker/deathnotifier/wikipedia/"
|
|
```
|
|
* Run all tests in class
|
|
```shell
|
|
npm run test -- --test-filter="'' com/fwdekker/deathnotifier/wikipedia/WikipediaTest.php"
|
|
```
|
|
* Run only specific test
|
|
```shell
|
|
npm run test -- --test-filter="test_query_detects_dead_person ."
|
|
```
|
|
* 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-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-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`](https://man.freebsd.org/cgi/man.cgi?query=newsyslog.conf&sektion=5) 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 600 7 * @T00 JE
|
|
/var/www/death-notifier/.death-notifier.db.log www:www 600 7 * $W0D23 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.
|