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.
This commit is contained in:
Stefan Bethke 2026-10-27 12:55:20 +01:00
commit 6a0d4365ca

View file

@ -26,6 +26,21 @@ by the mail server, the note will not be removed. Note however that this utility
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:
@ -42,6 +57,9 @@ From Docker Compose:
command: "-c -r 14 -n 95"
environment:
- "POSTGRES_HOSTNAME=database"
- "UPLOADS_PATH=/uploads"
volumes:
- uploads:/uploads
depends_on:
- database
```
@ -67,16 +85,17 @@ Without it, the expiry action will be taken.
|--------|---------|-------------------------------------------------------------------|
| -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 and notes that would be expired, based on the given parameters for `-n` and `-r` |
| 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 and notes. |
| expire | Expire old revisions, notes and unreferenced uploads. |
### Environment variables
@ -85,19 +104,21 @@ To configure the Postgres database connection and the SMTP parameters to send ma
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 |
| 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