Why TechDocs caching matters when docs live in remote storage
Caching keeps repeat reads of TechDocs content close to the Backstage backend, so pages open faster when the generated site sits in remote object storage. Teams need it when readers feel slow page loads and the storage bucket is in a different region, network zone or provider from the Backstage deployment. The TechDocs architecture guidance notes that latency can be high depending on where the storage is located, and it suggests caching responses in a supported cache store as the remedy. Check the storage location against your Backstage backend first, because a bucket in the same region often needs less help than one reached across a wide-area link.
TechDocs caching covers the responses the Backstage backend returns when it serves docs, so repeated requests for the same content can be answered from the cache instead of fetching it again from storage. Backstage supports Redis, Memcache, Infinispan or in-memory caching through its cache configuration, and the cache store you pick sets the operational work you take on. An in-memory cache is simple but is local to each backend instance, so it does not share hits across replicas. A shared store such as Redis needs its own hosting, sizing, high availability and patching. Ask your platform team which store already runs under support before you choose.
Caching does not replace the work that makes the source site fast to publish and fast to fetch. It does not fix oversized sites, missing assets, or slow generation in CI, and it does not change who may read a page, which remains a catalog permission question. It also does not remove the need to refresh content: when docs change, confirm that your cache lifetime and invalidation behavior match your publishing schedule, so readers do not see stale pages for longer than you expect. Review the setting with the owners of your TechDocs storage before rollout.
Which cache store fits your Backstage deployment
Backstage names four supported cache options: in-memory caching, Redis, Memcache and Infinispan. The right choice depends less on raw speed than on how many backend instances you run, whether cached data must survive a restart, and which software your legal and security teams have already approved. Treat the cache as a shared dependency of the Backstage backend, not as a local detail of one pod.
- In-memory caching: Simplest to start with, but each backend instance keeps its own copy, so cache hits differ between replicas and entries are lost on restart.
- Redis: A widely deployed shared store that several backend instances can use together. Its license depends on the version you pick (see the next tabs).
- Memcache: A shared, memory-only store. Confirm with your platform team that it fits your monitoring and high availability standards before choosing it.
- Infinispan: A Java-based data grid. It fits organizations that already run it, but adds a new operational surface if they do not.
- Decision inputs: Replica count, restart tolerance, existing approved software and staff familiarity.
Before you commit, confirm with your Backstage team which cache backend your current configuration expects, and whether your replicas must share cached TechDocs responses.
Redis licensing changed across release lines, so the version number you install determines which terms apply. The Redis licenses page describes three groups. Redis 8.0 and later can be used under a license of your choice among RSALv2, SSPLv1 and AGPLv3, and the Redis licenses page says the project plans to keep Redis Open Source under AGPLv3. Redis 7.4.x through 7.8.x remain under the dual RSALv2 or SSPLv1 license, which are not OSI-approved. Redis 7.2.x and earlier remain under BSD-3-Clause.
- Redis 8 and later: Redis 8.0.0 was published on May 2, 2025, and the AGPLv3 option is available within this line.
- Redis 7.4.x to 7.8.x: Dual RSALv2 or SSPLv1 terms, neither OSI-approved. Review these with counsel before adopting them.
- Redis 7.2.x and earlier: BSD-3-Clause, the most permissive of the three groups.
- Network service terms: The Redis licenses FAQ says teams offering modified Redis code as a network service must make the modified source available to that service's users.
- Trademark and product names: Redis Software and Redis Cloud are commercial products and are not open source.
Confirm the exact license for the version you plan to deploy with your legal team, and record the decision in your architecture documentation.
Valkey is a fork of open-source Redis, created just before Redis moved to source-available licenses. It is licensed under BSD-3-Clause and is an open community project under LF Projects, LLC, with the Linux Foundation holding the Valkey trademarks. For teams that want a BSD-3-Clause store with a Redis-compatible client, Valkey is a candidate to evaluate alongside Redis 8 under AGPLv3.
- Client compatibility: The Valkey migration guide says existing Redis client libraries connect to Valkey without code changes, and that Valkey is compatible with Redis OSS 7.2 and earlier open-source versions.
- Release lines: Valkey 9.0.0 was published on October 21, 2025. The current stable line is 9.1, with 9.1.2 published on September 1, 2026, according to the valkey-io/valkey releases page.
- Maintained branches: Several release lines receive updates at the same time, including 8.0.11 and 7.2.14, which helps when you need a patch line that matches your upgrade schedule.
- Migration boundary: The guide warns that Redis Community Edition 7.4 and later produce data files that are not compatible with Valkey, so those migrations need a different method that the guide does not cover.
- Sentinel: Valkey Sentinel provides high availability without Valkey Cluster, and the Valkey docs recommend at least three Sentinel instances.
Confirm Backstage's supported client behavior against the Valkey version you select, and test the cache path in a non-production environment first.
Once several backend replicas share TechDocs responses, the cache becomes a single point to design around. Redis Sentinel provides automatic failover by promoting a replica to master when you do not use Redis Cluster, and the Redis docs say a robust deployment needs at least three Sentinel instances. Valkey Sentinel follows the same pattern. In-memory caching avoids this network dependency but cannot give replicas a shared view of cached data.
- Replica sharing: Shared stores (Redis, Valkey, Memcache, Infinispan) let every backend replica read the same cached entries.
- Failover design: Sentinel-style failover needs at least three Sentinel instances, placed so one node failure does not remove quorum.
- Operating platforms: Redis Software and Redis Cloud are commercial options for teams that need vendor-run support, while Redis Open Source and Valkey are self-operated.
- Platform support: Redis Open Source runs on Linux, macOS and BSD systems, and on Windows only through Docker, per the Redis install page. Confirm this against your server estate.
- Failure behavior: Decide whether TechDocs should fall back to storage when the cache is unavailable, and test that path.
Ask your platform team to document the failover tests and the cache's monitoring before go-live.
What to cache and what to leave uncached
The responses worth caching are the ones that stay the same between publishes and are requested often: the rendered HTML pages and static assets that TechDocs serves from the storage bucket. A page that has not changed since the last CI publish can be served from cache for as long as the publish cycle allows, and that is where the latency gain comes from when the bucket sits in a distant region. Metadata lookups for a docs site, such as the list of available files or the build timestamp, are also stable between builds. Everything that depends on who is asking should stay out of a shared cache, and you should confirm with your Backstage version which TechDocs routes the backend exposes before you decide on a rule for each one.
Cache expiry has to follow the publish cycle in CI, not a fixed clock. If a TechDocs build publishes new HTML and the cache still returns the old page for an hour, readers see stale documentation that the team believes is current. Key entries by the entity and the content version so a new publish naturally produces new keys, or invalidate the entity's keys as the last step of the publish job. Check the cache key scheme against how techdocs-cli publishes, and test with two consecutive publishes of the same entity, confirming the second one is visible immediately. Short time-to-live values are a fallback, not the main mechanism, because they still allow a window of stale reads after each publish.
Access-controlled documentation needs the strictest handling. If the cache key does not include the requesting user's identity or the permission decision, one reader's response can be served to someone who should not see it. Treat any response that depends on catalog read permissions as uncached in a shared store unless the key includes the identity that was authorized, and confirm how your Backstage version applies permission checks to TechDocs routes before enabling caching for them. Sign-in and authorization changes also need a plan: a user removed from a group must not keep reading cached pages. The Backstage authentication documentation is the right starting point for how identities resolve, and a test with two users of different permission levels should be part of the rollout.
Cache configuration options and when each fits
This table compares the four cache options Backstage supports for TechDocs response caching: in-memory, Redis, Memcache and Infinispan. Read each row against how many backend replicas you run, whether cached entries must survive a restart, and how much cache infrastructure your team is willing to operate. Confirm the exact configuration keys in the Backstage cache documentation for your version before you commit.
| Option | Operational burden | Shared across backend replicas | Fit for TechDocs caching |
|---|---|---|---|
| In-memory | Lowest, since it runs inside the backend process with no extra service | No, each replica keeps its own cache | Single-replica or development setups where cold starts after restarts are acceptable |
| Redis | Moderate, requires a running Redis service and monitoring of its memory use | Yes, all replicas read and write the same store | Common choice for multi-replica production when you want one shared cache with familiar tooling |
| Memcache | Moderate, requires a Memcached service with its own capacity planning | Yes, all replicas share the same cache pool | Fits production when your team already runs Memcached and only needs simple key-value caching |
| Infinispan | Highest of the four, since it is a distributed data grid with its own clustering model | Yes, through its clustered data grid | Fits organizations that already operate Infinispan or need its clustering features for other workloads |
| Persistence across restarts | Depends on the store, confirm whether your chosen option is configured to persist data | Not applicable to in-memory, which is lost when the process restarts | Cached TechDocs responses can be rebuilt from storage, so persistence is a convenience rather than a requirement |
| Eviction and sizing | Set a memory limit and eviction policy that match the size of your docs catalog | Shared stores need one limit that covers all replicas | Undersized caches increase storage reads and reduce the latency benefit |
| Licensing and support | Check the license and support terms of the store version you deploy | Not applicable | Confirm the license terms of your Redis version before adopting it, since Redis changed its licensing after version 7.2 |
| Security | Restrict network access to the cache and enable authentication where the store supports it | Shared stores expose cached responses to anything that can reach them | Keep the cache on a private network segment, since cached TechDocs pages may include internal documentation |
How to set up TechDocs caching step by step
This sequence moves TechDocs caching from a measured baseline to a verified setup, so that documentation pages load faster from remote storage without serving stale content after a publish.
Confirm storage location and measure baseline latency
Identify the bucket or container that holds your published TechDocs sites and the region it runs in, then record how long a typical docs page takes to load from a browser and from the Backstage backend, using the same entity and network path your engineers use. Ask your platform team which region the Backstage backend runs in and whether it matches the storage location, because distance between the two is the main source of the latency the TechDocs architecture page describes. Save these numbers with the date and the entity names you tested. The step is done when you have a repeatable baseline you can compare against after caching is enabled.
Choose a supported cache store
Select one cache store that Backstage supports: Redis, Memcache, Infinispan or in-memory caching, as listed in the Backstage architecture overview. In-memory caching suits a single backend instance and development, while a shared store is needed when you run more than one backend replica, because each replica otherwise keeps its own copy. For Redis, check the license of the version you plan to deploy on the Redis licenses page, and confirm with your legal or procurement team whether the license terms fit your use, including any modified-code or network-service obligations. Consider Valkey as an alternative under BSD-3-Clause if that license fits your policy better. The step is done when the store, version and license decision are written down and approved.
Deploy the cache store with high availability
Deploy the chosen store in the infrastructure you control. If a single cache instance is acceptable for your recovery targets, a standalone node is simpler to run. If an outage would slow every docs page, use replication with Redis Sentinel or Valkey Sentinel, which the vendor docs describe as providing automatic failover that promotes a replica to master when not using a Cluster. The Redis and Valkey Sentinel documentation recommends at least three Sentinel instances for a robust deployment, so plan for three and place them on separate failure domains where possible. Confirm that the Backstage backend can reach the master through the Sentinel setup your deployment chooses. The step is done when you can stop the master in a test environment and see a replica promoted while the backend continues to answer.
Configure the Backstage cache backend
Set the cache connection in the Backstage backend configuration to point at the store you deployed, with the connection details, credentials and TLS settings that match your environment. Keep credentials in your secrets mechanism and reference them from configuration rather than writing them into files in source control. Confirm the exact configuration keys against the current Backstage documentation for the cache backend, since the key names and options depend on the Backstage release you run. Restart a non-production backend and check its startup logs for connection errors. The step is done when the backend starts, connects to the cache and shows no authentication or TLS failures in the logs.
Set what is cached and the expiry
Decide which TechDocs responses the backend should cache, such as rendered page content fetched from storage, and set an expiry for each cache entry. Shorter expiry times reduce the window in which readers see an older version after a publish, while longer times reduce storage reads. Document the choice per content type so that your team knows what to expect after each publish. Test a few entity sites with the expiry you chose and confirm that cache entries are created for the documents you intended and not for private responses that should be checked for each user. Coordinate with your access model, since TechDocs visibility depends on catalog permissions and cached responses must not bypass them. The step is done when the cached items, the expiry values and the access check are recorded in your runbook.
Verify hit behavior and page load times after a publish
Publish a change to one test TechDocs site, then load its pages twice from the same location and check the cache store for new keys, using its monitoring commands or metrics. Confirm that the second load is served from the cache, and that the new content appears after the expiry you set, not earlier and not indefinitely. Compare page load times with the baseline you recorded in the first step, measuring both cold and warm loads. Also confirm that a failed cache store does not block docs from loading, because the backend should fall back to storage. The step is done when hit behavior matches the design, page loads improve against the baseline, and a publish reaches readers within the expiry window you documented.
Security risks when caching documentation
A TechDocs cache holds copies of documentation that may be restricted to certain teams. The cards below cover where those copies can leak, how the cache is keyed and reached, and where it runs, so the cache does not weaken the access controls around the source docs.
Access leakage across users
If cached responses are keyed only by entity or page path, a response built for one user can be served to another who should not see it. Check whether the cache key includes the identity or permission context that TechDocs relies on, and test with two users who have different catalog read rights. Confirm this behavior against the TechDocs and permission configuration in your own version before you rely on it.
Cache key design
Keys that omit the site version, the entity reference or a content hash can return stale or mismatched documentation, and stale pages can outlive a retraction or an access change. Decide which values belong in each key, set expiry on every entry, and document how a cache flush is triggered after a docs publish.
Network exposure of the cache store
Redis, Valkey and other stores accept connections on a network port, and an open port lets any reachable workload read or overwrite cached pages. Bind the store to a private subnet, restrict inbound sources to the Backstage backend, and confirm that no public address or load balancer routes to it.
Authentication to the cache
A cache without authentication trusts every client that can reach it. Enable the store's access control, use a dedicated credential for the Backstage backend with only the commands it needs, and store that credential in your secrets system rather than in the app configuration file.
Data at rest in cache memory
Cached documentation sits in memory and may be written to snapshot or append-only files on disk. Check whether those persistence files are enabled, where they are written, who can read the host, and how they are removed when a cache node is retired or replaced.
Keeping the cache in your infrastructure
A managed cache service sends your documentation through a provider's environment. Keep the cache on servers or clusters you control, and confirm with your compliance owner which data classes may be cached outside your boundary. Record the license and support terms of the store you choose, since they differ across the Redis and Valkey lines.
Questions teams ask before caching TechDocs
What does it cost to cache TechDocs, and what drives the cost up?
The cost has two parts: the engagement itself and the cache store you run afterward. The engagement is quoted from a written scope, so the main drivers are how many Backstage backend instances need to share the cache, whether your storage is S3, Google Cloud Storage or Azure Blob Storage, whether you already operate a Redis-compatible service, and how much verification and load testing you want before cutover. The cache store adds recurring infrastructure cost: compute, memory, replicas and monitoring. Ask for the quote to split one-time work (configuration, testing, runbook) from recurring items (cache hosting, upgrades, support), and ask which of those the vendor will run for you.
How long does a TechDocs caching rollout take?
Duration depends on scope rather than on the caching change itself, which is a configuration change in the Backstage backend. Timing grows with the number of environments, the number of backend replicas, the cache store decision (an existing managed service is quicker to adopt than a new high availability topology), the amount of latency measurement you need before and after, and how many approval gates your change process requires. Agree a timeline in the written scope, and make sure it includes a baseline measurement so you can show whether page loads actually improved.
What does the internal team need to provide for this work?
Plan to supply access and decisions rather than code. You will need the current Backstage configuration, read access to the TechDocs storage bucket and its region, a list of environments, and a named owner who can approve the cache store choice. Your platform team should also confirm network paths from the backend to the cache and which secrets store holds the cache credentials. Security and compliance reviewers should be available early, because the cache will hold documentation content and must be placed in the same trust zone as the backend.
Can our own team cache TechDocs without a partner?
Yes, if your team already runs Backstage in production and operates a supported cache store. The Backstage configuration change is small, but the surrounding work is not: choosing the store, sizing it, making it highly available, setting eviction and expiry behavior, and testing failover all need experienced operators. A partner adds the most value when the team lacks cache operations experience or when a fixed-scope delivery with written verification is needed. Compare the internal effort against the written scope before deciding.
Which cache store should we choose for Backstage?
Backstage supports Redis, Memcache, Infinispan or in-memory caching, so the choice is a platform decision rather than a Backstage limitation. Redis Open Source 8.0 and later are available under a choice of RSALv2, SSPLv1 or AGPLv3, so license review is required before you adopt it. Redis 7.2.x and earlier use BSD-3-Clause, and Valkey is a BSD-3-Clause fork under Linux Foundation governance that is compatible with Redis OSS 7.2 and earlier. Check your legal team's position on each license, the high availability model you need (Redis Sentinel and Valkey Sentinel both recommend at least three Sentinel instances), and whether your cloud provider offers a managed service. Confirm the exact version you plan to deploy against the release pages before finalizing.
How do we verify that TechDocs caching works?
Measure before and after. Record page load and TechDocs fetch times from the same locations and user paths, then repeat the measurements after the change with the cache warm and cold. Confirm that repeated requests for the same documentation hit the cache, that a changed site is served after its cache entry expires or is invalidated, and that users who lack read permission on an entity still cannot see its docs through a cached response. Ask the vendor to deliver these test cases in writing, along with the expected results.
What happens to TechDocs when the cache is down?
The cache should be a performance layer, not the only path to content. Confirm with your engineers how the Backstage backend behaves when the cache store is unreachable: whether requests fall back to the storage bucket, whether errors surface to users, and how long timeouts run. Plan a high availability topology for the cache, alert on connection failures, and test a cache outage in a non-production environment before go-live. Include the failure behavior in the runbook so on-call staff know what slowdown or error they should expect.
How DeployOpen scopes and delivers TechDocs caching
DeployOpen approaches TechDocs caching as a scoped change to a Backstage deployment: first measuring where latency comes from, then choosing a supported cache store, then configuring, testing and documenting the result in infrastructure you control. Engagements are fixed-scope, with the written scope agreed before work starts.
How we scope
- Confirm where TechDocs sites are stored and how far that storage sits from your Backstage backend and users.
- Agree which backend responses to cache, and which must always be read fresh, such as access checks.
- Record the cache store decision, its hosting model and its license terms, with an owner for each in the written scope.
How we build
- Configure the Backstage cache backend against the chosen store, keeping the cache settings in version-controlled configuration.
- Set cache expiry and invalidation so that newly published docs appear within a window your team agrees in advance.
- Test cold and warm page loads and confirm that restricted documentation is never served from cache to unauthorized users.
How we hand over
- Deliver the configuration, the cache store deployment notes and the test results for your review and sign-off.
- Document the cache keys, expiry settings and the steps to flush the cache after a failed publish or a storage change.
- Walk your platform and security engineers through monitoring of the cache store and the runbook for common failures.
How we support
- Offer ongoing support, upgrades and continuous testing as a retainer for the cache store and Backstage configuration.
- Review the cache store's release line and security fixes when your Backstage version or cache store version changes.
- Revisit cache settings when storage location, document volume or the TechDocs publishing process changes.
