Provider configuration (provider.json)

This page describes the structure, attributes, and configuration of the provider.json file for operating various storage providers in webPDF Server in a cluster environment. Storage providers manage where and how documents, files, and sessions are stored.

Purpose

With provider.json, you control which storage backend is used for three types of data:

• Document Storage – Stores processed documents and their metadata
• File Storage – Stores uploaded and temporary files
• Session Storage – Stores user session data

Each storage type can be configured independently with different providers, allowing flexible architecture configurations.

Available Providers

webPDF Server supports the following storage providers:

• LOCAL – Local filesystem storage (default) or NFS network shares for files
• REDIS – Redis in-memory data store for documents and sessions
• VALKEY – Valkey (Redis-compatible) in-memory data store for documents and sessions
• MINIO – MinIO S3-compatible object storage for files
• AZURE_BLOB – Microsoft Azure Blob Storage for files
• SMB – SMB/CIFS network file shares for files

note

NFS (Network File System) support is provided through the LOCAL provider with sharedUsage: true configuration. See NFS Provider for details.

info

For detailed configuration of each provider, see the individual provider documentation pages linked below.

Structure

The provider.json is a JSON object with three main sections:

Important

The provider.json file is required for cluster deployments and must always contain a configuration entry for each storage type (documentStorage, fileStorage, and sessionStorage).

{
  "documentStorage": {
    "name": "provider-name",
    "checks": { ... }
  },
  "fileStorage": {
    "name": "provider-name",
    "checks": { ... }
  },
  "sessionStorage": {
    "name": "provider-name",
    "checks": { ... }
  }
}

Each section has the following attributes:

• name: string – The provider type identifier (required)
• checks: object – Health check configuration (optional)

Health Checks (checks)

Each provider can be configured with health checks to monitor availability:

• enabled: boolean – Enable/disable health checks (default: false)
• interval: number – Check interval in milliseconds (default: 10000)

Provider Configuration Files

Each provider requires a separate configuration file with provider-specific settings. The configuration files follow this naming pattern:

• LOCAL/NFS: provider-local.json (optional for default local, required for NFS)
• Redis (documents): provider-redis.yaml
• Redis (sessions): provider-redis.yaml
• Valkey (documents): provider-valkey.yaml
• Valkey (sessions): provider-valkey.yaml
• MinIO: provider-minio.json
• Azure Blob: provider-azure-blob.json
• SMB: provider-smb.json

tip

Configuration files are referenced by the provider but managed separately. This allows for cleaner separation of concerns and easier credential management.

Examples

Default (LOCAL)

{
  "documentStorage": {
    "name": "LOCAL"
  },
  "fileStorage": {
    "name": "LOCAL"
  },
  "sessionStorage": {
    "name": "LOCAL"
  }
}

Redis + MinIO

{
  "documentStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  },
  "fileStorage": {
    "name": "MINIO",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  },
  "sessionStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  }
}

Valkey + Azure Blob

{
  "documentStorage": {
    "name": "VALKEY",
    "checks": {
      "enabled": true,
      "interval": 10000
    }
  },
  "fileStorage": {
    "name": "AZURE_BLOB",
    "checks": {
      "enabled": true,
      "interval": 10000
    }
  },
  "sessionStorage": {
    "name": "VALKEY",
    "checks": {
      "enabled": true,
      "interval": 10000
    }
  }
}

SMB File Storage

{
  "documentStorage": {
    "name": "LOCAL"
  },
  "fileStorage": {
    "name": "SMB",
    "checks": {
      "enabled": true,
      "interval": 15000
    }
  },
  "sessionStorage": {
    "name": "LOCAL"
  }
}

NFS File Storage

{
  "documentStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  },
  "fileStorage": {
    "name": "LOCAL",
    "checks": {
      "enabled": true,
      "interval": 15000
    }
  },
  "sessionStorage": {
    "name": "REDIS",
    "checks": {
      "enabled": true,
      "interval": 5000
    }
  }
}

note

For NFS, use LOCAL provider with provider-local.json containing "sharedUsage": true and NFS mount path.

Environment Variables

Provider settings can be overridden via environment variables using the following patterns:

Document Storage

• WEBPDF_PROVIDER_SETTINGS_DOCUMENT_STORAGE_NAME – Provider name
• WEBPDF_PROVIDER_SETTINGS_DOCUMENT_STORAGE_CHECKS_ENABLED – Health checks enabled
• WEBPDF_PROVIDER_SETTINGS_DOCUMENT_STORAGE_CHECKS_INTERVAL – Health check interval

File Storage

• WEBPDF_PROVIDER_SETTINGS_FILE_STORAGE_NAME – Provider name
• WEBPDF_PROVIDER_SETTINGS_FILE_STORAGE_CHECKS_ENABLED – Health checks enabled
• WEBPDF_PROVIDER_SETTINGS_FILE_STORAGE_CHECKS_INTERVAL – Health check interval

Session Storage

• WEBPDF_PROVIDER_SETTINGS_SESSION_STORAGE_NAME – Provider name
• WEBPDF_PROVIDER_SETTINGS_SESSION_STORAGE_CHECKS_ENABLED – Health checks enabled
• WEBPDF_PROVIDER_SETTINGS_SESSION_STORAGE_CHECKS_INTERVAL – Health check interval

Provider Compatibility Matrix

Provider	Document Storage	File Storage	Session Storage
LOCAL	✓	✓	✓
LOCAL (NFS)	✗	✓	✗
REDIS	✓	✗	✓
VALKEY	✓	✗	✓
MINIO	✗	✓	✗
AZURE_BLOB	✗	✓	✗
SMB	✗	✓	✗

Provider Documentation

For detailed configuration instructions for each provider, see:

• LOCAL Provider – Local filesystem storage
• NFS Provider – NFS network file shares (LOCAL with shared usage)
• REDIS Provider – Redis in-memory data store
• VALKEY Provider – Valkey (Redis-compatible) data store
• MINIO Provider – MinIO S3-compatible object storage
• AZURE_BLOB Provider – Microsoft Azure Blob Storage
• SMB Provider – SMB/CIFS network file shares

Best Practices

1. Use health checks in production – Enable health checks with appropriate intervals to detect storage issues early
2. Separate concerns – Use different providers for different storage types based on your architecture needs
3. Secure credentials – Store provider configuration files with sensitive credentials outside version control
4. Test failover – Validate that your application handles provider failures gracefully
5. Monitor performance – Different providers have different performance characteristics; monitor and adjust accordingly

caution

When switching providers, existing data is not automatically migrated. Plan data migration carefully before changing provider configurations.