improve docs

This commit is contained in:
Stefan Bethke 2024-05-18 19:19:06 +02:00
parent 5cde4ac06b
commit 7c4cb94ea8
2 changed files with 62 additions and 8 deletions

View file

@ -1,14 +1,68 @@
# 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 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 ## 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 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.
### Expiring old revisions ### Expiring old revisions
All revisions that have been created before the specified age will be removed. If all revisions are older the newest revision that represents the current contents of the note will be retained. All revisions that have been created before the specified age will be removed. If all revisions are older the newest
revision that represents the current contents of the note will be retained.
## Running hedgedoc-expire.py
Locally from the command line:
```shell
poetry run python ./hedgedoc-expire.py ...
```
From Docker Compose:
```yaml
hedgedoc-expire:
image: hedgedoc-expire
command: "-c -r .001 -n .001"
environment:
- "POSTGRES_HOSTNAME=database"
depends_on:
- database
```
## 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 |
|--------|---------|------------------------------------------------------------|
| -c | | Create a report which revisions and notes will be expired |
| -n | 90 | remove all notes not changed in these many days |
| -r | 7 | remove all revisions created more than these many days ago |
### 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_DATABASE | hedgedoc | database to connect to |
| POSTGRES_HOSTNAME | localhost | host of the database server |
| POSTGRES_PASSWORD | geheim | password for the database |
| POSTGRES_PORT | 5432 | port number of the database server |
| POSTGRES_USERNAME | hedgedoc | username for 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 ## Local Development Setup

View file

@ -185,13 +185,13 @@ if __name__ == '__main__':
parser = argparse.ArgumentParser( parser = argparse.ArgumentParser(
prog='hedgedoc-expire', prog='hedgedoc-expire',
description='Remove old notes and revisions from Hedgedoc', description='Remove old notes and revisions from Hedgedoc',
epilog='See https://git.hamburg.ccc.de/xxx') epilog='See https://git.hamburg.ccc.de/CCCHH/hedgedoc-expire')
parser.add_argument('-r', '--revisions', metavar='DAYS', type=float, default=7,
help='remove all revisions created more than these many days ago')
parser.add_argument('-n', '--notes', metavar='DAYS', type=float, default=90,
help='remove all notes not changed in these many days')
parser.add_argument('-c', '--check', action='store_true', parser.add_argument('-c', '--check', action='store_true',
help='print what would be done, then exit') help='print what would be done, then exit')
parser.add_argument('-n', '--notes', metavar='DAYS', type=float, default=90,
help='remove all notes not changed in these many days')
parser.add_argument('-r', '--revisions', metavar='DAYS', type=float, default=7,
help='remove all revisions created more than these many days ago')
args = parser.parse_args() args = parser.parse_args()
revisions_delta = timedelta(days=args.revisions) revisions_delta = timedelta(days=args.revisions)