CCCHH/hedgedoc-expire
0
0
Fork 1
Code Issues Pull requests 1 Projects Releases Packages 1 Wiki Activity Actions

improve docs with better infos, format and consistency

Browse source 
For the README:
- Improve the format, getting rid of the textwidth-based linebreaks and
  instead putting each sentence on its own line.
- Have an example for a local check execution to have the examples be
  more diverse.
- Describe the docker compose example and have it be up-to-date.
- Better describe the local setup example.
- Reformat the section on commands and arguments, first describing the
  commands and then the arguments, as this makes more sense
  structurally.
- Also change the title of the arguments and environment variables
  section to reflect its content on commands.

For the help output mirror the command descriptions of the README and
improve the format.
This commit is contained in:
Julian Schacher 2024-12-09 18:22:27 +01:00
parent 07ef29225e
commit 5569119fcc
2 changed files with 40 additions and 39 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

67
README.md
View file

@ -1,34 +1,35 @@
# hedgedoc-expire - remove old notes # 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 A Python app that can be run regularly against a Postgres Hedgedoc database to remove old notes.
can be emailed to the author as a backup. Notes that are expired can be emailed to the author as a backup.
## Expiring old notes and revisions ## Expiring old notes and revisions
Hedgedoc keeps notes and revisions (versions) of those notes forever. This might not be desirable, for example because Hedgedoc keeps notes and revisions (versions) of those notes forever.
of data protection reasons. With this utility, you can remove old revisions and old notes from the This might not be desirable, for example because of data protection reasons.
database. `hedgedoc-expire` works by talking directly to a Postgres database; no API access to Hedgedoc is required. 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. Currently, it only works with Postgres.
### Expiring old revisions ### Expiring old revisions
Using the `-r` or `--revisions` argument. 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 All revisions that have been created before the specified age will be removed.
remains available, it just won't have any revisions to revert to. Once you continue editing it, new revisions will be If all revisions are expired, the note remains available, it just won't have any revisions to revert to.
added. Once you continue editing it, new revisions will be added.
### Expiring old notes ### Expiring old notes
Using the `-n` or `--notes` argument. 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 Notes that are being expired will be emailed to the account that initially created the note.
restore the note, if necessary. Expiring a note will also remove all existing revisions for 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 You will need to configure your environment for `hedgedoc-expire` to be able to send mail.
by the mail server, the note will not be removed. Note however that this utility has no idea if the mail server has If the mail is not accepted by the mail server, the note will not be removed.
successfully delivered that mail to the intended recipient; if the mail gets lost somewhere on the way, the note cannot 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.
be recovered.
## Running `hedgedoc-expire.py` ## 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 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 ```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 ```yaml
hedgedoc-expire: hedgedoc-expire:
image: hedgedoc-expire image: hedgedoc-expire
command: "-c -r 14 -n 95" command: "check -r 14 -n 95"
environment: environment:
- "POSTGRES_HOSTNAME=database" - "POSTGRES_HOSTNAME=database"
depends_on: depends_on:
- database - 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 ```shell
$ poetry run python ./hedgedoc-expire.py -n .001 -r .001 $ 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 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. `hedgedoc-expire` provides several different commands with check being the default:
Without it, the expiry action will be taken.
| 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 | | Option | Default | Description |
|--------|---------|-------------------------------------------------------------------| |--------|---------|-------------------------------------------------------------------|
| -n | None | remove all notes not changed in these many days | | -n | None | target all notes not changed in these many days |
| -r | None | remove all revisions created more than these many days ago | | -r | None | target all revisions created more than these many days ago |
| -v | false | Print info on current action during `cron` and `expire` commandds | | -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 ### Environment variables
To configure the Postgres database connection and the SMTP parameters to send mail, set these variables. To configure the Postgres database connection and the SMTP parameters to send mail, set these variables.

10
hedgedoc-expire.py
View file

@ -336,11 +336,11 @@ def main():
Revisions of notes that have been created before the specified time will be deleted. Revisions of notes that have been created before the specified time will be deleted.
'''), '''),
epilog=dedent('''\ epilog=dedent('''\
command is one of: command is one of, which check being the default:
- check: print a list of revisions and notes to be expired - check: Print a list of revisions and notes that would be expired, based on the given arguments -n and -r.
- cron: run expire every 24 hours - cron: Run `expire` at 2 am local time each day. Will run until killed.
- emailcheck: send am email from the configured sender to themselves with the the check report - emailcheck: Send an email from the configured sender to themselves with the the check report.
- expire: expire old revisions and untouched notes - expire: Expire old revisions and notes, based on the given arguments -n and -r.
See https://git.hamburg.ccc.de/CCCHH/hedgedoc-expire See https://git.hamburg.ccc.de/CCCHH/hedgedoc-expire
''') ''')