Skip to main content
Version: 10.0

VALKEY Provider

The VALKEY provider uses Valkey as an in-memory data store for documents and sessions. Valkey is a Redis-compatible open-source alternative maintained by the Linux Foundation, ideal for cluster deployments where multiple webPDF Server nodes need to share document metadata and session data.

Overview​

  • Provider Name: VALKEY
  • Supports: Document Storage, Session Storage
  • Configuration File: provider-valkey.yaml (Redisson configuration format)
  • Use Case: Cluster deployments, high-performance caching, distributed sessions
  • Compatibility: Fully compatible with Redis protocol and configuration

Features​

  • ✓ High-performance in-memory data store
  • ✓ 100% Redis protocol compatible
  • ✓ Open-source (BSD 3-Clause license)
  • ✓ Cluster-ready with shared state
  • ✓ Persistence options (RDB, AOF)
  • ✓ Replication and high availability support
  • ✓ Low latency access
  • ✓ Batch operations for optimized performance
  • ✓ Distributed locking with watchdog mechanism
  • ✓ Namespace-based key isolation
  • ✓ JSON serialization with Java time support
  • ✓ Connection health monitoring
  • ✓ Event manager integration for async operations
  • ✓ Session reconciliation and expiration processing
  • ✗ Limited by available RAM
  • ✗ Requires external Valkey server

Prerequisites​

  • Valkey server 7.2 or later (or Redis 6.0+)
  • Network connectivity from webPDF Server to Valkey
  • Valkey connection details (host, port, credentials)

Configuration​

provider.json​

{
"documentStorage": {
"name": "VALKEY",
"checks": {
"enabled": true,
"interval": 5000
}
},
"sessionStorage": {
"name": "VALKEY",
"checks": {
"enabled": true,
"interval": 5000
}
}
}

provider-valkey.yaml​

The configuration file uses the Redisson YAML format. Valkey is fully compatible with Redis protocol, so Redisson can be used seamlessly.

info

The provider-valkey.yaml file is a standard Redisson configuration file, not a webPDF-specific format. Use valkey:// protocol prefix in addresses. Refer to the Redisson documentation for all available configuration options.

Single Server Configuration​

For standalone Valkey servers:

singleServerConfig:
address: "valkey://localhost:6379"
password: "your-password"
database: 0
connectionPoolSize: 64
connectionMinimumIdleSize: 24
idleConnectionTimeout: 10000
connectTimeout: 10000
timeout: 3000
retryAttempts: 3
retryInterval: 1500

Cluster Configuration​

For Valkey Cluster deployments:

clusterServersConfig:
nodeAddresses:
- "valkey://valkey-node1:6379"
- "valkey://valkey-node2:6379"
- "valkey://valkey-node3:6379"
password: "your-password"
scanInterval: 1000
readMode: "SLAVE"
subscriptionMode: "MASTER"

NAT Mapper Configuration​

For cluster deployments with NAT (e.g., Docker):

clusterServersConfig:
nodeAddresses:
- "valkey://localhost:7001"
- "valkey://localhost:7002"
- "valkey://localhost:7003"
natMapper:
class: "org.redisson.api.HostNatMapper"
hostsMap:
"172.24.5.1": "localhost"
"172.24.5.2": "localhost"
"172.24.5.3": "localhost"

Sentinel Configuration​

For Valkey Sentinel high availability:

sentinelServersConfig:
masterName: "mymaster"
sentinelAddresses:
- "valkey://sentinel1:26379"
- "valkey://sentinel2:26379"
- "valkey://sentinel3:26379"
password: "your-password"
database: 0

Configuration Attributes​

Single Server Settings​

