Complete Setup Tutorial For Lighttpd, A Lightweight Web Server

There is a web server that is very conservative in its resource usage and memory footprint. That server is known as lighttpd (pronounced ‘lighty’). Setting one lighttpd instance can be a bit tricky, so this tutorial serves as a clear guide on how to properly configure a lighttpd server on Linux.

Understanding the configuration file for each web server instance is key to successfully running lighttpd. This tutorial will also cover adding PHP support for your web servers.  

Lighttpd ​Configuration Options

After installing lighttpd, we will begin by creating a file that defines the web server settings. Let’s call this ‘example.conf’ in the home directory. We will simply copy the default config file found in /etc/lighttpd. This is a standard ‘.conf’ file so the normal syntax rules apply, that is, for example, any characters after ‘#’ are treated as comments.

$ cp /etc/lighttpd/lighttpd.conf ~/webservers/example.conf
$ vim ~/webservers/example.conf # Or whatever editor you wish 

Server Modules

The ‘server.modules’ field contains an array of modules that are used by the server. Let’s add two more to the list now: ‘mod_fastcgi’ and ‘mod_setenv’. Mod_fastcgi will allow us to add PHP support. Mod_setenv will allow us to pass a header that will allow the server to make requests to other domains which is useful for loading external libraries. ​

NOTE: if you want to also include ‘mod_status’ in the list, put ‘mod_setenv’ before it.  

Server Settings

Let’s inspect the following section:

server.document-root = "/var/www/html"
server.upload-dirs = ( "/var/cache/lighttpd/uploads" )
server.errorlog = "/var/log/lighttpd/error.log"
server.pid-file = "/var/run/lighttpd.pid"
server.username = "www-data"
server.groupname = "www-data"
server.port = 80 

These fields are self-explanatory really. These are the defaults found in the config file in /etc/lighttpd. Since this is a new file, copied from the default config file, we can change whatever we want. The document root specifies the upper-most directory level visible to the web server. The field ‘upload-dirs’ contains an array of directories to store uploads to. Username and group name corresponding to the ones found on your system. By default, the user ‘www-data’ is the owner of the files created by this instance of lighttpd. You will need to make sure that the error log is writable by ‘www-data’ (covered a little later).

In this configuration, let’s change the directory of the document root to ‘/var/www/mysite/html’.Next change the error log to a different name: ‘/var/log/lighttpd/mysite/error.log’.Then change the port to 8080, if you wish.  

FastCGI and ‘setenv’ Support

Since we added these two modules in: we will need to put configurations in the file underneath the server settings (if the executables for ‘php’ and ‘php-cgi’ are located elsewhere, specify those instead):

fastcgi.server = ( ".php" => ((
"bin-path" => "/usr/bin/php-cgi",
"socket" => "/tmp/php.socket"
)))cgi.assign = ( ".php" => "/usr/bin/php" ) 

What we have done is told lighttpd that if a PHP script was requested from the server, it should launch the PHP interpreter on the computer to process it. The FastCGI module is what we use to execute PHP scripts.

If you need to allow cross-origin resource sharing(CORS), add this line below. setenv.add-response-header = ( “Access-Control-Allow-Origin” => “*”) To specify only one domain, replace “*” with the domain you want.

Here are the contents of the config file:

How to Install PHP

If you want PHP support, PHP will need to be installed, specifically the ‘php’ and ‘php-cgi’ packages. For MySQL support, ‘php-mysql’ needs to be installed as well. We have already configured the web server in the config file to allow for PHP code to be executed.  

​A Few Extra Steps

Log File

Because the location of the log file we specified in the config is in a folder that does not yet exist, lighttpd will throw an error when it runs. First, we will need to create the folder:

$ sudo mkdir /var/log/lighttpd/mysite ​

Next, create the log file, then change the user and group ownership of the file to the “www-data” user as specified in the config file.

$ sudo touch /var/log/lighttpd/mysite/error.log
$ sudo chown www-data /var/log/lighttpd/mysite/error.log
$ sudo chgrp www-data /var/log/lighttpd/mysite/error.log ​

Then we try to run the server using our config file:

$ sudo lighttpd -f mysite.conf 

Copy the Index File

Don’t forget to copy the index file found in the /var/www/html directory to your root directory:

$ sudo cp /var/www/html/index.lighttpd.html /var/www/html/mysite/index.html   

Running the Server

Hopefully, lighttpd will start in the background without printing errors on the screen. However, I did encounter an issue with one of the “include_shell” commands in the config:

include_shell "/usr/share/lighttpd/include-conf-enabled.pl" 

If you encounter this problem as well, one option is to disable it (by sticking a ‘#’ at the start of the line).

#include_shell "/usr/share/lighttpd/include-conf-enabled.pl" 

If you want or need, to fix it, the other option is to open the Perl script specified in the include_shell command and change one of the strings.

Find this line:

my $enabled = “conf-enabled/*.conf”; 

The problem is that this is a directory that this script references, but are incomplete. What I did was add where it said directory was located to the $enabled variable.

my $enabled = “/etc/lighttpd/conf-enabled/*.conf”; 

Applying Changes

​After changing the config file for a particular server, you should kill that instance of lighttpd and restart it. The PID of that server can easily be found using the ‘ps’ command.

If you only have one instance of lighttpd running, then simply run the ‘killall’ command.

$ sudo killall lighttpd   

View In Your Browser

To verify that your server is up and running and working correctly, open up your web browser (whatever it is), and type in the address bar “localhost:8080” or “127.0.0.1:8080”. If a page comes up with the title “Placeholder Page”, your server is running and delivering HTML pages correctly.  

Troubleshooting

​If you encounter problems when you launch the server, or even after that, you may need to troubleshoot. Here are a few examples and how to overcome the problems found here.  

Files Being Downloaded Instead of Handled Properly

If you tried to open your index.html page in your web browser and it took the initiative to download the file instead of rendering it, you may not have your MIME types correctly configured.

Ensure that the Perl script to configure them is being executed.

include_shell "/usr/share/lighttpd/create-mime.assign.pl" 

​This command configures your webserver to handle different file types appropriately.  

PHP Scripts Not Executing

Be sure you have PHP installed, and that the configuration file has the settings laid out in this tutorial.  

HTTP 500 Errors

These errors require further investigation. One culprit could be an error in PHP code. Whatever the cause, read the log file to find out what happened.  

Conclusion

You should have a properly configured web server running successfully with lighttpd. If you need more than one lighttpd instance running, ensure that the port specified in each configuration file is different from each other, otherwise, lighttpd will throw an error.  

A Little Quality of Life Tip

You can manage the files without running editors as root by giving full ownership of the directory to yourself:

$ sudo chown -R your_username /var/www/html/mysite
$ sudo chgrp -R your_username /var/www/html/mysite