Version: 10.0

MINIO Provider

The MINIO provider uses MinIO, a high-performance S3-compatible object storage system, for storing files. MinIO is ideal for cluster deployments where multiple webPDF Server nodes need to share file storage.

Overview

Provider Name: MINIO
Supports: File Storage only
Configuration File: provider-minio.yaml
Use Case: Cluster deployments, scalable file storage, S3-compatible storage
Protocol: S3 API compatible

Features

✓ S3-compatible API
✓ High-performance object storage
✓ Cluster-ready with shared file access
✓ Scalable and distributed
✓ Support for versioning and encryption
✓ Multi-tenant with bucket isolation
✓ ETag-based local caching for improved performance
✓ Automatic retry with exponential backoff
✓ Batch deletion for efficient cleanup
✓ Configurable connection pooling
✓ Event Manager support for notifications
✗ Requires external MinIO server or S3-compatible service
✗ Higher latency compared to local filesystem

Prerequisites

MinIO server or S3-compatible service
Network connectivity from webPDF Server to MinIO
MinIO access credentials (access key, secret key)
Bucket created or automatic bucket creation enabled

Configuration

provider.json

{
  "fileStorage": {
    "name": "MINIO",
    "checks": {
      "enabled": true,
      "interval": 10000
    }
  }
}

provider-minio.yaml

Configuration file for MinIO file storage (YAML format):

url: http://minio.example.com:9000
username: minioadmin
password: minioadmin-secret
bucketName: webpdf-files
settings:
  region: us-east-1

Configuration Attributes

Required Attributes

Attribute	Type	Description	Example
`url`	string	MinIO server endpoint URL	`http://minio.example.com:9000`
`username`	string	MinIO access key	`minioadmin`
`password`	string	MinIO secret key	`minioadmin-secret`

Optional Attributes

Attribute	Type	Description	Default
`bucketName`	string	S3 bucket name for file storage	Auto-generated
`settings`	object	Additional MinIO/S3 client settings	`{}`

Settings Object

The settings object supports S3 client configuration options:

Setting	Type	Description	Default
`region`	string	AWS/MinIO region	-

Bucket Naming

If bucketName is not specified, it is automatically generated using the namespace configuration:

{org}-{app}-{env}-{version}

Example: webpdf-webpdf-prod-v10-0

tip

For better organization, explicitly set bucketName to a meaningful value like webpdf-files-prod.

Environment Variables

# MinIO file storage
WEBPDF_MINIO_FILE_STORAGE_SETTINGS_URL=http://minio.example.com:9000
WEBPDF_MINIO_FILE_STORAGE_SETTINGS_USERNAME=minioadmin
WEBPDF_MINIO_FILE_STORAGE_SETTINGS_PASSWORD=minioadmin-secret
WEBPDF_MINIO_FILE_STORAGE_SETTINGS_BUCKET_NAME=webpdf-files

Health Checks

Health checks verify connectivity to MinIO and bucket accessibility:

{
  "fileStorage": {
    "name": "MINIO",
    "checks": {
      "enabled": true,
      "interval": 10000
    }
  }
}

enabled: Enable health checks (recommended: true)
interval: Check interval in milliseconds (recommended: 10000 - 30000)

Health Check Implementation

The health check performs a lightweight connectivity test:

Bucket Existence Check - Uses a HEAD request to check if the bucket exists
Connection Validation - Verifies network connectivity to MinIO endpoint
SSL Validation - Ensures SSL/TLS configuration is correct (for HTTPS endpoints)

What is checked:

Network connectivity to MinIO service
Bucket accessibility
SSL/TLS configuration validity

Health Status Results:

UP - Connection established, bucket accessible
DOWN - Connection failed, bucket not accessible, or SSL error

Note: The health check only verifies connectivity, not bucket creation. If the bucket doesn't exist, automatic creation is attempted during storage initialization.

Security Considerations

Authentication

MinIO uses access key and secret key authentication:

username: access-key-id
password: secret-access-key

TLS/SSL Configuration

For HTTPS connections:

url: https://minio.example.com:9000
username: access-key
password: secret-key
settings:
  region: us-east-1

IAM Policies

