forked from CCCHH/hedgedoc-expire
07ef29225e
And then only act on notes/revisions, if the relevant argument got specified. This makes the CLI cleaner.
125 lines
No EOL
7 KiB
Markdown
125 lines
No EOL
7 KiB
Markdown
# 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.
|
|
|
|
## 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.
|
|
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.
|
|
|
|
### 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.
|
|
|
|
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`
|
|
|
|
Locally from the command line expiring revisions and notes older than 7 days:
|
|
|
|
```shell
|
|
poetry run python ./hedgedoc-expire.py expire -n 7 -r 7
|
|
```
|
|
|
|
Locally from the command line only expiring revisions older than 7 days:
|
|
|
|
```shell
|
|
poetry run python ./hedgedoc-expire.py expire -r 7
|
|
```
|
|
|
|
Locally from the command line only expiring notes older than 7 days:
|
|
|
|
```shell
|
|
poetry run python ./hedgedoc-expire.py expire -n 7
|
|
```
|
|
|
|
From Docker Compose:
|
|
|
|
```yaml
|
|
hedgedoc-expire:
|
|
image: hedgedoc-expire
|
|
command: "-c -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:
|
|
|
|
```shell
|
|
$ poetry run python ./hedgedoc-expire.py -n .001 -r .001
|
|
Revisions to be deleted created before 2024-05-20 09:02:46.407671+00:00 (a minute):
|
|
foo@example.com http://localhost:3000/foo: hedgedoc-expire - remove old notes
|
|
a day: 328dd778-6914-4a04-be58-940b1fe83e01
|
|
a day: 5acca085-51da-4463-ad20-74dc03e68255
|
|
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
|
|
|
|
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.
|
|
|
|
| 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 |
|
|
| -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.
|
|
|
|
For the SMTP connection, the code assumes a standard submission protocol setup with enable StartTLS and authentication,
|
|
so you will need to configure a username and password.
|
|
|
|
| Variable | Default | Description |
|
|
|---------------------|------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|
|
| POSTGRES_CONNSTRING | postgresql://hedgedoc:geheim@localhost:5432/hedgedoc | [PostgreSQL connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) specifying where and how to connnect to the database |
|
|
| SMTP_FROM | | sender address for the expiry mails |
|
|
| SMTP_HOSTNAME | localhost | mail server hostname |
|
|
| SMTP_PASSWORD | | SMTP password |
|
|
| SMTP_PORT | 587 | port to connect to |
|
|
| SMTP_USERNAME | | SMTP username |
|
|
| URL | http://localhost:3000 | base URL for linking to notes |
|
|
|
|
## Local Development Setup
|
|
|
|
Use Docker Compose to bring up a local development environment.
|
|
|
|
* Hedgedoc: http://localhost:3000
|
|
* Adminer: http://localhost:8080/?pgsql=database&username=hedgedoc&db=hedgedoc&ns=public&password=geheim
|
|
|
|
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
|
|
``` |