Cache Off vs Cache On: Choosing Thymeleaf Template Reload Strategy

Direct Answers

1. Docker deployment with spring.thymeleaf.cache=false: It reliably prevents stale renders if the template files are updated in-place on a volume that all containers see with updated mtime. With immutable images (templates baked into the image), cache=false adds unnecessary I/O; cache=true is safe because each new pod starts with fresh templates.
2. Performance trade‑offs: Cache enabled (true) eliminates filesystem stat() and re‑parsing per request, typically yielding 10–50× higher throughput on template‑heavy pages. Cache disabled (false) adds ~1–5 ms per render for stat() + re‑parse on change; under high concurrency this can become a bottleneck. Explicit cache clearing on each deployment adds a small operational window where stale content may be served.
3. Cluster‑wide timestamp invalidation: Works automatically when all nodes share a volume that is updated atomically (e.g., symlink swap or atomic write). With Kubernetes ConfigMaps, updates are eventually consistent; you must either accept a brief staleness window or trigger a rolling restart / inotify‑based reload.

Confirmed Behavior (Spring Boot 2.3+ / Thymeleaf 3.0+)

• spring.thymeleaf.cache=true (default in production) parses each template once at startup. Changes require JVM restart or explicit TemplateEngine.clearTemplateCache().
• spring.thymeleaf.cache=false checks the file’s last‑modified timestamp on every render. In local development this gives instant feedback. In containers it adds a stat() syscall per request.
• Spring Boot DevTools sets cache=false only when a development profile is active; it does not activate in production.
• Explicit invalidation via ContextRefreshedEvent listener or Actuator endpoint works but introduces a race condition between pod start and cache clear.

Recommended Patterns

Deployment Model	Cache Setting	Invalidation Approach
Immutable container image (templates in src/main/resources/templates)	true	None needed; new image = new templates
Externalized templates on shared volume (PVC, hostPath)	false	Atomic volume update (symlink swap) so mtime changes are visible instantly
Kubernetes ConfigMap for templates	false + rolling restart	ConfigMap updates are eventually consistent; rolling restart guarantees consistency

Verification Steps (Safe Commands)

1. Check active resolver and cache flag:

   curl -s http://localhost:8080/actuator/configprops | jq '.[] | select(.prefix=="spring.thymeleaf")'
   # or
   ./mvnw spring-boot:run --spring.profiles.active=prod -Dspring.thymeleaf.cache=true
   

2. Load‑test latency difference:

   wrk -t4 -c100 -d30s http://localhost:8080/template-heavy-endpoint
   # run with cache=true and cache=false, compare p99 latency and CPU
   

3. Simulate template update in a running container:

   docker exec  touch /templates/foo.html
   # then request the page; with cache=false change appears immediately
   

One Missing Diagnostic Detail

If you are using Kubernetes ConfigMaps for templates, confirm whether your deployment strategy includes a rolling restart or an inotify‑based reloader (e.g., kubectl rollout restart or a sidecar like stakater/reloader). This determines whether cache=false alone is sufficient or if you must accept a staleness window.

Uncertainty Flags (Review Before Production)

• Thymeleaf’s StandardTemplateResolver key collision when multiple template locations share the same logical name (classpath vs file). Verify with DEBUG logging for org.thymeleaf.TemplateEngine.
• Spring Boot’s spring.template.provider.cache (since 2.3) interacts with spring.thymeleaf.cache; ensure only one resolver is active.
• Performance impact of cache=false under your specific load profile should be measured; the 1–5 ms estimate varies with filesystem type (local SSD vs network volume).