redis-pvxs-ioc

redis-pvxs-ioc is a standalone PVAccess service for hot-reloadable, Redis-backed EPICS process variables defined by YAML.

Key features

• Generation-based hot reload: reload through SIGHUP or a PVA command; compatible Redis subscriptions stay live, changed PVs are staged, and invalid replacements are rejected while the active generation keeps serving.
• Optional native ACF security: explicitly enabled EPICS access policy protects Redis PVs, RPCs, and admin endpoints with dedicated, whole-config, or settled file-watcher reload while leaving monitor fan-out untouched.
• Collision-aware preflight: --check-config resolves final PV names and routes without starting Redis or PVA, rejecting duplicate PV names, reserved version/revision aliases, unknown backends, and conflicting read/confirm subscriptions within a backend.
• Shared-runtime aliases: each Redis-backed PV may expose additional, fully-qualified PVA names without adding Redis subscriptions or duplicating confirmed writes.
• Built-in diagnostics: always-on PVA endpoints report version, source revision, config generation/status/error, configured PV count, and Redis backend health.
• Snapshot-plus-stream reads: each PV opens from the latest Redis value, or its YAML initial fallback, before live subscription updates take over; Redis source timestamps are carried into PVA.
• Confirmed Redis writes: scalar and array routes may use independent read, write, and confirmation keys across multiple backends; readback matching has a bounded timeout, and stale-generation operations are fenced during reload.
• Operator-ready PVA values: NTScalar and NTScalarArray values include alarm, timestamp, display, control, units, precision, and limit metadata.
• Alarm de-chattering and engineering units: numeric thresholds support hysteresis, Redis alarm events are emitted only on state/severity transitions, and linear transforms map reads forward and writes back through the inverse.
• Dynamic integrations: one-shot ChannelFinder publishing and reflection-based PVA RPC to gRPC forwarding without service-specific generated code in the IOC.
• Container tooling: released images include pvxget, pvxput, and other PVXS tools for validation and troubleshooting.

The core runtime is PVA-only. It does not load EPICS databases, call iocInit(), or serve Channel Access.

Quick start

The registry images allow anonymous pulls:

git clone https://github.com/fermi-ad/redis-pvxs-ioc.git
cd redis-pvxs-ioc
docker compose pull
docker compose up -d

Validate the demo from inside the IOC container:

PV_ENV='EPICS_PVA_AUTO_ADDR_LIST=NO EPICS_PVA_ADDR_LIST=127.0.0.1'
PVX=/opt/redis-pvxs-ioc/bin/pvxs

docker exec redis-pvxs-ioc-demo sh -lc \
  "$PV_ENV $PVX/pvxget SYS:demo:backend:health"
docker exec redis-pvxs-ioc-demo sh -lc \
  "$PV_ENV $PVX/pvxget DEMO:source:temperature"
docker exec redis-pvxs-ioc-demo sh -lc \
  "$PV_ENV $PVX/pvxput DEMO:magnet:current 9.0"

Stop the demo with docker compose down.

The default stack uses a private Docker bridge and is intended for local validation. See PVAccess networking before deploying on a controls network.

Built-in operational PVs

These PVs are always created from server.instance; they do not use server.namespace.

PV	Access	Purpose
<instance>:version	read	Release version
<instance>:revision	read	Embedded Git revision
SYS:<instance>:version	read	Version alias
SYS:<instance>:revision	read	Revision alias
SYS:<instance>:config:reload	write	Request a config reload
SYS:<instance>:config:generation	read	Active config generation
SYS:<instance>:config:lastStatus	read	Last config/app status
SYS:<instance>:config:lastError	read	Last config/app error
SYS:<instance>:stats:pvCount	read	Configured runtime and RPC PV count
SYS:<instance>:backend:health	read	Connected Redis backend summary
SYS:<instance>:access:*	read/write	ACF reload, status, generation, fingerprint, and counters

See Operations and diagnostics for reload guarantees and verification commands.

Configure and deploy

The released image reads /etc/redis-pvxs-ioc/config.yaml. Start with demo/config.yaml, validate it before serving, and mount the deployment-owned file read-only:

REDIS_PVXS_IOC_CONFIG=/absolute/path/to/config.yaml \
  docker compose run --rm --no-deps ioc \
  --check-config /etc/redis-pvxs-ioc/config.yaml

REDIS_PVXS_IOC_CONFIG=/absolute/path/to/config.yaml docker compose up -d

Production deployments should consume the published image by semver tag and immutable digest. :latest is only a development convenience. See the Redis-only adoption guide and complete configuration reference.

Documentation

• Documentation index
• Configuration reference
• Operations and diagnostics
• Access control
• Performance measurement
• Architecture
• Current feature state and roadmap
• Building from source
• Contributor development guide
• Release process

Optional legacy sidecar

An independently versioned conventional IOC sidecar is available for .db records, RecCaster, and selected support modules. It is experimental and is not part of the core quick start while its long-term product boundary is decided in issue #68. See the legacy sidecar guide for the current image and limits.

License

Project-authored code is available under the BSD 3-Clause License. The contract and government-rights terms are retained in NOTICE. See Third-Party Notices for bundled dependencies and their license locations.