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.
  • Python 96.9%
  • Dockerfile 3.1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Stefan Bethke 6a0d4365ca Remove unreferenced uploads and attach them to expiry mails
HedgeDoc doesn't track uploaded files, so they stay on disk after their
note is deleted. If UPLOADS_PATH is set, expire now removes uploads that
no remaining note or revision references and that are older than -u DAYS
(default 1). check and emailcheck list the files that would be removed.

Expiry mails now include the note's uploads as attachments, up to a total
of MAX_ATTACHMENT_SIZE bytes (default 20 MB); files that don't fit are
listed in the mail text instead.
2026-10-27 12:55:20 +01:00
.forgejo/workflows Try the new runner 2024-07-21 14:42:25 +02:00
docker-compose.yaml Remove unreferenced uploads and attach them to expiry mails 2026-10-27 12:55:20 +01:00
Dockerfile Build an image and add it to compose 2024-05-18 18:56:22 +02:00
hedgedoc-expire.py Remove unreferenced uploads and attach them to expiry mails 2026-10-27 12:55:20 +01:00
LICENSE first version of the script 2024-05-18 18:31:30 +02:00
poetry.lock first version of the script 2024-05-18 18:31:30 +02:00
pyproject.toml first version of the script 2024-05-18 18:31:30 +02:00
README.md Remove unreferenced uploads and attach them to expiry mails 2026-10-27 12:55:20 +01:00

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

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

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.

If UPLOADS_PATH is set, files uploaded to the note (images and other attachments) are attached to the mail as well, up to a total of MAX_ATTACHMENT_SIZE bytes. Files that do not fit are listed in the mail text instead.

Expiring unreferenced uploads

Hedgedoc does not keep track of uploaded files, so they remain on disk after their note has been deleted, either by the user or by hedgedoc-expire. If UPLOADS_PATH points to Hedgedoc's uploads directory (/hedgedoc/public/uploads in the Hedgedoc container image), hedgedoc-expire will remove all files in that directory that are not referenced by any remaining note or revision. To avoid deleting files that have just been uploaded, but whose note has not been saved yet, only files older than the age given with -u are removed.

A file is considered referenced if its name appears in a link containing /uploads/<name> in any note or revision, regardless of the host name in the link. Links to uploads from outside of Hedgedoc are not taken into account. Only the filesystem upload type is supported.

Running hedgedoc-expire.py

Locally from the command line:

poetry run python ./hedgedoc-expire.py ...

From Docker Compose:

  hedgedoc-expire:
    image: hedgedoc-expire
    command: "-c -r 14 -n 95"
    environment:
      - "POSTGRES_HOSTNAME=database"
      - "UPLOADS_PATH=/uploads"
    volumes:
      - uploads:/uploads
    depends_on:
      - database

Running 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

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 90 remove all notes not changed in these many days
-r 7 remove all revisions created more than these many days ago
-u 1 remove unreferenced uploads older than these many days
-v false Print info on current action during cron and expire commandds

Command is one of:

Command Description
check Print a list of revisions, notes and uploads that would be expired, based on -n, -r and -u
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, notes and unreferenced uploads.

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
MAX_ATTACHMENT_SIZE 20971520 maximum total size of uploads attached to an expiry mail
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
UPLOADS_PATH Hedgedoc uploads directory; uploads are ignored if not set
URL http://localhost:3000 base URL for linking to notes

Local Development Setup

Use Docker Compose to bring up a local development environment.

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