Fossil SCM
Improved the caching configuration recommended in the nginx doc to show the option for immutable content service for /artifact, /doc, /file, and /raw URLs, which are likely to contain hashes that make the URLs unique identifiers for particular versions of the referenced content.
Commit
1d0d69866dda0c1093ae0aed8c4caf258bb50f088650f5c6eb6269dcc0b86dd0
Parent
0835ec45a481d4e…
1 file changed
+62
-33
+62
-33
| --- www/server/debian/nginx.md | ||
| +++ www/server/debian/nginx.md | ||
| @@ -142,46 +142,75 @@ | ||
| 142 | 142 | contains the configuration for `*.foo.net`. |
| 143 | 143 | |
| 144 | 144 | The configuration for our `example.com` web site, stored in |
| 145 | 145 | `/etc/nginx/sites-enabled/local/example.com` is: |
| 146 | 146 | |
| 147 | - server { | |
| 148 | - server_name .example.com .example.net ""; | |
| 149 | - include local/generic; | |
| 150 | - | |
| 151 | - access_log /var/log/nginx/example.com-https-access.log; | |
| 152 | - error_log /var/log/nginx/example.com-https-error.log; | |
| 153 | - | |
| 154 | - # Bypass Fossil for the static documentation generated from | |
| 155 | - # our source code by Doxygen, so it merges into the embedded | |
| 156 | - # doc URL hierarchy at Fossil’s $ROOT/doc without requiring that | |
| 157 | - # these generated files actually be stored in the repo. This | |
| 158 | - # also lets us set aggressive caching on these docs, since | |
| 159 | - # they rarely change. | |
| 160 | - location /code/doc/html { | |
| 161 | - root /var/www/example.com/code/doc/html; | |
| 162 | - | |
| 163 | - location ~* \.(html|ico|css|js|gif|jpg|png)$ { | |
| 164 | - expires 7d; | |
| 165 | - add_header Vary Accept-Encoding; | |
| 166 | - access_log off; | |
| 167 | - } | |
| 168 | - } | |
| 169 | - | |
| 170 | - # Redirect everything else to the Fossil instance | |
| 171 | - location /code { | |
| 172 | - include scgi_params; | |
| 173 | - scgi_param SCRIPT_NAME "/code"; | |
| 174 | - scgi_pass 127.0.0.1:12345; | |
| 175 | - } | |
| 176 | - } | |
| 147 | +---- | |
| 148 | + | |
| 149 | + server { | |
| 150 | + server_name .example.com .example.net ""; | |
| 151 | + include local/generic; | |
| 152 | + include local/code; | |
| 153 | + | |
| 154 | + access_log /var/log/nginx/example.com-https-access.log; | |
| 155 | + error_log /var/log/nginx/example.com-https-error.log; | |
| 156 | + | |
| 157 | + # Bypass Fossil for the static documentation generated from | |
| 158 | + # our source code by Doxygen, so it merges into the embedded | |
| 159 | + # doc URL hierarchy at Fossil’s $ROOT/doc without requiring that | |
| 160 | + # these generated files actually be stored in the repo. This | |
| 161 | + # also lets us set aggressive caching on these docs, since | |
| 162 | + # they rarely change. | |
| 163 | + location /code/doc/html { | |
| 164 | + root /var/www/example.com/code/doc/html; | |
| 165 | + | |
| 166 | + location ~* \.(html|ico|css|js|gif|jpg|png)$ { | |
| 167 | + add_header Vary Accept-Encoding; | |
| 168 | + access_log off; | |
| 169 | + expires 7d; | |
| 170 | + } | |
| 171 | + } | |
| 172 | + | |
| 173 | + # Redirect everything under /code to the Fossil instance | |
| 174 | + location /code { | |
| 175 | + include local/code; | |
| 176 | + | |
| 177 | + # Extended caching for URLs known to include unique IDs | |
| 178 | + location ~ /(artifact|doc|file|raw)/ { | |
| 179 | + include local/code; | |
| 180 | + add_header Cache-Control "public, max-age=31536000, immutable"; | |
| 181 | + access_log off; | |
| 182 | + } | |
| 183 | + } | |
| 184 | + } | |
| 185 | + | |
| 186 | +---- | |
| 177 | 187 | |
| 178 | 188 | As you can see, this is a pure extension of [the basic nginx service |
| 179 | 189 | configuration for SCGI][scgii], showing off a few ideas you might want to |
| 180 | 190 | try on your own site, such as static asset proxying. |
| 181 | 191 | |
| 182 | -The `local/generic` file referenced above helps us reduce unnecessary | |
| 192 | +You also need a `local/code` file containing: | |
| 193 | + | |
| 194 | + include scgi_params; | |
| 195 | + scgi_pass 127.0.0.1:12345; | |
| 196 | + scgi_param SCRIPT_NAME "/code"; | |
| 197 | + | |
| 198 | +We separate that out because nginx refuses to inherit certain settings | |
| 199 | +between nested location blocks, so rather than repeat them, we extract | |
| 200 | +them to this separate file and include it from both locations where it’s | |
| 201 | +needed. You see this above where we set far-future expiration dates on | |
| 202 | +files served by Fossil via URLs that contain hashes that change when the | |
| 203 | +content changes. It tells your browser that the content of these URLs | |
| 204 | +can never change without the URL itself changing, which makes your | |
| 205 | +Fossil-based site considerably faster.(^Beware: If you use logical | |
| 206 | +versions in URLs like `/file/trunk/path/name/…` the rule above will | |
| 207 | +apply to them, too, requiring your users to toss the cache before | |
| 208 | +they’ll see updates to the referenced content. Trading off caching | |
| 209 | +versus the possibility of stale data is a delicate dance.) | |
| 210 | + | |
| 211 | +Similarly, the `local/generic` file referenced above helps us reduce unnecessary | |
| 183 | 212 | repetition among the multiple sites this configuration hosts: |
| 184 | 213 | |
| 185 | 214 | root /var/www/$host; |
| 186 | 215 | |
| 187 | 216 | listen 80; |
| @@ -189,12 +218,12 @@ | ||
| 189 | 218 | |
| 190 | 219 | charset utf-8; |
| 191 | 220 | |
| 192 | 221 | There are some configuration directives that nginx refuses to substitute |
| 193 | 222 | variables into, citing performance considerations, so there is a limit |
| 194 | -to how much repetition you can squeeze out this way. One such example is | |
| 195 | -the `access_log` and `error_log` directives, which follow an obvious | |
| 223 | +to how much repetition you can squeeze out this way. One such example | |
| 224 | +are the `access_log` and `error_log` directives, which follow an obvious | |
| 196 | 225 | pattern from one host to the next. Sadly, you must tolerate some |
| 197 | 226 | repetition across `server { }` blocks when setting up multiple domains |
| 198 | 227 | on a single server. |
| 199 | 228 | |
| 200 | 229 | The configuration for `foo.net` is similar. |
| 201 | 230 |
| --- www/server/debian/nginx.md | |
| +++ www/server/debian/nginx.md | |
| @@ -142,46 +142,75 @@ | |
| 142 | contains the configuration for `*.foo.net`. |
| 143 | |
| 144 | The configuration for our `example.com` web site, stored in |
| 145 | `/etc/nginx/sites-enabled/local/example.com` is: |
| 146 | |
| 147 | server { |
| 148 | server_name .example.com .example.net ""; |
| 149 | include local/generic; |
| 150 | |
| 151 | access_log /var/log/nginx/example.com-https-access.log; |
| 152 | error_log /var/log/nginx/example.com-https-error.log; |
| 153 | |
| 154 | # Bypass Fossil for the static documentation generated from |
| 155 | # our source code by Doxygen, so it merges into the embedded |
| 156 | # doc URL hierarchy at Fossil’s $ROOT/doc without requiring that |
| 157 | # these generated files actually be stored in the repo. This |
| 158 | # also lets us set aggressive caching on these docs, since |
| 159 | # they rarely change. |
| 160 | location /code/doc/html { |
| 161 | root /var/www/example.com/code/doc/html; |
| 162 | |
| 163 | location ~* \.(html|ico|css|js|gif|jpg|png)$ { |
| 164 | expires 7d; |
| 165 | add_header Vary Accept-Encoding; |
| 166 | access_log off; |
| 167 | } |
| 168 | } |
| 169 | |
| 170 | # Redirect everything else to the Fossil instance |
| 171 | location /code { |
| 172 | include scgi_params; |
| 173 | scgi_param SCRIPT_NAME "/code"; |
| 174 | scgi_pass 127.0.0.1:12345; |
| 175 | } |
| 176 | } |
| 177 | |
| 178 | As you can see, this is a pure extension of [the basic nginx service |
| 179 | configuration for SCGI][scgii], showing off a few ideas you might want to |
| 180 | try on your own site, such as static asset proxying. |
| 181 | |
| 182 | The `local/generic` file referenced above helps us reduce unnecessary |
| 183 | repetition among the multiple sites this configuration hosts: |
| 184 | |
| 185 | root /var/www/$host; |
| 186 | |
| 187 | listen 80; |
| @@ -189,12 +218,12 @@ | |
| 189 | |
| 190 | charset utf-8; |
| 191 | |
| 192 | There are some configuration directives that nginx refuses to substitute |
| 193 | variables into, citing performance considerations, so there is a limit |
| 194 | to how much repetition you can squeeze out this way. One such example is |
| 195 | the `access_log` and `error_log` directives, which follow an obvious |
| 196 | pattern from one host to the next. Sadly, you must tolerate some |
| 197 | repetition across `server { }` blocks when setting up multiple domains |
| 198 | on a single server. |
| 199 | |
| 200 | The configuration for `foo.net` is similar. |
| 201 |
| --- www/server/debian/nginx.md | |
| +++ www/server/debian/nginx.md | |
| @@ -142,46 +142,75 @@ | |
| 142 | contains the configuration for `*.foo.net`. |
| 143 | |
| 144 | The configuration for our `example.com` web site, stored in |
| 145 | `/etc/nginx/sites-enabled/local/example.com` is: |
| 146 | |
| 147 | ---- |
| 148 | |
| 149 | server { |
| 150 | server_name .example.com .example.net ""; |
| 151 | include local/generic; |
| 152 | include local/code; |
| 153 | |
| 154 | access_log /var/log/nginx/example.com-https-access.log; |
| 155 | error_log /var/log/nginx/example.com-https-error.log; |
| 156 | |
| 157 | # Bypass Fossil for the static documentation generated from |
| 158 | # our source code by Doxygen, so it merges into the embedded |
| 159 | # doc URL hierarchy at Fossil’s $ROOT/doc without requiring that |
| 160 | # these generated files actually be stored in the repo. This |
| 161 | # also lets us set aggressive caching on these docs, since |
| 162 | # they rarely change. |
| 163 | location /code/doc/html { |
| 164 | root /var/www/example.com/code/doc/html; |
| 165 | |
| 166 | location ~* \.(html|ico|css|js|gif|jpg|png)$ { |
| 167 | add_header Vary Accept-Encoding; |
| 168 | access_log off; |
| 169 | expires 7d; |
| 170 | } |
| 171 | } |
| 172 | |
| 173 | # Redirect everything under /code to the Fossil instance |
| 174 | location /code { |
| 175 | include local/code; |
| 176 | |
| 177 | # Extended caching for URLs known to include unique IDs |
| 178 | location ~ /(artifact|doc|file|raw)/ { |
| 179 | include local/code; |
| 180 | add_header Cache-Control "public, max-age=31536000, immutable"; |
| 181 | access_log off; |
| 182 | } |
| 183 | } |
| 184 | } |
| 185 | |
| 186 | ---- |
| 187 | |
| 188 | As you can see, this is a pure extension of [the basic nginx service |
| 189 | configuration for SCGI][scgii], showing off a few ideas you might want to |
| 190 | try on your own site, such as static asset proxying. |
| 191 | |
| 192 | You also need a `local/code` file containing: |
| 193 | |
| 194 | include scgi_params; |
| 195 | scgi_pass 127.0.0.1:12345; |
| 196 | scgi_param SCRIPT_NAME "/code"; |
| 197 | |
| 198 | We separate that out because nginx refuses to inherit certain settings |
| 199 | between nested location blocks, so rather than repeat them, we extract |
| 200 | them to this separate file and include it from both locations where it’s |
| 201 | needed. You see this above where we set far-future expiration dates on |
| 202 | files served by Fossil via URLs that contain hashes that change when the |
| 203 | content changes. It tells your browser that the content of these URLs |
| 204 | can never change without the URL itself changing, which makes your |
| 205 | Fossil-based site considerably faster.(^Beware: If you use logical |
| 206 | versions in URLs like `/file/trunk/path/name/…` the rule above will |
| 207 | apply to them, too, requiring your users to toss the cache before |
| 208 | they’ll see updates to the referenced content. Trading off caching |
| 209 | versus the possibility of stale data is a delicate dance.) |
| 210 | |
| 211 | Similarly, the `local/generic` file referenced above helps us reduce unnecessary |
| 212 | repetition among the multiple sites this configuration hosts: |
| 213 | |
| 214 | root /var/www/$host; |
| 215 | |
| 216 | listen 80; |
| @@ -189,12 +218,12 @@ | |
| 218 | |
| 219 | charset utf-8; |
| 220 | |
| 221 | There are some configuration directives that nginx refuses to substitute |
| 222 | variables into, citing performance considerations, so there is a limit |
| 223 | to how much repetition you can squeeze out this way. One such example |
| 224 | are the `access_log` and `error_log` directives, which follow an obvious |
| 225 | pattern from one host to the next. Sadly, you must tolerate some |
| 226 | repetition across `server { }` blocks when setting up multiple domains |
| 227 | on a single server. |
| 228 | |
| 229 | The configuration for `foo.net` is similar. |
| 230 |