Serving static files with lighttpd

From WeBWorK
Jump to: navigation, search

WeBWorK servers experiencing high loads may optionally install the lightweight webserver lighttpd to serve static files. According to the lighttpd documentation,

lighttpd is a secure, fast, compliant, and very flexible web-server that has been optimized for high-performance environments. It has a very low memory footprint compared to other webservers and takes care of cpu-load. Its advanced feature-set (FastCGI, CGI, Auth, Output-Compression, URL-Rewriting and many more) make lighttpd the perfect webserver-software for every server that suffers load problems.<ref>lighttpd documentation</ref>

Installation of lighttpd may be done at any time and your active courses will continue to function seemingly without change. The only change behind the scenes will be that static images and pages will be served by a light weight web server. However, installation of lighttpd as described here does come with one caution: the default security settings of some web browsers and some university firewall configurations have been reported to block images served through a different port than port 80. See below.


Installation and configuration

Install lighttpd

You must first install lighttpd according to the instructions for your operating system. Installation packages are available for Ubuntu and Debian, Red Hat and Fedora, openSUSE, Gentoo, and a FreeBSD port of lighttpd is also available. Links to those packages and installation instructions are available in the lighttpd installation documentation. Information on installing lighttpd on Ubuntu can be found in Installation_Manual_for_2.4_on_Ubuntu_10.04.

Configure lighttpd

Most linux distributions will place the lighttpd.conf configuration file with the other configuration files in /etc at /etc/lighttpd.conf or /etc/lighttpd/lighttpd.conf.On FreeBSD, the configuration file is at /usr/local/etc/lighttpd.conf. Open this file for editing as root.

Since Apache is listening on port 80 so we need an alternate port for lighttp to listen on. Standard alternate ports for this are usually 81, 8000, or 8080. 8080 is the only port that is listed as official alternate<ref>List of TCP and UDP port numbers</ref>.

Find the server.port line

# server.port               = 81

and uncomment it and change 81 to 8080 so that it reads

server.port               = 8080

If you would like to be able to view lighttpd server status information on the web, then uncomment the line

#           "mod_status",

so that it becomes


and uncomment the line

# status.status-url = "/server-status"

so it becomes

status.status-url = "/server-status"

If you want to be able to view knowls and the results of other javaScript functions which access files in the htdocs directory then uncomment the line

#            "mod_setenv",

so that it becomes


and add a custom response header. The first line is a model in the file; the second is the one you add:

#setenv.add-response-header = ( "X-Secret-Message" => "42" )
setenv.add-response-header =  ( "Access-Control-Allow-Origin" => "")

One can also use "*" if you wish to allow requests from all servers, but that might not be desirable.

The default settings for the other configuration parameters in lighttpd.conf should work fine for our purposes. If you find that the default settings for other lighttpd configuration parameters produce errors are are not suitable, please report the issue in the WeBWorK forum, and see the official lighttpd configuration instructions for further reference.

After making your changes to httpd.conf save the file, quit the editor, and restart lighttpd. On linux, this can typically be done by running this command as root:

/etc/init.d/lighttpd start

Note that the command /etc/init.d/lighttpd with no arguments will list all of the options for the lighttpd executable.

Now test your server by connecting to "http://localhost:8080/" and/or connecting to your server from a browser on a remote machine. You should see the page It works! indicating that lighttp is running.

If you enabled mod_status, then you can check lighttp's status by connecting to "http://localhost:8080/server-status" using a browser on your machine or from to "" from a browser on a remote machine.

Configure WeBWorK to use lighttpd

To configure WeBWorK to use lighttpd, we must change two values in global.conf: $webworkURLs{htdocs_temp} and $courseURLS{html_temp} . To do so, as root open global.conf for editing. If your $webworkURLs{htdocs_temp} and $courseURLS{html_temp} are set with their default values from global.conf.dist then find the line

$webworkURLs{htdocs_temp}   = "$webworkURLs{htdocs}/tmp";

and replace it by