AttributeTypeDescriptionDefault
addressstringValkey server address (format: valkey://host:port)-
passwordstringValkey authentication passwordnull
databaseintegerValkey database number (0-15)0
connectionPoolSizeintegerConnection pool size64
connectionMinimumIdleSizeintegerMinimum idle connections24
idleConnectionTimeoutintegerIdle connection timeout (ms)10000
connectTimeoutintegerConnection timeout (ms)10000
timeoutintegerCommand timeout (ms)3000
retryAttemptsintegerNumber of retry attempts3
retryIntervalintegerRetry interval (ms)1500

Cluster Server Settings​

AttributeTypeDescriptionDefault
nodeAddressesarrayList of cluster node addresses-
passwordstringValkey authentication passwordnull
scanIntervalintegerCluster topology scan interval (ms)1000
readModestringRead mode: SLAVE, MASTER, MASTER_SLAVESLAVE
subscriptionModestringSubscription mode: MASTER, SLAVEMASTER
natMapperobjectNAT mapping configuration for Docker/containerized deployments-

Sentinel Server Settings​

AttributeTypeDescriptionDefault
masterNamestringName of the master server-
sentinelAddressesarrayList of sentinel addresses-
passwordstringValkey authentication passwordnull
databaseintegerValkey database number0

Environment Variables​

Since the configuration uses Redisson YAML format, environment variables can be used within the YAML file using standard YAML syntax:

singleServerConfig:
address: "valkey://${VALKEY_HOST:localhost}:${VALKEY_PORT:6379}"
password: "${VALKEY_PASSWORD}"
database: ${VALKEY_DATABASE:0}

Health Checks​

Health checks monitor Valkey connectivity and availability:

{
"documentStorage": {
"name": "VALKEY",
"checks": {
"enabled": true,
"interval": 5000
}
}
}
  • enabled: Enable health checks (recommended: true)
  • interval: Check interval in milliseconds (recommended: 5000 - 10000)

Namespace Support​

Valkey keys are automatically prefixed with the namespace of the cluster: <prefix>:v<main>.<minor>-r<revision> (for example webpdf-prod:v10.0-r1). It identifies the installation and its data format, so that several clusters and several versions of webPDF can share one Valkey without touching each other's data.

The key <namespace>:owner holds the owner of the namespace: a second cluster on the same namespace does not start (see One Namespace, One Cluster).

Key Structure​

Keys follow this pattern:

<namespace>:<domain>:<type>:<identifier>

Where:

  • namespace: <prefix>:v<main>.<minor>-r<revision>, for example webpdf-prod:v10.0-r1
  • domain: Key domain (session, document, event, history)
  • type: Key type (data, index, lock)
  • identifier: Unique ID (session ID, document ID, etc.)

Key Domains​

DomainPurposeExample Keys
sessionSession management<ns>:session:data:<sessionId>
documentDocument storage<ns>:document:data:<sessionId>:<documentId>
eventEvent notifications<ns>:event
historyDocument history<ns>:history:data:<sessionId>:<documentId>

Index Keys​

Index keys are used for listing and searching:

<namespace>:session:index
<namespace>:document:index:<sessionId>

<namespace>:document:index:<sessionId> lists the documents of one session and is removed together with the session. There is no index of all documents of the namespace.

Lock Keys​

Distributed locks use dedicated keys:

<namespace>:session:lock:<sessionId>
<namespace>:session:lock:principal:<hash>
<namespace>:session:lock:expiration
<namespace>:session:lock:reconciliation
<namespace>:document:lock:<sessionId>:<documentId>

See Namespace Configuration for more details on configuring namespaces.

All keys that webPDF writes lie under the namespace. In addition, Redisson derives the channel redisson_lock__channel:{<namespace>:…} and the key redisson_unlock_latch:{<namespace>:…}:<id> for every lock. A Valkey that several installations share needs the memory policy noeviction and enough maxmemory for all of them. For the rules for a shared Valkey, restricted access rights and emptying the area of a namespace, see Operating Rules.

Valkey vs Redis​

Valkey is a fork of Redis that maintains full protocol compatibility:

FeatureValkeyRedis
Protocol✓ Compatible✓ Native
LicenseBSD 3-ClauseSSPL/RSALv2
GovernanceLinux FoundationRedis Ltd.
Features✓ All Redis features✓ Native
Performance✓ Equivalent✓ Equivalent
tip

You can migrate from Redis to Valkey (or vice versa) without changing your webPDF configuration. Simply point to a different server and restart.

Security Considerations​

  1. Authentication – Always use Valkey authentication (requirepass in Valkey config)
  2. TLS/SSL – Enable SSL for connections over untrusted networks
  3. Network Security – Use firewalls to restrict Valkey access
  4. Password Strength – Use strong, randomly generated passwords
  5. Database Separation – Use different database numbers for documents and sessions
warning

Never store Valkey passwords in configuration files. Use environment variables or secure configuration management.

High Availability​

For production deployments, consider:

  1. Valkey Sentinel – Automatic failover and monitoring
  2. Valkey Cluster – Horizontal scaling across multiple nodes
  3. Replication – Master-replica replication for read scaling
  4. Persistence – Enable RDB or AOF for data durability

Performance Tuning​

Batch Operations​

The provider uses batch operations to optimize performance for multiple operations:

  • Batch Execution: Multiple Valkey commands are grouped and executed together
  • Reduced Latency: Minimizes network round trips
  • Atomic Operations: Batch operations are executed atomically
  • Use Case: Document retrieval, session cleanup, bulk operations

Distributed Locking​

Distributed locks ensure data consistency across cluster nodes:

  • Lock Timeout: 2000 milliseconds (default)
  • Lock Lease Time: -1 (watchdog enabled for automatic extension)
  • Lock Keys: Separate locks for sessions and documents
  • Global Locks: Used for expiration processing and reconciliation

The watchdog mechanism automatically extends lock lease time as long as the lock-holding thread is alive, preventing premature lock release.

Data Serialization​

JSON serialization with Java time support:

  • Format: JSON for the records of sessions and documents and for the event stream; plain text for the indexes and the revision counters
  • Codec: set by webPDF Server for every structure; a codec in the Redisson YAML does not affect the stored data
  • Benefits: Human-readable data, cross-platform compatibility
  • Types: Supports all Java time types (Instant, LocalDateTime, etc.)

Connection Health Monitoring​

Automatic connection monitoring:

  • Connection Listeners: Monitor connection status changes
  • Health Status: Real-time connection state tracking
  • Reconnection: Automatic reconnection on failure
  • Health Checks: Scheduled health check validation

Event Manager Integration​

Asynchronous event processing:

  • Async Operations: Non-blocking event notifications
  • Event Queue: Decoupled event processing
  • Performance: Operations don't wait for event processing
  • Use Case: Notifications, logging, monitoring

Session Management​

Advanced session handling:

  • Session Reconciliation: Periodic consistency checks across cluster
  • Expiration Processing: Automated cleanup of expired sessions
  • Session ID Generation: Random 128-bit IDs (32 hexadecimal characters) that the server assigns itself, independent of any token
  • Session Table: Maintains session metadata and state

Valkey Server Configuration​

# valkey.conf optimizations
maxmemory 4gb
maxmemory-policy noeviction
tcp-backlog 511
timeout 300
tcp-keepalive 60

Use maxmemory-policy noeviction. Valkey holds the sessions, the document records and the deletion events of the cluster. With an eviction policy such as allkeys-lru it silently deletes keys when it reaches maxmemory: users lose their sessions, documents disappear, and deletions can leave content behind in the document storage. With noeviction a full Valkey rejects new writes instead, and the affected requests fail with an error of the document or session storage rather than losing data unnoticed. Size maxmemory for the peak number of sessions and documents, and monitor the memory use (info memory) and the evicted keys (evicted_keys in info stats), which must stay 0.

Checks by webPDF Server. webPDF Server reads the memory status of Valkey when it starts and then every 60 seconds, without any setting. The check only reads (INFO memory and INFO stats) and changes nothing on Valkey. It covers every master: all masters of a cluster, the current master of a Sentinel setup, and the master of a single, master/replica or replicated setup. Replicas are not read. The first check runs in the background, so it neither delays the start of webPDF Server nor stops it when Valkey cannot be read.

Log levelWhen
WARNA master reports a maxmemory-policy other than noeviction (allkeys-*, volatile-* or a policy that is not known yet). The line names each such master with its policy and maxmemory. It is written once per check; after the start check only when the policy of a master changes to such a value. Under a volatile-* policy Valkey deletes the keys with an expiry first, among them all locks.
INFOThe start check finds every master on noeviction.
INFOThe memory status of a master cannot be read (INFO renamed or not permitted, no answer within 5 seconds), and when it can be read again. webPDF Server keeps running; check the policy of Valkey yourself. The check needs the permission for the INFO command; without it, set WEBPDF_REDIS_MEMORY_CHECK_INTERVAL to 0 to stop the repeated attempts, and monitor Valkey outside webPDF Server.
ERRORA master evicted keys since the last report. At most one line per minute, with the number of keys and the number per master. Data of webPDF Server may be among them (sessions, documents, locks). The counter covers all keys of Valkey, also those of other applications.
WARNA lock was no longer held when webPDF Server released it, because it expired or Valkey evicted it. Mutual exclusion was not guaranteed for that one operation. The result of the operation is reported as usual.

If a master restarts, fails over, or is reset with CONFIG RESETSTAT, the counting continues from the new value of that master without an alarm.

note

Managed services often preset an evicting policy: the node-based clusters of Amazon ElastiCache use volatile-lru by default. Set noeviction in a parameter group of the cluster. Amazon ElastiCache Serverless fixes volatile-lru; there the start warning is written at every start, and the ERROR line and the metric cache_server_evicted_keys_total (see Metrics Reference) are your monitoring.

Environment settings. The interval is the only setting. It has no XML configuration and no Admin Portal dialog.

Environment settingSystem propertyDefaultDescription
WEBPDF_REDIS_MEMORY_CHECK_INTERVAL-Dwebpdf.redis.memory.check.interval60000Time between two checks in milliseconds. 0 or less switches the running check off: the start check still runs, but there is no ERROR line for evicted keys, the metric does not rise, and the cluster status is not updated. A value from 1 to 999 is raised to 1000 with a warning. The prefix webpdf.redis applies to Valkey as well.

To go back to the default, remove the setting and restart webPDF Server. Environment settings take precedence over the defaults.

Cluster status. The cluster status of the Admin REST interface (GET /admin/cluster/status) shows the result of the last check as the optional field cacheServer. It is missing when no storage provider uses Valkey and until the first check has finished. Every server node reads Valkey itself, so the field shows the view of the node that answers the request.

FieldDescription
cacheServer.providerVALKEY
cacheServer.checkedAtTime of the last finished check in milliseconds since 1970-01-01T00:00:00Z.
cacheServer.nodes[]One entry per master.
nodes[].addressAddress of the master as host:port.
nodes[].readabletrue if the master answered the check and reported all three of the following values. Read the three values only when this is true.
nodes[].maxMemoryPolicyThe maxmemory-policy as the server reports it. Every policy except noeviction is unsafe for webPDF.
nodes[].maxMemoryThe maxmemory limit in bytes; 0 means no limit.
nodes[].evictedKeysThe evicted_keys counter of the master since its start or since CONFIG RESETSTAT; it must stay 0.

If readable is false, the fields maxMemoryPolicy, maxMemory and evictedKeys are left out. Clients that fill a missing field with a default value (for example 0) must therefore check readable first. evictedKeys is the counter of Valkey itself: after an eviction it stays above 0 until Valkey restarts or CONFIG RESETSTAT resets it. The metric cache_server_evicted_keys_total counts differently: every server node counts the evictions it observed since its own start.

Connection Pool Tuning​

Adjust pool settings in the Redisson configuration based on load:

singleServerConfig:
address: "valkey://localhost:6379"
connectionPoolSize: 256
connectionMinimumIdleSize: 64
subscriptionConnectionPoolSize: 50
subscriptionConnectionMinimumIdleSize: 10
idleConnectionTimeout: 10000
connectTimeout: 10000
timeout: 3000

Troubleshooting​

Cannot Connect to Valkey​

  1. Verify Valkey is running: valkey-cli ping (or redis-cli ping)
  2. Check network connectivity: telnet valkey-host 6379
  3. Verify credentials are correct
  4. Check firewall rules

High Memory Usage​

  1. Monitor Valkey memory: valkey-cli info memory
  2. Check that evicted_keys (info stats) is 0; keep maxmemory-policy noeviction (see Valkey Server Configuration)
  3. Review data retention policies
  4. Consider increasing Valkey server memory

Slow Response Times​

  1. Check Valkey server load: valkey-cli info stats
  2. Monitor network latency
  3. Review slow log: valkey-cli slowlog get 10
  4. Optimize connection pool settings

Migration​

From REDIS to VALKEY​

Migration between Redis and Valkey is seamless:

  1. Set up Valkey server
  2. Copy provider-redis.yaml to provider-valkey.yaml
  3. Update protocol prefix from redis:// to valkey:// in addresses
  4. Update provider.json to use VALKEY instead of REDIS
  5. Optional: Migrate data using redis-cli --rdb and restore to Valkey
  6. Restart webPDF Server

Examples​

Basic Single Server Setup​

singleServerConfig:
address: "valkey://localhost:6379"

Valkey with Authentication​

singleServerConfig:
address: "valkey://valkey.example.com:6379"
password: "secure-password"
database: 0
connectionPoolSize: 64
connectionMinimumIdleSize: 24

Valkey with SSL/TLS​

singleServerConfig:
address: "valkeys://valkey.example.com:6380"
password: "secure-password"
database: 0
sslEnableEndpointIdentification: true

Valkey Cluster Configuration​

clusterServersConfig:
nodeAddresses:
- "valkey://valkey-node1:6379"
- "valkey://valkey-node2:6379"
- "valkey://valkey-node3:6379"
password: "secure-password"
scanInterval: 1000
readMode: "SLAVE"
subscriptionMode: "MASTER"

Valkey Cluster with NAT Mapper (Docker)​

clusterServersConfig:
nodeAddresses:
- "valkey://localhost:7001"
- "valkey://localhost:7002"
- "valkey://localhost:7003"
natMapper:
class: "org.redisson.api.HostNatMapper"
hostsMap:
"172.24.5.1": "localhost"
"172.24.5.2": "localhost"
"172.24.5.3": "localhost"

Valkey Sentinel Configuration​

sentinelServersConfig:
masterName: "mymaster"
sentinelAddresses:
- "valkey://sentinel1.example.com:26379"
- "valkey://sentinel2.example.com:26379"
- "valkey://sentinel3.example.com:26379"
password: "secure-password"
database: 0