diff --git a/README.md b/README.md index b38355e..5ae22a8 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,35 @@ # hedgedoc-expire - remove old notes -A Python app that can be run regularly against a Postgres Hedgedoc database to remove old notes. Notes that are expired -can be emailed to the author as a backup. +A Python app that can be run regularly against a Postgres Hedgedoc database to remove old notes. +Notes that are expired can be emailed to the author as a backup. ## Expiring old notes and revisions -Hedgedoc keeps notes and revisions (versions) of those notes forever. This might not be desirable, for example because -of data protection reasons. With this utility, you can remove old revisions and old notes from the -database. `hedgedoc-expire` works by talking directly to a Postgres database; no API access to Hedgedoc is required. +Hedgedoc keeps notes and revisions (versions) of those notes forever. +This might not be desirable, for example because of data protection reasons. +With this utility, you can remove old revisions and old notes from the database. +`hedgedoc-expire` works by talking directly to a Postgres database; no API access to Hedgedoc is required. Currently, it only works with Postgres. ### Expiring old revisions Using the `-r` or `--revisions` argument. -All revisions that have been created before the specified age will be removed. If all revisions are expired, the note -remains available, it just won't have any revisions to revert to. Once you continue editing it, new revisions will be -added. +All revisions that have been created before the specified age will be removed. +If all revisions are expired, the note remains available, it just won't have any revisions to revert to. +Once you continue editing it, new revisions will be added. ### Expiring old notes Using the `-n` or `--notes` argument. -Notes that are being expired will be emailed to the account that initially created the note. This allows that user to -restore the note, if necessary. Expiring a note will also remove all existing revisions for the note. +Notes that are being expired will be emailed to the account that initially created the note. +This allows that user to restore the note, if necessary. +Expiring a note will also remove all existing revisions for the note. -You will need to configure your environment for `hedgedoc-expire` to be able to send mail. If the mail is not accepted -by the mail server, the note will not be removed. Note however that this utility has no idea if the mail server has -successfully delivered that mail to the intended recipient; if the mail gets lost somewhere on the way, the note cannot -be recovered. +You will need to configure your environment for `hedgedoc-expire` to be able to send mail. +If the mail is not accepted by the mail server, the note will not be removed. +Note however that this utility has no idea if the mail server has successfully delivered that mail to the intended recipient; if the mail gets lost somewhere on the way, the note cannot be recovered. ## Running `hedgedoc-expire.py` @@ -44,25 +45,25 @@ Locally from the command line only expiring revisions older than 7 days: poetry run python ./hedgedoc-expire.py expire -r 7 ``` -Locally from the command line only expiring notes older than 7 days: +Locally from the command line checking which notes older than 7 days would be expired (and only checking notes): ```shell -poetry run python ./hedgedoc-expire.py expire -n 7 +poetry run python ./hedgedoc-expire.py check -n 7 ``` -From Docker Compose: +From Docker Compose checking which notes older than 95 and which revisions older than 14 days would be expired: ```yaml hedgedoc-expire: image: hedgedoc-expire - command: "-c -r 14 -n 95" + command: "check -r 14 -n 95" environment: - "POSTGRES_HOSTNAME=database" depends_on: - database ``` -Running against a local setup with one note, with times set to a fraction of a day: +Running a check against a local setup with one note, with times set to a fraction of a day: ```shell $ poetry run python ./hedgedoc-expire.py -n .001 -r .001 @@ -74,26 +75,26 @@ Notes to be deleted not changed since 2024-05-20 09:02:46.416294+00:00 (a minute foo@example.com (a day) http://localhost:3000/foo: hedgedoc-expire - remove old notes ``` -## Arguments and Environment Variables +## Commands, Arguments and Environment Variables -There are two main modes to run `hedgedoc-require`: check and expire. With `-c`, a report is generated on standard out. -Without it, the expiry action will be taken. +`hedgedoc-expire` provides several different commands with check being the default: + +| Command | Description | +|------------|--------------------------------------------------------------------------------------------------------| +| check | Print a list of revisions and notes that would be expired, based on the given arguments `-n` and `-r`. | +| cron | Run `expire` at 2 am local time each day. Will run until killed. | +| emailcheck | Send an email from the configured sender to themselves with the the check report. | +| expire | Expire old revisions and notes, based on the given arguments `-n` and `-r`. | + +Additionally the following arguments are available. +`-n` and `-r` are crucial in determining whether or not and how many notes/revisions should be targeted. | Option | Default | Description | |--------|---------|-------------------------------------------------------------------| -| -n | None | remove all notes not changed in these many days | -| -r | None | remove all revisions created more than these many days ago | +| -n | None | target all notes not changed in these many days | +| -r | None | target all revisions created more than these many days ago | | -v | false | Print info on current action during `cron` and `expire` commandds | -Command is one of: - -| Command | Description | -|------------|------------------------------------------------------------------------------------------------------------| -| check | Print a list of revisions and notes that would be expired, based on the given parameters for `-n` and `-r` | -| cron | Run `expire` at 2 am local time each day. Will run until killed. | -| emailcheck | Send an email from the configured sender to themselves with the the check report. | -| expire | Expire old revisions and notes. | - ### Environment variables To configure the Postgres database connection and the SMTP parameters to send mail, set these variables. @@ -122,4 +123,4 @@ You will need to create a user using the command line: ```sh docker compose exec -it hedgedoc bin/manage_users --add foo@example.com --pass geheim -``` \ No newline at end of file +``` diff --git a/hedgedoc-expire.py b/hedgedoc-expire.py index 9a2e0c1..54478f7 100644 --- a/hedgedoc-expire.py +++ b/hedgedoc-expire.py @@ -336,11 +336,11 @@ def main(): Revisions of notes that have been created before the specified time will be deleted. '''), epilog=dedent('''\ - command is one of: - - check: print a list of revisions and notes to be expired - - cron: run expire every 24 hours - - emailcheck: send am email from the configured sender to themselves with the the check report - - expire: expire old revisions and untouched notes + command is one of, which check being the default: + - check: Print a list of revisions and notes that would be expired, based on the given arguments -n and -r. + - cron: Run `expire` at 2 am local time each day. Will run until killed. + - emailcheck: Send an email from the configured sender to themselves with the the check report. + - expire: Expire old revisions and notes, based on the given arguments -n and -r. See https://git.hamburg.ccc.de/CCCHH/hedgedoc-expire ''')