You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/deployment/caching/proxies.md
+33-45Lines changed: 33 additions & 45 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,99 +10,87 @@ myst:
10
10
(caching-profiles-label)=
11
11
# Caching proxies
12
12
13
-
It is common to place a so-called caching reverse proxy in front of Zope when hosting large Plone sites.
13
+
It is common to place a caching reverse proxy in front of Zope when hosting large Plone sites.
14
14
If hosted by yourself, a popular option is {term}`Varnish`.
15
-
On the other hand there are commercial hosted CDN services like Cloudflare, CloudFront, Fastly and more.
15
+
There are commercial hosted CDN services including Cloudflare, CloudFront, Fastly, and more.
16
16
17
-
It is important to realise that whilst `plone.app.caching` provides some functionality for controlling how Plone interacts with a caching proxy.
18
-
The proxy itself must be configured separately.
17
+
It is important to realize that while `plone.app.caching` provides some functionality for controlling how Plone interacts with a caching proxy, the proxy itself must be configured separately.
19
18
20
-
Some operations in `plone.app.caching` can set response headers that instruct the caching proxy how best to cache content.
21
-
For example, it is normally a good idea to cache static resources (such as images and stylesheets) and "downloadables" in the proxy.
22
-
This are i.e. Plone content of the types `File` or `Image`.
19
+
Some operations in `plone.app.caching` can set response headers that instruct the caching proxy how to cache content best.
20
+
For example, it is normally a good idea to cache static resources (such as images and stylesheets) and downloadable files in the proxy.
21
+
These include Plone content of the types `File` or `Image`.
23
22
This content will then be served to most users straight from the proxy, which is much faster than Zope.
24
23
25
-
The downside of this approach is that an old version of a content item may returned to a user, because the cache has not been updated since the item was modified.
24
+
The downside of this approach is that an old version of a content item may returned to a user because the cache has not been updated since the item was modified.
26
25
27
26
## Strategies
28
27
29
-
There are four general strategies for dealing with this:
28
+
There are four general strategies for dealing with this situation.
30
29
31
30
### Change the URL
32
31
33
-
Since resources are cached in the proxy based on their URL, you can "invalidate" the cached copy by changing an item's URL when it is updated.
32
+
Since resources are cached in the proxy based on their URL, you can invalidate the cached copy by changing an item's URL when it is updated.
34
33
35
-
This is the approach taken by Plone's resource management: Links that are inserted into Plone's content pages for resources managed by Plone contain a hash-based token, which changes when the main bundle file changes.
34
+
This is the approach taken by Plone's resource management.
35
+
Links that are inserted into Plone's content pages for resources managed by Plone contain a hash-based token, which changes when the main bundle file changes.
36
36
37
-
This approach has the benefit of also being able to "invalidate" content stored in a user's browser cache.
37
+
This approach has the benefit of also invalidating content stored in a browser's cache.
38
38
39
-
### All caching proxies support setting timeouts.
39
+
### All caching proxies support setting timeouts
40
40
41
41
This means that content may be stale, but typically only up to a few minutes.
42
42
43
43
This is sometimes an acceptable policy for high-volume sites where most users do not log in.
44
44
45
-
### Most caching proxies support receiving PURGE requests for paths that should be purged.
45
+
### Most caching proxies support receiving `PURGE` requests for paths that should be purged
46
46
47
47
Given the proxy has cached a resource at `/logo.jpg`, and that object is modified.
48
-
49
-
Then a PURGE request could be sent to the proxy (originating from the backend, not the browser) with the same path to force the proxy to fetch a new version the next time the item is requested.
48
+
Then a `PURGE` request could be sent to the proxy (originating from the backend, not the browser) with the same path to force the proxy to fetch a new version the next time the item is requested.
50
49
51
50
### Avoid caching
52
51
53
-
The final option, of course is to avoid caching content in the proxy altogether.
52
+
The final option, of course, is to avoid caching content in the proxy altogether.
54
53
55
54
The default policies will not allow standard listing pages to be cached in the proxy, because it is too difficult to invalidate cached instances.
56
-
57
55
For example, if you change a content item's title, that may require invalidation of a number of pages where that title appears in the navigation tree, folder listings, `Collections`, portlets, and so on.
58
-
59
56
Tracking all these dependencies and purging in an efficient manner is impossible unless the caching proxy configuration is highly customised for the site.
60
57
61
58
Nevertheless a "terse" policy allows caching for just a few seconds of all pages to reduce the load on the backend on high traffic situations.
62
59
63
60
64
61
## Purging a caching proxy
65
62
66
-
Synchronous and asynchronous purging is enabled via [plone.cachepurging](https://pypi.org/project/plone.cachepurging), which is installed as a dependency of `plone.app.caching`.
63
+
Synchronous and asynchronous purging is enabled via [`plone.cachepurging`](https://pypi.org/project/plone.cachepurging), which is installed as a dependency of `plone.app.caching`.
67
64
68
65
In the control panel, you can configure the use of a proxy via various options, such as:
69
66
70
-
* Whether or not to enable purging globally.
71
-
72
-
* The address of the caching server to which PURGE requests should be sent.
73
-
74
-
* Whether or not virtual host rewriting takes place before the caching proxy receives a URL or not.
75
-
This has implications for how the PURGE path is constructed.
76
-
77
-
* Any domain aliases for your site, to enable correct purging of content served via e.g. http://example.com and http://www.example.com.
67
+
- Whether to enable purging globally.
68
+
- The address of the caching server to which `PURGE` requests should be sent.
69
+
- Whether or not virtual host rewriting takes place before the caching proxy, receives a URL, or not.
70
+
This has implications for how the `PURGE` path is constructed.
71
+
- Any domain aliases for your site, to enable correct purging of content served via similar hosts http://example.com and http://www.example.com.
78
72
79
73
The default purging policy is geared mainly towards purging file and image resources, not content pages, although basic purging of content pages is included.
80
-
81
74
The actual paths to purge are constructed from a number of components providing the `IPurgePaths` interface.
82
-
83
75
See `plone.cachepurging` for details on how this works, especially if you need to write your own.
84
76
85
77
The default purge paths include:
86
78
87
-
* ${object_path}, -- the object's canonical path
88
-
89
-
* ${object_path}/ -- in case the object is a folder
90
-
91
-
* ${object_path}/view -- the `view` method alias
92
-
93
-
* ${object_path}/${default-view} -- in case a default view template is used
94
-
95
-
* The download URLs for any content object fields, given the type contains blobs.
96
-
This includes support for the standard `File` and `Image` types.
79
+
-`${object_path},`: the object's canonical path
80
+
-`${object_path}/`: in case the object is a folder
81
+
-`${object_path}/view`: the `view` method alias
82
+
-`${object_path}/${default-view}`: in case a default view template is used
83
+
- The download URLs for any content object fields, given the type contains blobs.
84
+
This includes support for the standard `File` and `Image` types.
97
85
98
-
Files and images created (or customised) in the ZMI are purged automatically when modified.
99
-
Bundles managed through the resource registration do not need purging, since they have "stable" URLs.
100
-
To purge Plone content when modified (or removed), you must select the content types in the control panel.
86
+
Files and images created (or customized) in the ZMI are purged automatically when modified.
87
+
Bundles managed through the resource registration do not need purging, since they have stable URLs.
88
+
To purge Plone content when modified or removed, you must select the content types in the control panel.
101
89
By default, only the `File` and `Image` types are purged.
102
90
103
91
You should not enable purging for types that are not likely to be cached in the proxy.
104
92
Although purging happens asynchronously at the end of the request, it may still place unnecessary load on your server.
105
93
106
-
Finally, you can use the *Purge* tab in the control panel to manually purge one or more URLs.
94
+
Finally, you can use the {guilabel}`Purge` tab in the control panel to manually purge one or more URLs.
107
95
This is a useful way to debug cache purging.
108
-
It offers as well as a quick solution for the awkward situation where your boss walks in and wonders why the "about us" page is still showing that old picture of him, before he had a new haircut.
96
+
It offers a quick solution for the awkward situation where your boss walks in and wonders why the "about us" page is still showing that old picture of him, before he had a new haircut.
0 commit comments