Configure MinIO IAM policies for least privilege access:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::webpdf-files/*",
        "arn:aws:s3:::webpdf-files"
      ]
    }
  ]
}

warning

Never store MinIO credentials in configuration files. Use environment variables or secure configuration management.

Bucket Management

Automatic Bucket Creation

If the specified bucket doesn't exist, webPDF will attempt to create it automatically during storage initialization. The bucket name is automatically converted to lowercase and trimmed.

Bucket Naming Rules:

Must be lowercase (automatically converted)
Can contain letters, numbers, and hyphens
Must be between 3 and 63 characters
Must start and end with a letter or number
Follows AWS S3 bucket naming rules

Manual Bucket Creation

Using MinIO Client (mc):

mc alias set myminio http://minio.example.com:9000 accesskey secretkey
mc mb myminio/webpdf-files
mc policy set download myminio/webpdf-files

Bucket Lifecycle Policies

Configure lifecycle policies for automatic cleanup:

<LifecycleConfiguration>
  <Rule>
    <ID>DeleteOldFiles</ID>
    <Status>Enabled</Status>
    <Expiration>
      <Days>30</Days>
    </Expiration>
  </Rule>
</LifecycleConfiguration>

High Availability

For production deployments:

Distributed MinIO – Multi-node MinIO cluster with erasure coding
Load Balancing – Distribute requests across MinIO nodes
Replication – Site-to-site bucket replication
Backup – Regular bucket snapshots

Distributed Setup Example

# 4-node distributed MinIO
minio server http://minio{1...4}.example.com/data{1...4}

Performance Tuning

MinIO Server Optimization

# Environment variables
export MINIO_CACHE_SIZE=10GB
export MINIO_CACHE_DRIVES="/mnt/cache1,/mnt/cache2"

Built-in Connection Management

The MinIO provider includes two optimized HTTP client configurations:

Default Client (Standard Operations)

Connection Pool: 50 connections, 5-minute keep-alive
Connect Timeout: 5 seconds
Read/Write Timeout: 10 seconds
Call Timeout: 15 seconds
Retry on Failure: Enabled
Keepalive Ping: 15 seconds (detects and evicts half-open connections; configurable)
Use Case: Regular file operations (get, put, delete)

Streaming Client (Large File Operations)

Connection Pool: Isolated (no connection reuse)
Connect Timeout: 10 seconds
Read/Write Timeout: 5 minutes
Call Timeout: 10 minutes
Retry on Failure: Disabled (handled by retry policy)
Use Case: Long-running uploads/downloads

Connection Resilience and Self-Healing

After a short network or storage disruption (for example a load balancer failover, a firewall idle-timeout, or a brief MinIO/S3 outage), pooled HTTP connections can be left in a broken or half-open state. Reusing such connections would otherwise cause every retry to fail on the same poisoned pool, and recovery would require restarting the affected node.

The MinIO provider recovers from these situations automatically:

Keepalive ping — The default client sends periodic HTTP pings (default 15 seconds). Half-open connections are detected and evicted from the pool instead of being reused under load.
Connection-pool rebuild on transient failures — When a retry is triggered by a transient transport failure (connection reset, broken pipe, socket timeout, premature end of stream), the client rebuilds its connection pool once before retrying. The next attempt uses fresh connections, so the node recovers without a restart.
Connection-pool rebuild on TLS trust changes — The same rebuild mechanism applies when the external TLS certificate material changes (see TLS/SSL configuration above).
Rebuild throttling — A cooldown prevents a rebuild storm when many threads fail at the same time; only one rebuild happens per cooldown window.

After such an event, the server log records a connection refresh (for example Refreshed client state after standard failure ... and Rebuilt MinIO client ...), confirming the self-healing without manual intervention.

note

A genuine application-level error such as a real Object does not exist (HTTP 404) is not treated as a transient transport failure and does not trigger a pool rebuild.

Client Runtime Settings

These settings tune the MinIO HTTP client behavior. They are configured as webPDF environment settings under the webpdf.minio.client.* namespace and apply across all MinIO operations. The defaults are suitable for most deployments.

Environment variable	System property	Default	Description
`WEBPDF_MINIO_CLIENT_PING_INTERVAL`	`webpdf.minio.client.ping.interval`	`15000`	Keepalive ping interval in milliseconds for the default client. A value `> 0` enables active probes that detect and evict half-open connections; `0` disables pings.
`WEBPDF_MINIO_CLIENT_FORCED_REFRESH_COOLDOWN`	`webpdf.minio.client.forced.refresh.cooldown`	`5000`	Minimum interval in milliseconds between forced connection-pool rebuilds (transient transport failures and TLS trust changes). Prevents rebuild storms under concurrent failures.
`WEBPDF_MINIO_CLIENT_CERTIFICATE_POLL_INTERVAL`	`webpdf.minio.client.certificate.poll.interval`	`60000`	Polling interval in milliseconds for detecting changes to the external TLS certificate file.
`WEBPDF_MINIO_CLIENT_TLS_CERT_FILE`	`webpdf.minio.client.tls.cert.file`	-	Path to an external certificate file used for TLS trust material. When unset, the JVM truststore is used.
`WEBPDF_MINIO_CLIENT_PART_SIZE`	`webpdf.minio.client.part.size`	`5242880`	Multipart transfer part size in bytes (default 5 MiB) for streaming uploads.
`WEBPDF_MINIO_CLIENT_SHUTDOWN_TIMEOUT`	`webpdf.minio.client.shutdown.timeout`	`20000`	Timeout in milliseconds for releasing client resources during shutdown or a pool rebuild.

tip

In containerized deployments, supply secrets such as the TLS certificate path using the file: resolver (WEBPDF_MINIO_CLIENT_TLS_CERT_FILE=file:/run/secrets/minio_ca), so the value is read from a mounted secret file.

Automatic Retry Policy

Retry configuration for transient failures:

Max Attempts: 5 retries
Strategy: Exponential backoff
Initial Delay: 500ms
Max Delay: 30 seconds
Jitter: Enabled (randomized delays)

This handles network hiccups and temporary MinIO unavailability automatically.

Batch Processing

For efficient bulk operations:

Batch Size: 1000 objects
Use Case: Deleting multiple files in a single request
Benefit: Reduces API calls and improves performance

File Caching

ETag-based caching mechanism:

Local Cache - Files are cached locally after download
ETag Validation - ETags and file sizes are compared before re-downloading
Automatic Invalidation - Cache is updated when ETags don't match or file size differs
Consistency Check - File size verification ensures complete uploads/downloads

Network Optimization

Use dedicated network for storage traffic
Enable jumbo frames (MTU 9000) if supported
Co-locate webPDF and MinIO in same data center/region

Monitoring

MinIO Metrics

Monitor MinIO health and performance:

# MinIO metrics endpoint
curl http://minio.example.com:9000/minio/v2/metrics/cluster

Key Metrics

Request rate (GET/PUT operations)
Response time (latency)
Bandwidth utilization
Error rate
Storage capacity

Troubleshooting

Cannot Connect to MinIO

Verify MinIO is running: curl http://minio.example.com:9000/minio/health/live
Check network connectivity
Verify access credentials
Check firewall rules (port 9000)

Bucket Not Found

Verify bucket exists: mc ls myminio/
Check bucket name matches configuration
Verify access permissions
Enable automatic bucket creation

Slow Upload/Download

Check network bandwidth
Review MinIO server performance
Consider distributed MinIO setup
Check file size - large files automatically use streaming client
Review retry attempts in logs

Access Denied Errors

Verify access key and secret key
Check IAM policy permissions
Review bucket policies
Verify bucket ownership

AWS S3 Compatibility

MinIO provider works with AWS S3 and S3-compatible services:

AWS S3 Configuration

url: https://s3.amazonaws.com
username: AWS_ACCESS_KEY_ID
password: AWS_SECRET_ACCESS_KEY
bucketName: webpdf-files
settings:
  region: us-east-1

Examples

Basic MinIO Setup

url: http://192.168.1.100:9000
username: webpdf-user
password: secure-password
bucketName: webpdf-files

MinIO with TLS

url: https://minio.example.com:9000
username: webpdf-user
password: secure-password
bucketName: webpdf-files-prod
settings:
  region: us-east-1

AWS S3

url: https://s3.eu-central-1.amazonaws.com
username: AKIAIOSFODNN7EXAMPLE
password: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
bucketName: my-webpdf-bucket
settings:
  region: eu-central-1

Overview​

Features​

Prerequisites​

Configuration​

provider.json​

provider-minio.yaml​

Configuration Attributes​

Required Attributes​

Optional Attributes​

Settings Object​

Bucket Naming​

Environment Variables​

Health Checks​

Health Check Implementation​

Security Considerations​

Authentication​

TLS/SSL Configuration​

IAM Policies​

Bucket Management​

Automatic Bucket Creation​

Manual Bucket Creation​

Bucket Lifecycle Policies​

High Availability​

Distributed Setup Example​

Performance Tuning​

MinIO Server Optimization​

Built-in Connection Management​

Default Client (Standard Operations)​

Streaming Client (Large File Operations)​

Connection Resilience and Self-Healing​

Client Runtime Settings​

Automatic Retry Policy​

Batch Processing​

File Caching​

Network Optimization​

Monitoring​

MinIO Metrics​

Key Metrics​

Troubleshooting​

Cannot Connect to MinIO​

Bucket Not Found​

Slow Upload/Download​

Access Denied Errors​

AWS S3 Compatibility​

AWS S3 Configuration​

Examples​

Basic MinIO Setup​

MinIO with TLS​

AWS S3​