File Sharing and Storage

Stirling PDF can store files on the server and let users share them with each other. Files can be shared directly with specific users or via shareable links. Admins can set storage quotas to control disk usage.

Basic local-disk storage and sharing need no license - just turn on security.enableLogin and storage.enabled. Only the database and s3 storage providers require a Pro/Enterprise license. See Modes for what each deploy mode includes; self-hosted instances never use credits.

What You Can Do#

• Store files server-side -- upload PDFs and other files that persist across sessions
• Share with specific users -- grant other registered users access to your files with configurable permissions
• Share via link -- generate a shareable link that any logged-in user with the link can access
• Control access levels -- assign Editor, Commenter, or Viewer roles to shared users
• Set storage quotas -- limit storage per user, per file, or system-wide
• Audit access -- see who accessed your shared links and when
• Automatic cleanup -- expired share links and orphaned files are cleaned up daily

Prerequisites#

• Authentication must be enabled (security.enableLogin: true)
• For share links: system.frontendUrl must be set to your instance URL
• For email notifications when sharing: mail.enabled: true with valid SMTP configuration

Enabling File Storage#

storage:
  enabled: true
  provider: local          # 'local', 'database', or 's3'
  local:
    basePath: './storage'  # Filesystem path (local provider only)

STORAGE_ENABLED=true
STORAGE_PROVIDER=local
STORAGE_LOCAL_BASEPATH=./storage

Storage Providers#

Docker Volume Mount#

When using the local provider with Docker, mount the storage directory so files persist across container restarts:

volumes:
  - ./stirling-storage:/storage

S3-Compatible Object Storage#

Set storage.provider: s3 to store user uploads in any S3-compatible object store. The same storage.s3.* block is also used by the cluster artifact store (see below).

storage:
  enabled: true
  provider: s3
  s3:
    endpoint: ""                       # blank = AWS regional default; otherwise full URL incl. https://
    bucket: my-bucket                  # required
    region: us-east-1
    accessKey: ""                      # blank = fall back to AWS DefaultCredentialsProvider (env / profile / IMDS)
    secretKey: ""
    pathStyleAccess: false             # true for MinIO and Supabase; false for AWS/R2/most CDNs
    allowPrivateEndpoints: false       # SSRF guard - see below
    requestChecksumCalculation: WHEN_SUPPORTED   # WHEN_SUPPORTED | WHEN_REQUIRED | DISABLED
    responseChecksumValidation: WHEN_SUPPORTED   # WHEN_SUPPORTED | WHEN_REQUIRED | DISABLED

STORAGE_ENABLED=true
STORAGE_PROVIDER=s3
STORAGE_S3_ENDPOINT=
STORAGE_S3_BUCKET=my-bucket
STORAGE_S3_REGION=us-east-1
STORAGE_S3_ACCESSKEY=
STORAGE_S3_SECRETKEY=
STORAGE_S3_PATHSTYLEACCESS=false
STORAGE_S3_ALLOWPRIVATEENDPOINTS=false
STORAGE_S3_REQUESTCHECKSUMCALCULATION=WHEN_SUPPORTED
STORAGE_S3_RESPONSECHECKSUMVALIDATION=WHEN_SUPPORTED

S3 Configuration Keys#

Per-Vendor Cheat Sheet#

Sharing Credentials with the Cluster Artifact Store#

The storage.s3.* block is used in two places: the s3 storage provider (persistent user uploads) and the cluster artifact store when cluster.artifactStore: s3 (transient multi-node job artifacts). When both use S3 they reuse the same credentials and bucket. The cluster store writes under a separate key prefix (cluster.s3.keyPrefix, default transient/) so a single bucket can host both persistent uploads and transient artifacts without collisions. Multi-node deployments must set cluster.artifactStore: s3.

Enabling File Sharing#

storage:
  enabled: true
  sharing:
    enabled: true            # Master switch for all sharing
    linkEnabled: true        # Enable shareable links
    emailEnabled: true       # Send email notifications when sharing
    linkExpirationDays: 3    # Days until share links expire

STORAGE_SHARING_ENABLED=true
STORAGE_SHARING_LINKENABLED=true
STORAGE_SHARING_EMAILENABLED=true
STORAGE_SHARING_LINKEXPIRATIONDAYS=3

Feature Dependencies#

