Web Servers

Using Apache httpd

Before starting things up, make sure mod_rewrite is enabled, and the AllowOverride directive
is set to All on the necessary directories involved. Be sure to restart the server before
checking things.

In order to provide applications with clean URLs, distributions ship with a set of .htaccess files for use with Apache, which will handle URL rewriting.

By default, these files can be utilized by finding all references to AllowOverride in your httpd.conf configuration file and setting the values to All. On an OS X system, your setup may look something like this:

  1. <Directory "/Library/WebServer/Documents">
  2.     Options Indexes FollowSymLinks MultiViews
  3.     AllowOverride All
  4.     Order allow,deny
  5.     Allow from all
  6. </Directory>

Once you’ve made sure AllowOverride has been set correctly, you can toss a project in your DocumentRoot. Using the past example, placing the project in /Library/WebServer/Documents/project would allow you to access your application at http://localhost/project.

In production, it is recommended that you set AllowOverride to None and instead, create a <VirtualHost /> configuration pointed at your application’s webroot directory, which contains the rewrite rules. For example, if your application is located in /var/www/html/project, your configuration would resemble the following:

  1. <VirtualHost *:80>
  2.     ServerName example.com
  3.     DocumentRoot "/var/www/html/project/app/webroot"
  4.     ErrorLog "logs/error_log"
  6.     <Directory "/var/www/html/project/app/webroot">
  7.         RewriteEngine On
  8.         RewriteCond %{REQUEST_FILENAME} !-d
  9.         RewriteCond %{REQUEST_FILENAME} !-f
  10.         RewriteCond %{REQUEST_FILENAME} !favicon.ico$
  11.         RewriteRule ^ index.php [QSA,L]
  12.     </Directory>
  13. </VirtualHost>

In this case, your app is available at http://example.com.

Using NGINX

Nginx requires a simple rewrite configuration that enables it to serve dynamic URLs. With nginx, each domain has its own configuration file that encapsulates all such rewriting rules.

The following example file is typically stored at /etc/nginx/sites-available/example.org.conf. All instances of example.org can be replaced with the domain name of your site or application.

  1. server {
  2.     listen 80;
  3.     server_name example.org;
  4.     root /path/to/project/app/webroot;
  6.     index index.php;
  7.     try_files $uri $uri/ /index.php?$args;    
  9.     location ~ \.php$ {
  10.         # These are example paths. Check your FPM configuration as your setup may vary.
  11.         include /usr/local/etc/nginx/fastcgi.conf;
  13.         # Either use a FPM socket...
  14.         fastcgi_pass unix:/usr/local/var/run/php-fpm.socket;
  16.         # ... or an address to bind to.
  17.         # fastcgi_pass 127.0.0.1:9000;
  18.     }
  19. }

Using Internet Information Services (IIS)

IIS Is a Microsoft-supplied product which manages many internet services—one of them being HTTPD—that comes standard on most Windows machines.

Obtaining IIS

To install IIS under Windows you need to go to “Add/Remove Programs” in your control panel. After entering the “Add/Remove Programs” window, click “Turn Windows features on or off” and locate the following:

  • Internet Information Services
  • Internet Information Services Hostable Web Core

For a quick setup, check both. If you want to remove specific features, you can expand “Intenernet Information Services” and remove unwanted features.

Once this is done you can now locate IIS within your Start menu or find it through search by typing “IIS”.

Preparations

To make IIS work well with li3’s pretty URL system, install the URL Rewrite extension located on the iis.net website and follow the proper installation instructions located there.

Next, follow the setup instructions for PHP on IIS for either IIS 6.0 or IIS 7.0.

Setup a site by right clicking “Sites” and click “Add Web Site”

  1. Enter your website name.
  2. Enter the physical path to your application’s webroot directory (\path\to\lithium\app\webroot).
  3. Optional: If your content is in your home directory, click “Connect As” and click “Specific User”. From therec enter your Windows login details, as this will allow IIS to have proper access to the application.
  4. Enter the desired port.
  5. Click “OK”.

