1==================
2Output Compression
3==================
4
5--------------------
6Module: mod_compress
7--------------------
8
9
10.. meta::
11  :keywords: lighttpd, compress
12
13.. contents:: Table of Contents
14
15Description
16===========
17
18Output compression reduces the network load and can improve the overall
19throughput of the webserver. All major http-clients support compression by
20announcing it in the Accept-Encoding header. This is used to negotiate the
21most suitable compression method. We support deflate, gzip and bzip2.
22
23deflate (RFC1950, RFC1951) and gzip (RFC1952) depend on zlib while bzip2
24depends on libbzip2. bzip2 is only supported by lynx and some other console
25text-browsers.
26
27We currently limit to compression support to static files.
28
29Caching
30-------
31
32mod_compress can store compressed files on disk to optimize the compression
33on a second request away. As soon as compress.cache-dir is set the files are
34compressed.
35
36(You will need to create the cache directory if it doesn't already exist. The web server will not do this for you.  The directory will also need the proper ownership.  For Debian/Ubuntu the user and group ids should both be www-data.)
37
38The names of the cache files are made of the filename, the compression method
39and the etag associated to the file.
40
41Cleaning the cache is left to the user. A cron job deleting files older than
4210 days could do it: ::
43
44  find /var/www/cache -type f -mtime +10 | xargs -r rm
45
46Limitations
47-----------
48
49The module limits the compression of files to files smaller than 128 MByte and
50larger than 128 Byte.
51
52The lower limit is set as small files tend to become larger by compressing due
53to the compression headers, the upper limit is set to work sensibly with
54memory and cpu-time.
55
56Directories containing a tilde ('~') are not created automatically (See ticket
57#113). To enable compression for user dirs you have to create the directories
58by hand in the cache directory.
59
60Options
61=======
62
63compress.allowed-encodings
64  override default set of allowed encodings
65
66  e.g.: ::
67
68    compress.allowed-encodings = ("bzip2", "gzip", "deflate")
69
70compress.cache-dir
71  name of the directory where compressed content will be cached
72
73  e.g.: ::
74
75    compress.cache-dir = "/var/www/cache/"
76
77    # even better with virt-hosting
78    $HTTP["host"] == "docs.example.org" {
79      compress.cache-dir = "/var/www/cache/docs.example.org/"
80    }
81
82  Default: not set, compress the file for every request
83
84compress.filetype
85  mimetypes which might get compressed
86
87  e.g.: ::
88
89    compress.filetype           = ("text/plain", "text/html")
90
91  Keep in mind that compressed JavaScript and CSS files are broken in some
92  browsers. Not setting any filetypes will result in no files being compressed.
93
94  NOTE: You have to specify the full mime-type! If you also define a charset, for example, you have to use "text/plain; charset=utf-8" instead of just "text/plain".
95
96  Default: not set
97
98compress.max-filesize
99  maximum size of the original file to be compressed kBytes.
100
101  This is meant to protect the server against DoSing as compressing large
102  (let's say 1Gbyte) takes a lot of time and would delay the whole operation
103  of the server.
104
105  There is a hard upper limit of 128Mbyte.
106
107  Default: unlimited (== hard-limit of 128MByte)
108
109Display compressed files
110========================
111
112If you enable mod_compress, and you want to force clients to uncompress and display compressed text files, please force mimetype to nothing.
113Exemple :
114If you want to add headers for uncompress and display diff.gz files , add this section in your conf : ::
115
116  $HTTP["url"] =~ "\.diff\.gz" {
117    setenv.add-response-header = ( "Content-Encoding" => "gzip" )
118    mimetype.assign = ()
119  }
120
121
122Compressing Dynamic Content
123===========================
124
125PHP
126---
127
128To compress dynamic content with PHP please enable ::
129
130  zlib.output_compression = 1
131  zlib.output_handler = On
132
133in the php.ini as PHP provides compression support by itself.
134
135mod_compress of lighttpd 1.5 r1992 may not set correct Content-Encoding with php-fcgi. A solution to that problem would be:
136
1371.disable mod_compress when request a php file::
138
139    $HTTP["url"] !~ "\.php$" {
140    	compress.filetype = ("text/plain", "text/html", "text/javascript", "text/css", "text/xml")
141    }
142
1432.enable mod_setenv of your lighttpd::
144
145    server.modules  += ( "mod_setenv" )
146
1473.manually set Content-Encoding::
148
149    $HTTP["url"] =~ "\.php$" {
150  	setenv.add-response-header  = ( "Content-Encoding" => "gzip")
151    }
152
153
154TurboGears
155----------
156
157To compress dynamic content with TurboGears please enable ::
158
159  [/]
160  gzip_filter.on = True
161  gzip_filter.mime_types = ["application/x-javascript", "text/javascript", "text/html", "text/css", "text/plain"]
162
163in the config/app.cfg file in your TurboGears application.  The above lines should already be in the file.  You just need to remove the comment symbol in front of the lines to make them active.
164
165Django
166------
167
168To compress dynamic content with Django please enable the GZipMiddleware ::
169
170  MIDDLEWARE_CLASSES = (
171      'django.middleware.gzip.GZipMiddleware',
172      ...
173  )
174
175in the settings.py file in your Django project.
176
177Catalyst
178--------
179
180To compress dynamic content with Perl/Catalyst, simply use the Catalyst::Plugin::Compress::Gzip module available on CPAN ::
181
182  use Catalyst qw(
183      Compress::Gzip
184      ...
185  );
186
187in your main package (MyApp.pm). Further configuration is not required.
188
189}}}
190
191
192
193