Storage Quotas#

Control how much storage space is available.

storage:
  quotas:
    maxStorageMbPerUser: -1   # Per-user cap in MB (-1 = unlimited)
    maxStorageMbTotal: -1     # Total system cap in MB (-1 = unlimited)
    maxFileMb: -1             # Max size per upload in MB (-1 = unlimited)

STORAGE_QUOTAS_MAXSTORAGEMBPERUSER=500
STORAGE_QUOTAS_MAXSTORAGEMBTOTAL=10000
STORAGE_QUOTAS_MAXFILEMB=100

Quotas are checked before a file is stored. When replacing an existing file, only the size difference counts against the quota.

Access Roles#

When sharing a file, you choose what level of access to grant:

The file owner always has full access. The default role is Editor.

The difference between Commenter and Viewer only matters in Shared Signing workflows -- both are read-only for regular file sharing.

The My Files Page#

When your admin has turned storage on, you get a My Files page (find it at /files once you are logged in). It is your personal space on the server for keeping documents that stick around between sessions, instead of living only in your browser tab.

On the My Files page you can:

• Upload documents to keep them on the server
• Organize them into folders, including folders inside folders, and drag files between them
• Preview a stored file right in the browser without downloading it
• Rename, move, and delete files and folders
• Jump around quickly using the folder sidebar on the left
• Personalize folders with colors and thumbnails so they are easy to spot
• See where each file lives - every item shows a small badge telling you whether it is in your current browser session or saved on the server

Your folders are private to you. Folders themselves are not shared; you share individual files instead (see Sharing Files below).

Sharing Files#

You can share a file from the My Files page, or from the Share button in the top bar of the editor workbench while a file is open.

Share with a Specific User#

From the file manager, select a file and share it with another user by their username or email address. You can choose the access role when sharing.

If you enter an email address for someone who doesn't have an account, the system will create a share link and email it to them (if email notifications are enabled).

Share via Link#

Generate a shareable link for any file you own. Anyone who is logged in and has the link can access the file. Links expire automatically based on your linkExpirationDays setting (default: 3 days).

You can revoke a share link at any time, which immediately removes access and deletes all access records for that link.

The share link URL follows the format:

https://your-stirling-instance.com/share/{token}

Access History#

For any share link you've created, you can view who accessed it, whether they viewed or downloaded the file, and when.

Security#

• All endpoints require authentication -- there is no anonymous file access
• Owner-only controls -- only the file owner can update, delete, or manage sharing
• Random tokens -- share link tokens are cryptographically random UUIDs
• Automatic expiration -- expired links return an error and are cleaned up daily
• Revocation -- owners can revoke any share link immediately
• Access auditing -- every share link access is recorded with user, action type, and timestamp

Known Limitations#

• Share links require system.frontendUrl to be configured
• Share links require the user to be logged in -- there is no public/anonymous access
• The database storage provider uses more memory with large files (use the local provider for large deployments)

Troubleshooting#

"Storage is disabled"#

• Verify storage.enabled: true in your settings
• Verify security.enableLogin: true

"Share links are disabled"#

• Verify storage.sharing.linkEnabled: true
• Verify system.frontendUrl is set to your instance URL

"Email sharing is disabled"#

• Verify storage.sharing.emailEnabled: true
• Verify mail.enabled: true with valid SMTP settings

Share link returns 404 Not Found#

• The link has expired or does not exist. Expired and missing links both return 404 Not Found. The file owner needs to create a new one.

Quota exceeded (HTTP 413)#

• A file or upload that exceeds a configured quota is rejected with 413 Payload Too Large (per-file, per-user, and total-storage caps all use this status)
• Increase maxStorageMbPerUser, maxStorageMbTotal, or maxFileMb, or delete unused files to free up space

Developer Reference: Storage API#

This section is for developers and admins automating storage outside the web app. If you just want to upload, organize, and share files, everything above is done from the My Files page - you do not need any of this.

The full storage and sharing endpoints are listed below. See API Documentation for authentication and general usage.

Folder Endpoints#

These are the endpoints behind the folders on the My Files page. All operations are scoped to the authenticated user.

Related#

• Shared Signing -- Collaborative multi-participant document signing
• Certificate Signing -- Individual certificate signing
• System and Security Settings -- JWT, sessions, server certificates