Optional automatic PDF compression on document upload

[julianwitzel]

Summary

Add an account-level preference (and corresponding environment variable for self-hosters) to automatically compress uploaded PDF documents before storage, reducing file sizes without requiring users to pre-process documents externally.

Motivation

Self-hosted DocuSeal instances often integrate with email infrastructure that has size limits on attachments. For example:

• AWS SES (default): 40 MB per message
• Many SMTP relays and self-hosted email platforms: 10 MB or less
• Recipients with conservative inbox quotas

When DocuSeal sends completion emails with the signed PDF as an attachment, even moderately sized PDFs (8–15 MB) can hit these limits. Today, the workaround is one of:

1. Disabling email attachments entirely (degraded UX — recipients only get a download link)
2. Pre-compressing PDFs externally before upload (manual, error-prone, inconsistent)
3. Increasing email infrastructure limits (often not possible for self-hosters using third-party relays)

A built-in compression option would solve this at the source. Many existing preferences already modify the uploaded PDF (e.g., "Add signature ID to the documents", "Combine completed documents and Audit Log"), so an additional optimization step would fit naturally into the existing architecture.

Proposed Solution

UI option (Account → Preferences)

Add a new toggle in the Preferences panel:

Compress PDF documents on upload
Automatically reduce file size of uploaded PDFs while preserving readability. Useful when sending signed documents as email attachments.

When enabled, uploaded PDFs are passed through Ghostscript (or equivalent) with a sensible default profile (/ebook quality, ~150 DPI image downsampling) before being stored.

Environment variable (for self-hosters)

For headless / programmatic configuration:

# Enable automatic PDF compression on upload
COMPRESS_UPLOADED_PDFS=true

# Optional: Compression profile (screen|ebook|printer|prepress)
# Default: ebook (good balance of size vs. quality)
PDF_COMPRESSION_PROFILE=ebook

Optional: Per-template override

Allow templates to opt out of compression for cases where original fidelity is required (e.g., legal documents with specific print requirements).

Implementation Notes

• Ghostscript is already widely used for PDF processing and is available as a Debian/Alpine package
• The /ebook preset typically reduces file size by 50–80% with minimal visible quality loss
• Compression should happen before the original is stored, not on retrieval, to keep storage costs low
• Important caveat: Compression should be skipped if the uploaded PDF already contains digital signatures (to avoid invalidating them)

Alternatives Considered

1. External compression before upload — Works but creates manual overhead and inconsistent results across team members.
2. Compress only on email attachment send — Would solve the email use case but not the storage/bandwidth case, and would require regenerating compressed versions repeatedly.
3. Disable email attachments entirely — Already supported, but gives a worse UX for recipients who expect the document directly in their inbox.

Use Case

Our team uses DocuSeal as the contract signing platform alongside a self-hosted Plunk instance for transactional emails. Plunk has a 10 MB attachment limit (built on top of AWS SES). Most contracts work fine, but visually rich documents (templates with logos, embedded images, scanned signatures from previous parties) easily exceed this limit. Pre-compressing every document before upload is impractical, especially for non-technical team members.

Additional Context

This feature would also benefit:

• Users on tight S3 storage budgets
• Users hosting DocuSeal on small VPS instances with limited disk space
• Recipients on mobile devices or slow connections downloading signed documents
• API users uploading documents programmatically via webhooks or integrations

Happy to discuss the approach further or contribute a PR if this direction sounds good.