Adding Rewrite Rules to IIS

  1. Locate your site in the “Sites” tree and click it.
  2. Locate the URL Rewrite icon from the extension installed earlier.
  3. On the right hand side under “Inbound Rules” click “Import Rules”
  4. Click the ellipsis (…) next to the field box and locate the .htaccess file within your \path\to\lithium\app\webroot\ directory and select it.
  5. Click “Import”.
  6. On the right hand side, click “Apply”.

Your li3 application should now be accessible via IIS.


Tested with IIS7 (which is shipped with Windows 7).

On Lighty

This quick guide is meant to help Lighty users get a development setup running in order to create li3 apps served up by Lighttpd. Lighttpd is a web server designed and optimized for high-performance production environments. It has a small memory footprint, yet contains a rich feature set. If you’re planning on using li3 and Lighttpd together, this guide is for you.

Running Lighty

You can download a copy of Lighty on the official website. Once downloaded, follow the instructions to get a running instance.

Installation details should be found in the INSTALL file packaged with the downloaded archive. Online installation tips can also be found on the Lighttpd website.

Configuration

Let us assume for this example that you’re developing locally and would like your app to be accessible at http://lithium.local/li3.

First, enable mod_magnet in your lighttpd.conf.

  1. server.modules += ( "mod_magnet" )

Then, save the following script in a file named li3.lua, preferably somewhere near your lighttpd.conf.

  1.     -- Helper function
  2.     function file_exists(path)
  3.       local attr = lighty.stat(path)
  4.       if (attr) then
  5.           return true
  6.       else
  7.           return false
  8.       end
  9.     end
  10.     function removePrefix(str, prefix)
  11.       return str:sub(1,#prefix+1) == prefix.."/" and str:sub(#prefix+2)
  12.     end
  14.     --[[
  15.       Prefix without the trailing slash.
  16.       If you are _not_ serving out of a subfolder, leave `prefix` empty.
  17.     --]]
  18.     local prefix = '/li3'
  20.     -- The magic ;)
  21.     if (not file_exists(lighty.env["physical.path"])) then
  22.         -- File still missing: pass it to the fastCGI backend.
  23.         request_uri = removePrefix(lighty.env["uri.path"], prefix)
  24.         if request_uri then
  25.           lighty.env["uri.path"]          = prefix .. "/index.php"
  26.           local uriquery = lighty.env["uri.query"] or ""
  27.           lighty.env["uri.query"] = uriquery .. (uriquery ~= "" and "&" or "") .. "url=" .. request_uri
  28.           lighty.env["physical.rel-path"] = lighty.env["uri.path"]
  29.           lighty.env["request.orig-uri"]  = lighty.env["request.uri"]
  30.           lighty.env["physical.path"]     = lighty.env["physical.doc-root"] .. lighty.env["physical.rel-path"]
  31.         end
  32.     end
  33.     -- Fallthrough will put it back into the lighty request loop..
  34.     -- That means we get the 304 handling for free. ;)

Finally, in your lighttpd.conf, add the following conditional:

  1.     $HTTP["host"] =~ "lithium.local" {
  2.         server.document-root = "/path/to/your/app/webroot/"
  3.         magnet.attract-physical-path-to = ( "/path/to/li3.lua" )
  4.     }

You’ll probably need to add a line item in your /etc/hosts file as well:

  1. 127.0.0.1 lithium.local

Restart your lighttpd process, and you’re done!

Using Caddy

Caddy is a new HTTP/2 web server with automatic HTTPS written in Go. It is pretty fast and easy to learn. You can get a quick start reading the Getting Started chapter from the documentation.

To make use of Caddy and be able to start the Caddy Server with the command caddy there has to be a Caddyfile present. This file resides in the root directory of the project.

The following example file is typically stored at /path/to/framework with the name Caddyfile.

  1. localhost:2020
  3. gzip
  5. root app/webroot
  6. fastcgi / localhost:9000 php
  8. log app/resources/tmp/logs/access.log
  9. errors app/resources/tmp/logs/error.log
  11. rewrite / {
  12.     if {file} not favicon.ico
  13.     to {path} {path}/ /index.php?url={query}
  14. }

If you want to run Caddy with different plugins, check their documentation for a list of all possible directives.