--- a/doc/admin_guide.txt	Tue Jul 13 00:00:21 2021 -0400
+++ b/doc/admin_guide.txt	Sat Jul 24 16:31:36 2021 -0400
@@ -191,6 +191,84 @@
  roundup_server -p 8017  -u roundup --save-config  demo=/trackers/demo \
     sysadmin=/trackers/sysadmin
 
+Configuring Compression
+=======================
+
+Roundup will compress HTTP responses to clients on the fly. Dynamic,
+on the fly, compression is enabled by default, to disable it set::
+
+    [web]
+    ...
+    dynamic_compression = No
+
+in the tracker's ``config.ini``. You should disable compression if
+your proxy (e.g. nginx or apache) or wsgi server (uwsgi) is configured
+to compress responses on the fly. The python standard library includes
+gzip support. For brotli or zstd you will need to install packges. See
+the `installation documentation`_ for details.
+
+Some assets will not be compressed on the fly. Assets with mime types
+of "image/png" or "image/jpeg" will not be compressed. You
+can add mime types to the list by using ``interfaces.py`` as discussed
+in the `customisation documentation`_. As an example adding::
+
+  from roundup.cgi.client import Client
+
+  Client.precompressed_mime_types.append('application/zip`)
+
+to ``interfaces.py`` will prevent zip files from being compressed.
+
+Any content less than 100 bytes in size will not be compressed (e.g
+errors messages, short json responses).
+
+Zstd will be used if the client can understand it, followed by brotli
+then gzip encoding. Currently the preference order is hard coded into
+the server and not parsed using ``q`` values from the client's
+Accept-Encoding header. This is an area for improvement.
+
+In addition to dynamic compression, static files/assets accessed using
+``@@file`` can be pre-compressed. This reduces CPU load on the server
+and reduces the time required to respond to the client. By default
+searching for pre-compressed files is disabled. To enable it set::
+
+    [web]
+    ...
+    use_precompressed_files = Yes
+
+in the tracker's ``config.ini`` file. Then you can create a
+precompressed file and it will be served if the client is able to
+accept it. For a file ``.../@@file/library.js`` you can create::
+
+    tracker_home/html/library.js.gzip
+    tracker_home/html/library.js.br
+    tracker_home/html/library.js.zstd
+
+which should be created by using (respectively)::
+
+      gzip --keep --suffix .gzip library.js
+      brotli library.js
+      zstd library.js && mv library.js.zst library.js.zstd
+
+see the man pages for options that control compression level. Note
+that some levels require additional memory on the client side, so you
+may not always want to use the highest compression available.
+
+A pre-compressed file will not be used if its modified date is earlier
+than the uncompressed file. For example, if ``library.js.gzip`` is
+older (has earlier modification date) than ``library.js``,
+``library.js.gzip`` will be ignored. ``library.js`` will be
+served instead.  ``library.js`` will be dynamically compressed on the
+fly and a warning message will be logged.
+
+Precompressed files override dynamic compression. For example, assume
+the client can accept brotli and gzip. If there are no precompressed
+files, the data will be compressed dynamically (on the fly) using
+brotli. If there is a precompressed gzip file present the client will
+get the gzip version and not a brotli compressed version. This
+mechanism allows the admin to allow use of brotli and zstd for
+dynamic content, but not for static content.
+
+
 Users and Security
 ==================
 
@@ -525,3 +603,4 @@
 
 .. _`customisation documentation`: customizing.html
 .. _`upgrading documentation`: upgrading.html
+.. _`installation documentation`: installation.html