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:

poetry run python ./hedgedoc-expire.py expire -n 7 -r 7

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 checking which notes older than 7 days would be expired (and only checking notes):

poetry run python ./hedgedoc-expire.py check -n 7

From Docker Compose checking which notes older than 95 and which revisions older than 14 days would be expired:

  hedgedoc-expire:
    image: hedgedoc-expire
    command: "check -r 14 -n 95"
    environment:
      - "POSTGRES_HOSTNAME=database"
    depends_on:
      - database

Running a check against a local setup with one note, with times set to a fraction of a day:

$ 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

Commands, Arguments and Environment Variables

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	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

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 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:

docker compose exec -it hedgedoc bin/manage_users --add foo@example.com --pass geheim