Mercurial > p > roundup > code
comparison doc/admin_guide.txt @ 6458:8f1b91756457
issue2551147 - Enable compression of http responses in roundup.
gzip, (brotli/zstd with optional packages) on the fly
compression/content-encoding enabled by default. Can serve
pre-compressed static assets as well if the client can accept it.
Docs updated.
Also added example nginx config to installation.txt. The config allows
nginx to compress data on the fly. If the config is used, dynamic
compression in roundup can be disabled.
Dedicating this checkin to my father Paul Hector Rouillard 1930-2021.
I did much of the development in this changeset while sitting with him
as he slept/transitioned. Without his encouragement and example, my
desire to learn would not be what it is and I wouldn't be half the
person I am.
| author | John Rouillard <rouilj@ieee.org> |
|---|---|
| date | Sat, 24 Jul 2021 16:31:36 -0400 |
| parents | 1f2f7c0b8968 |
| children | 24e2eeb2ed9a |
comparison
equal
deleted
inserted
replaced
| 6457:dc59051807b6 | 6458:8f1b91756457 |
|---|---|
| 189 overwrite an existing file) from the roundup-server command line use:: | 189 overwrite an existing file) from the roundup-server command line use:: |
| 190 | 190 |
| 191 roundup_server -p 8017 -u roundup --save-config demo=/trackers/demo \ | 191 roundup_server -p 8017 -u roundup --save-config demo=/trackers/demo \ |
| 192 sysadmin=/trackers/sysadmin | 192 sysadmin=/trackers/sysadmin |
| 193 | 193 |
| 194 Configuring Compression | |
| 195 ======================= | |
| 196 | |
| 197 Roundup will compress HTTP responses to clients on the fly. Dynamic, | |
| 198 on the fly, compression is enabled by default, to disable it set:: | |
| 199 | |
| 200 [web] | |
| 201 ... | |
| 202 dynamic_compression = No | |
| 203 | |
| 204 in the tracker's ``config.ini``. You should disable compression if | |
| 205 your proxy (e.g. nginx or apache) or wsgi server (uwsgi) is configured | |
| 206 to compress responses on the fly. The python standard library includes | |
| 207 gzip support. For brotli or zstd you will need to install packges. See | |
| 208 the `installation documentation`_ for details. | |
| 209 | |
| 210 Some assets will not be compressed on the fly. Assets with mime types | |
| 211 of "image/png" or "image/jpeg" will not be compressed. You | |
| 212 can add mime types to the list by using ``interfaces.py`` as discussed | |
| 213 in the `customisation documentation`_. As an example adding:: | |
| 214 | |
| 215 from roundup.cgi.client import Client | |
| 216 | |
| 217 Client.precompressed_mime_types.append('application/zip`) | |
| 218 | |
| 219 to ``interfaces.py`` will prevent zip files from being compressed. | |
| 220 | |
| 221 Any content less than 100 bytes in size will not be compressed (e.g | |
| 222 errors messages, short json responses). | |
| 223 | |
| 224 Zstd will be used if the client can understand it, followed by brotli | |
| 225 then gzip encoding. Currently the preference order is hard coded into | |
| 226 the server and not parsed using ``q`` values from the client's | |
| 227 Accept-Encoding header. This is an area for improvement. | |
| 228 | |
| 229 In addition to dynamic compression, static files/assets accessed using | |
| 230 ``@@file`` can be pre-compressed. This reduces CPU load on the server | |
| 231 and reduces the time required to respond to the client. By default | |
| 232 searching for pre-compressed files is disabled. To enable it set:: | |
| 233 | |
| 234 [web] | |
| 235 ... | |
| 236 use_precompressed_files = Yes | |
| 237 | |
| 238 in the tracker's ``config.ini`` file. Then you can create a | |
| 239 precompressed file and it will be served if the client is able to | |
| 240 accept it. For a file ``.../@@file/library.js`` you can create:: | |
| 241 | |
| 242 tracker_home/html/library.js.gzip | |
| 243 tracker_home/html/library.js.br | |
| 244 tracker_home/html/library.js.zstd | |
| 245 | |
| 246 which should be created by using (respectively):: | |
| 247 | |
| 248 gzip --keep --suffix .gzip library.js | |
| 249 brotli library.js | |
| 250 zstd library.js && mv library.js.zst library.js.zstd | |
| 251 | |
| 252 see the man pages for options that control compression level. Note | |
| 253 that some levels require additional memory on the client side, so you | |
| 254 may not always want to use the highest compression available. | |
| 255 | |
| 256 A pre-compressed file will not be used if its modified date is earlier | |
| 257 than the uncompressed file. For example, if ``library.js.gzip`` is | |
| 258 older (has earlier modification date) than ``library.js``, | |
| 259 ``library.js.gzip`` will be ignored. ``library.js`` will be | |
| 260 served instead. ``library.js`` will be dynamically compressed on the | |
| 261 fly and a warning message will be logged. | |
| 262 | |
| 263 Precompressed files override dynamic compression. For example, assume | |
| 264 the client can accept brotli and gzip. If there are no precompressed | |
| 265 files, the data will be compressed dynamically (on the fly) using | |
| 266 brotli. If there is a precompressed gzip file present the client will | |
| 267 get the gzip version and not a brotli compressed version. This | |
| 268 mechanism allows the admin to allow use of brotli and zstd for | |
| 269 dynamic content, but not for static content. | |
| 270 | |
| 271 | |
| 194 Users and Security | 272 Users and Security |
| 195 ================== | 273 ================== |
| 196 | 274 |
| 197 Roundup holds its own user database which primarily contains a username, | 275 Roundup holds its own user database which primarily contains a username, |
| 198 password and email address for the user. Roundup *must* have its own user | 276 password and email address for the user. Roundup *must* have its own user |
| 523 | 601 |
| 524 Run ``roundup-admin help commands`` for a complete list of subcommands. | 602 Run ``roundup-admin help commands`` for a complete list of subcommands. |
| 525 | 603 |
| 526 .. _`customisation documentation`: customizing.html | 604 .. _`customisation documentation`: customizing.html |
| 527 .. _`upgrading documentation`: upgrading.html | 605 .. _`upgrading documentation`: upgrading.html |
| 606 .. _`installation documentation`: installation.html |