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.
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
| Attribute | Type | Description | Default |
|---|---|---|---|
address | string | Valkey server address (format: valkey://host:port) | - |
password | string | Valkey authentication password | null |
database | integer | Valkey database number (0-15) | 0 |
connectionPoolSize | integer | Connection pool size | 64 |
connectionMinimumIdleSize | integer | Minimum idle connections | 24 |
idleConnectionTimeout | integer | Idle connection timeout (ms) | 10000 |
connectTimeout | integer | Connection timeout (ms) | 10000 |
timeout | integer | Command timeout (ms) | 3000 |
retryAttempts | integer | Number of retry attempts | 3 |
retryInterval | integer | Retry interval (ms) | 1500 |
Cluster Server Settings
| Attribute | Type | Description | Default |
|---|---|---|---|
nodeAddresses | array | List of cluster node addresses | - |
password | string | Valkey authentication password | null |
scanInterval | integer | Cluster topology scan interval (ms) | 1000 |
readMode | string | Read mode: SLAVE, MASTER, MASTER_SLAVE | SLAVE |
subscriptionMode | string | Subscription mode: MASTER, SLAVE | MASTER |
natMapper | object | NAT mapping configuration for Docker/containerized deployments | - |
Sentinel Server Settings
| Attribute | Type | Description | Default |
|---|---|---|---|
masterName | string | Name of the master server | - |
sentinelAddresses | array | List of sentinel addresses | - |
password | string | Valkey authentication password | null |
database | integer | Valkey database number | 0 |
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 examplewebpdf-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
| Domain | Purpose | Example Keys |
|---|---|---|
session | Session management | <ns>:session:data:<sessionId> |
document | Document storage | <ns>:document:data:<sessionId>:<documentId> |
event | Event notifications | <ns>:event |
history | Document 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:
| Feature | Valkey | Redis |
|---|---|---|
| Protocol | ✓ Compatible | ✓ Native |
| License | BSD 3-Clause | SSPL/RSALv2 |
| Governance | Linux Foundation | Redis Ltd. |
| Features | ✓ All Redis features | ✓ Native |
| Performance | ✓ Equivalent | ✓ Equivalent |
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
- Authentication – Always use Valkey authentication (
requirepassin Valkey config) - TLS/SSL – Enable SSL for connections over untrusted networks
- Network Security – Use firewalls to restrict Valkey access
- Password Strength – Use strong, randomly generated passwords
- Database Separation – Use different database numbers for documents and sessions
Never store Valkey passwords in configuration files. Use environment variables or secure configuration management.
High Availability
For production deployments, consider:
- Valkey Sentinel – Automatic failover and monitoring
- Valkey Cluster – Horizontal scaling across multiple nodes
- Replication – Master-replica replication for read scaling
- 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:
2000milliseconds (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
codecin 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 level | When |
|---|---|
WARN | A 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. |
INFO | The start check finds every master on noeviction. |
INFO | The 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. |
ERROR | A 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. |
WARN | A 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.
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 setting | System property | Default | Description |
|---|---|---|---|
WEBPDF_REDIS_MEMORY_CHECK_INTERVAL | -Dwebpdf.redis.memory.check.interval | 60000 | Time 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.
| Field | Description |
|---|---|
cacheServer.provider | VALKEY |
cacheServer.checkedAt | Time of the last finished check in milliseconds since 1970-01-01T00:00:00Z. |
cacheServer.nodes[] | One entry per master. |
nodes[].address | Address of the master as host:port. |
nodes[].readable | true if the master answered the check and reported all three of the following values. Read the three values only when this is true. |
nodes[].maxMemoryPolicy | The maxmemory-policy as the server reports it. Every policy except noeviction is unsafe for webPDF. |
nodes[].maxMemory | The maxmemory limit in bytes; 0 means no limit. |
nodes[].evictedKeys | The 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
- Verify Valkey is running:
valkey-cli ping(orredis-cli ping) - Check network connectivity:
telnet valkey-host 6379 - Verify credentials are correct
- Check firewall rules
High Memory Usage
- Monitor Valkey memory:
valkey-cli info memory - Check that
evicted_keys(info stats) is0; keepmaxmemory-policy noeviction(see Valkey Server Configuration) - Review data retention policies
- Consider increasing Valkey server memory
Slow Response Times
- Check Valkey server load:
valkey-cli info stats - Monitor network latency
- Review slow log:
valkey-cli slowlog get 10 - Optimize connection pool settings
Migration
From REDIS to VALKEY
Migration between Redis and Valkey is seamless:
- Set up Valkey server
- Copy
provider-redis.yamltoprovider-valkey.yaml - Update protocol prefix from
redis://tovalkey://in addresses - Update
provider.jsonto useVALKEYinstead ofREDIS - Optional: Migrate data using
redis-cli --rdband restore to Valkey - 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