#$webworkURLs{htdocs_temp}   = "$webworkURLS{htdocs}/tmp";
$webworkURLs{htdocs_temp}   = "$webworkURLS{htdocs}:8080/tmp';

and find the line

$courseURLs{html_temp}   = "$courseURLs{html}/tmp";

and replace it by

#$courseURLs{html_temp}   = "$coursesURLs{html}/tmp";
$courseURLs{html_temp}   = "$coursesURLs{html}:8080/tmp";

If you have set up WeBWorK to Store WeBWorK's temporary files in a separate directory or partition, then find the line

$webworkURLs{htdocs_temp}   = '/wwtmp'

and replace it by

#$webworkURLs{htdocs_temp}   = '/wwtmp';
$webworkURLs{htdocs_temp}   = '';

and find the line

$courseURLs{html_temp}   = "/wwtmp/$courseName";

and replace it by

#$courseURLs{html_temp}   = "/wwtmp/$courseName";
$courseURLs{html_temp}   = "$courseName";

then save the file and quit.

As root or with sudo restart apache and lighttpd. For example, on Ubuntu this would be done with

 $ sudo apache2ctl graceful
  password:<wwadmin password>
 $ sudo /etc/init.d/lighttpd restart

To test things go to a course, e.g. Before you login right click on the WeBWorK icon in the upper left hand corner of the login page. The click on Properties (or whatever is appropriate on your browser) and check that the image is being served from port 8080 (something like Then log into your course and view a problem with typeset equations (e.g. Problem 1 of the Demo set). Again right click on the typeset equation and check that the image is being served from port 8080.

Potential problems

Two problems have been reported from this set up.

First, in some cases, a firewall configuration may block httpd requests to port 8080. If this is due to the firewall set up on the WeBWorK server itself, then it should not be difficult to fix by consulting the documentation for the operating system of the server. If this is due to the firewall set up at your institution, then resolving this issue will require cooperation from the IT group there.

Second, the default security settings on some browsers (notably MSIE) may cause the browser to issue a warning alert every time a WeBWorK problem containing an image is accessed. This can be terribly annoying to users of MSIE. Such users should be encouraged to use a better web browser or to change the security settings of their preferred browser.

If you find that one of these issues cannot be resolved, you can easily disable lighttpd for WeBWorK by undoing the changes to global.conf made above.

Disabling the use of lighttpd for a single course

If you are hosting courses from different institutions on your server, you may run into a situation where port 8080 is blocked by a college, dorm, network, etc. for one of your hosted courses. This means students will not be able to view images in problems because they are served by lighttpd off port 8080. The first thing to do is to try to get the local IT people to open up port 8080 (which is the "official" alternate port to the standard http port 80). Sometimes the local people are unaware that port 8080 is being blocked.

Failing this, you can set up the affected course to use port 80 for images. To switch a course from using the default (serving images with lighttpd on port 8080) to using apache2 on port 80 for images do the following:

Edit the file course.conf which you will find in the course's parent directory (e.g. /opt/webwork/courses/myTestCourse/ ) and at the end of the file add the lines:

# Do not use lightppd (port 8080) for this course
$webworkURLs{htdocs_temp}   = '/wwtmp';
$courseURLs{html_temp}   = "/wwtmp/$courseName";
$webworkURLs{equationCache} = "$webworkURLs{htdocs_temp}/equations";

Using SSL with lighttpd

The issue is that is you serve insecure images in a secure page then some browsers complain about "insecure content within a secure page". IE in particular complains about this a lot.

To do this here are the steps:

1. In /etc/apache2/certs do (as root)

 cat server.crt server.key > server.pem
 cp server.pem /etc/lighttpd/

2. In /etc/lighttpd, edit lighttpd.conf to include the lines

 ssl.engine = "enable"
 ssl.pemfile = "server.pem"

3. In site.conf replace

 $webworkURLs{htdocs_temp}   = '';


 $courseURLs{html_temp}   = "$courseName";

with https://...

Forum discussions

External links



follow us