There are many ways to set up a Foswiki server using
lighttpd
. This tip covers two methods, starting with the simplest and rising in complexity (and functionality).
Quick and Dirty
The simplest way to run
lighttpd
is to use the
tools/lighttpd.pl
perl script shipped with Foswiki. As long as
lighttpd
is installed, all you have to do is to run this script from the command-line, and it will start a server. This is a good way to get Foswiki up and running quickly, especially if you don't have an existing web server.
Your operating system may have mechanisms to allow such a script to be run in the background when the server starts.
- + simple
- + uses fastcgi if it's available
- - primarily intended for use by developers
- - requires additional configuration if you want anything more than a quick "suck it and see".
Fully-featured installation
Here's how to set up lighttpd for a medium to large Foswiki installation of multiple virtual hosts. This includes:
- fastcgi as well as plain cgi for debugging
- serving compressed css and js files
- short urls
- automation of domain configuration, including server aliasing as configured by VirtualHostingContrib
- protection of attachments using xsendfile (instead of the standard viewfile approach)
- http -> https redirect of
login
and register
Directory layout
Lighttpd
These are the configuration files used by lighttpd:
File |
Description |
/etc/lighttpd/rewrite.lua |
rewrite requests to css and js files to their gziped version when available |
/etc/lighttpd/rewrite.conf |
redirect configuration using rewrite.lua |
/etc/lighttpd/lightygraph.pl |
generates load statistics using rrd |
/etc/lighttpd/conf-enabled/10-fastcgi.conf |
required module |
/etc/lighttpd/conf-enabled/05-auth.conf |
required module |
/etc/lighttpd/conf-enabled/10-ssl.conf |
optional module |
/etc/lighttpd/conf-enabled/10-expire.conf |
required module |
/etc/lighttpd/conf-enabled/10-rrdtool.conf |
optional module for load statistics |
/etc/lighttpd/conf-enabled/10-cgi.conf |
required module |
/etc/lighttpd/conf-enabled/10-magnet.conf |
required module to run rewrite.lua on some urls |
/etc/lighttpd/conf-enabled/20-foswiki.conf |
required module |
/etc/lighttpd/lighttpd.conf |
base configuration as it comes with your distro |
/etc/lighttpd/foswiki-base.conf |
configuration used by each virtual host |
/etc/lighttpd/certs/your-domain.com/host.pem |
your ssl certificates |
/etc/lighttpd/certs/your-domain.com/... |
... |
/etc/lighttpd/lighttpd.user |
credentials for basic authentication to protect the /server/ path, i.e. /server/configure |
Foswiki
Both the Foswiki root and the directory holding all vhosts can be configured in
/etc/lighttpd/conf-enabled/20-foswiki.conf
and (unfortunately) in
- /var/www/foswiki/lib/LocalSite.cfg
- /var/www/vhosts/_template/VirtualHost.cfg
as well. VirtualHostingContrib needs a
$Foswiki::cfg{VirtualHostingContrib}{VirtualHostsDir} = '/var/www/vhosts';
in LocalSite.cfg.
This one may serve as our example:
Path |
Description |
/var/www/foswiki |
git clone location |
/var/www/foswiki/core |
foswiki installation |
/var/www/foswiki/core/tools/include-vhosts.pl |
generates virtual domain configuration found in the vhosts directory |
/var/www/foswiki/core/lib/LocalSite.cfg |
default foswiki configuration shared by all virtual hosts, per-domain configuration differences are in VirtualHost.cfg; this file is maintained using foswiki's standard configure application via the http://.../server/configure url |
/var/www/vhosts/_template/ |
location of the domain template |
/var/www/vhosts/_template/pub |
|
/var/www/vhosts/_template/VirtualHost.cfg |
configuration for a virtual domain overlaying /var/www/foswiki/core/lib/LocalSite.cfg |
/var/www/vhosts/_template/pub/System |
sym link to /var/www/foswiki/core/pub/System |
/var/www/vhosts/_template/pub/images |
thumnail images generated by ImageGalleryPlugin |
/var/www/vhosts/_template/pub/Trash/... |
a copy of the default trash as it comes in /var/www/foswiki/core/pub/Trash |
/var/www/vhosts/_template/working/... |
a copy of the default trash as it comes in /var/www/foswiki/core/working |
/var/www/vhosts/_template/html |
document root for static html files, e.g. holding a robots.txt and a favicon.ico |
/var/www/vhosts/_template/data |
holds some symlinks to webs shared among all vhosts as well |
/var/www/vhosts/_template/data/_empty |
a copy of the default trash as it comes in /var/www/foswiki/core/data/_empty |
/var/www/vhosts/_template/data/_default |
a copy of the default trash as it comes in /var/www/foswiki/core/data/_default |
/var/www/vhosts/_template/data/Sandbox |
a copy of the default trash as it comes in /var/www/foswiki/core/data/Sandbox |
/var/www/vhosts/_template/data/System |
symlink to /var/www/foswiki/core/data/System |
/var/www/vhosts/_template/data/Applications |
symlink to /var/www/foswiki/core/data/Applications in case you are using WikiWorkbenchContrib to share all wiki apps on all virtual hosts |
/var/www/vhosts/_template/data/Trash |
a copy of the default trash as it comes in /var/www/foswiki/core/data/Trash |
/var/www/vhosts/_template/data/Main |
a copy of the default trash as it comes in /var/www/foswiki/core/data/Main |
/var/www/vhosts/your.domain.com |
location a running domain, initiated as a copy of /var/www/vhosts/_template |
Files
20-foswiki.conf
# global vars
var.vhostsdir = "/var/www/vhosts"
var.foswikidir = "/var/www/foswiki/core"
server.breakagelog = "/var/log/lighttpd/error.log"
#debug.log-condition-handling = "enable"
#debug.log-request-header = "enable"
#debug.log-request-handling = "enable"
#debug.log-response-header = "enable"
# See Item12581: Lighttpd lower cases PATH_INFO on case-insensitive file systems.
server.force-lowercase-filenames = "disable"
$HTTP["useragent"] =~ "MSIE" {
server.max-keep-alive-requests = 0
}
# server maintenance
$HTTP["url"] =~ "^/server/configure" {
alias.url += ( "/server/configure" => foswikidir + "/bin/configure" )
cgi.assign = ( "" => "" )
setenv.add-environment = ( "AUTH_TYPE" => "Basic" ) # "Basic" or "Digest"
}
# optional in case you use rdd tools for load statistics
$HTTP["url"] =~ "^/server/lightygraph" {
alias.url += ( "/server/lightygraph" => "/etc/lighttpd/lightygraph.pl" )
cgi.assign = ( "" => "" )
}
include_shell "/etc/lighttpd/include-vhosts.pl"
foswiki-base.conf
This file is included by each domain and makes use of the server variables set before.
include "rewrite.conf"
# redirect login to https
# redirect System.UserRegistration to https
$HTTP["scheme"] == "http" {
#url.redirect = ( "^/(.*)" => "https://" + server.name + "/$1" )
url.redirect += (
"^/((?:bin/)?(?:login).*)" => "https://" + server.name + "/$1",
"^/(?:bin/view/)?(System/UserRegistration)" => "https://" + server.name + "/$1"
)
}
# enable this one to protect your wiki apps
#url.redirect = ( "^/+(bin\/+view\/+)?Applications.*" => "http://" + server.name )
# short urls
url.rewrite-once += ( "^/?(\?.*)?$" => "/bin/view" )
url.rewrite-once += ( "^/([A-Z_].*)" => "/bin/view/$1" )
# protect attachments
# exceptions:
# * System
# * Applications
# * Sandbox
# * thumbnails
# * !GenPDFPrincePlugin drags in css, js and image files via localhost so no authentication is required then
$HTTP["useragent"] !~ "Prince" {
url.rewrite-once += ( "^/pub/((?!System|Application|images|Sandbox).*)/(.*?)$" => "/bin/xsendfile/$1/$2" )
}
# alias for /pub
$HTTP["url"] =~ "^/pub/" {
expire.url += ("/pub" => "access 8 hours")
alias.url += ("/pub" => vhostsdir + "/" + server.name + "/pub" )
}
# fcgi for anything bin
$HTTP["url"] =~ "^/bin/" {
alias.url += ( "/bin" => foswikidir + "/bin/virtualhosts.fcgi" )
fastcgi.server = ( ".fcgi" => ((
"socket" => foswikidir + "/working/tmp/virtualhosts.sock",
"bin-path" => foswikidir + "/bin/virtualhosts.fcgi",
"check-local" => "disable",
"idle-timeout" => 20,
"min-procs" => 4,
"max-procs" => 10,
"allow-x-send-file" => "enable"
),
))
expire.url = ( )
}
# optionally access your sites using plain cgi via =http://your-domain.com/cgi-bin/Web/Topic
# usefull for debugging
$HTTP["url"] =~ "^/cgi-bin/" {
alias.url += ( "/cgi-bin" => foswikidir + "/bin/virtualhosts" )
cgi.assign = ( "" => "" )
setenv.add-environment = ( "FOSWIKI_ASSERTS" => "1" )
}
# add an extra expire header to xsendfile
$HTTP["url"] =~ "^/bin/(viewfile|xsendfile)" {
expire.url = ( "" => "access 8 hours")
}
05-auth.conf
This one protects anything under
http://...//server
by using a basic auth. It references digests stored in /etc/lighttpd/lighttpd.users
which you need to generate using the htdigest command.
server.modules += ( "mod_auth" )
auth.backend = "htdigest"
auth.backend.htdigest.userfile = "/etc/lighttpd/lighttpd.user"
#auth.backend.htdigest.groupfile = "/etc/lighttpd/lighttpd.group"
auth.debug = 0
auth.require = (
"/server" => (
"method" => "basic",
"realm" => "your domain realm",
"require" => "user=admin"
)
)
10-ssl.conf
$SERVER["socket"] == "0.0.0.0:443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/your.domain.com/host.pem"
}
server.modules += ( "mod_rrdtool" )
## path to the rrdtool binary
rrdtool.binary = "/usr/bin/rrdtool"
## file to store the rrd database, will be created by lighttpd
rrdtool.db-name = "/var/cache/lighttpd/lighttpd.rrd"
The one im /var/vhosts/_template/VirtualHosts.cfg looks like this. Note that you'll have to adjust the domain name when creating a new host.
my $domain = "your.domain.com";
$VirtualHost{DefaultUrlHost} = "https://$domain";
$VirtualHost{PermittedRedirectHostUrls} = "http://$domain, https://$domain";
# in case you are using a solr core per domain
$VirtualHost{SolrPlugin}{Url} = "http://localhost:8080/solr/$domain";
# note this has to match the vhost directory as configured above
$VirtualHost{XSendFileContrib}{Location} = "/var/www/vhosts/$domain/pub";