Windows

IIS

If you don’t need to run Apache for some other application on the server, on modern Windows Servers installing web2py behind IIS is easier (and more performant). The following steps explain how to setup IIS in order to serve web2py: Windows Server 2008R2 or higher is needed.

We’ll start from the assumption that you’re running 2012R2. The terms used for 2008R2 are slightly different but it shouldn’t be a problem to reconcile the instructions. Of course the requirements are a Python installed on the server and you being able to run web2py with something like

  1. python web2py.py -a 'yourpassword'

This means that nothing is broken in your installation and that you can host successfully web2py behind IIS.

In order to run Python, IIS needs the CGI feature installed. In order to serve static files with IIS, we need also the Url Rewrite module that you can install from here

To let IIS “speak” with python, we need to install the wfastcgi module from here . This will install a little script, wfasctgi.py, that is the handler the IIS will use to communicate with Python.

Now, open the Internet Information Services (IIS) Manager and click on the node representing the server.

We need to create a FastCGI process that will be mapped to the handler running web2py.

Click on the FastCGI Settings box, and then to “Add Application”: the “full path” needs to point to the python executable (something like “C:\Python27\python.exe”) while the “Arguments” needs to point to the wfastcgi.py path (usually C:\Python27\Scripts\wfastcgi.py”).

From 2.10.4, web2py ships with a configuration file (web.config, inside the examples directory) that overrides the default handlers in order to work. The IIS configuration prohibits altering the handlers from a configuration file, but it’s easy to disable the check: go to “Feature Delegation”, find “Handler Mappings” and set it to Read/Write. Web2py needs also to be able to write files in his directory, so please make sure that the IIS_IUSRS group has read/write access to the folder where web2py is.

If you want to use web2py under the root of IIS, copy the source code under the root of IIS (that is usually C:\inetpub\wwwroot). Now, copy the web.config out of the examples directory and put it on the root folder, alongside web2py.py. You only need to replace SCRIPT_PROCESSOR (near the end of the file) to match the FastCGI application we created earlier: it has a funny syntax, but it needs to match the format Full Path|Arguments of the FastCGI application.

If you have everything installed in the default paths, it needs to be something like C:\Python27\python.exe|C:\Python27\Scripts\wfastcgi.py

This is sufficient to use web2py as the “root” application of a site. If instead you need to run web2py under a subfolder (let’s say, “web2pyapps”, so you can reach the welcome app at http://hostname/web2pyapps/welcome/ instead of the default http://hostname/welcome/), two additional steps are needed:

  • move the code to a subfolder named web2pyapps
  • create a routes.py file with routers = dict(BASE=dict(path_prefix = "web2pyapps")) in it
  • inside the IIS Manager, locate the web2pyapps folder, right click on it and select “Convert to Application”

Apache and mod_wsgi

Installing Apache, and mod_wsgi, under Windows requires a slightly different procedure. However, it is quite similar to Linux, so please read the Linux Apache notes above.

Here we assume a Windows binary Python 2.x is installed, you are running from source and web2py is located at c:/web2py.

Modern apache Windows binaries (e.g. 2.4.x) are not actually downloaded from apache.org. Instead, you download them from partner sites, such as ApacheHaus. The Apache site has a full list of such partners; search for Apache 2.4 windows binaries.

However, the Windows binary may not come with the wsgi module. In that case, visit the modwsgi home (currently at http://code.google.com/p/modwsgi/) and download the precompiled binary for your version of python and Apache. After you install Apache, put the .so library in the modules directory.

You’ll need to modify httpd.conf to load the wsgi module; follow the example of other module load config lines.

  1. LoadModule wsgi_module modules/mod_wsgi.so

The modwsgi wiki mentions Windows specifics: recommended reading.

You will need to setup httpd.conf as per any new Apache installation.

Certificate installation is the same for Windows as under Linux.

The Windows binary is most likely configured to load and configure the SSL modules ‘out of the box’ (the Apache Haus binary is like this).

web2py should be served on https and optionally on http. Typically this means port 80 and port 443 although your Windows server may be using these ports because IIS may be installed, in which case choose alternate ports.

However, we’ll assume 80 and 443 for now. look for “Listen 80” and add this line after it

  1. Listen 443

append the following lines at the end changing drive letter, port number, ServerName according to your values

  1. NameVirtualHost *:443
  2. <VirtualHost *:443>
  3.   DocumentRoot "C:/web2py/applications"
  4.   ServerName server1
  6.   <Directory "C:/web2py">
  7.     Order allow,deny
  8.     Deny from all
  9.   </Directory>
  11.   <Location "/">
  12.     Order deny,allow
  13.     Allow from all
  14.   </Location>
  16.   <LocationMatch "^(/[\w_]*/static/.*)">
  17.     Order Allow,Deny
  18.     Allow from all
  19.   </LocationMatch>
  21.   WSGIScriptAlias / "C:/web2py/wsgihandler.py"
  22. #and don't forget to move the handler script out of the handlers directory
  24.   SSLEngine On
  25. #these cert settings are correct for self-signed certificates
  26.   SSLCertificateFile conf/server.crt
  27.   SSLCertificateKeyFile conf/server.key
  29.   LogFormat "%h %l %u %t "%r" %>s %b" common
  30.   CustomLog logs/access.log common
  31. </VirtualHost>

Save and check the config using: [Start > Program > Apache HTTP Server 2.2 > Configure Apache Server > Test Configuration]

If there are no problems you will see a command screen open and close. Now you can start Apache:

[Start > Program > Apache HTTP Server 2.2 > Control Apache Server > Start]

or better yet start the taskbar monitor

[Start > Program > Apache HTTP Server 2.2 > Control Apache Server]

Now you can right-click on the red feather-like taskbar icon to “Open Apache Monitor” and then start, stop and restart Apache as required.

This section was first contributed by Jonathan Lundell.

Using nssm to run as a Windows service

What Linux calls a daemon, Windows calls a service. The web2py built-in rocket server can easily be installed/started/stopped as a Windows service. The same is true of the web2py scheduler.

Rather than maintaining Windows service code in web2py.py, the developers support the external wrapper-tool ‘nssm’.

nssm is a well respected Windows tool with good features, such as automatic restart of services. It also means a consistent way of running web2py services, scheduler services and clean-up processes like session deletes. The use of the previous -W command-line option is no longer supported. The nssm method does not use the options.py file of the old method. Instead, options are passed on the command line (some exmaples are provided below)

nssm recipe: running the scheduler as a Windows service with nssm

Running the scheduler as a Windows service makes a lot of sense. The easiest approach is to download nssm (from htp://www.nssm.cc). nssm is an open source scheduling helper. It wraps around an executable command to turn it into a service. The command to start the scheduler is pythonw.exe -K We use nssm to wrap around this, becoming a service. Before doing this, you need to choose a name for your service. There are strong advantages to creating a specific service for each app which needs a scheduler. Therefore, your naming convention for services may be web2py_scheduler_app1

After extracting the nssm zip file, open a Windows command prompt in the folder containing the version for your architecture (32-bit or 64-bit), and type

  1. nssm install web2py_scheduler_app1

This shows a dialog asking you to enter Application and Options. Application is the pythonw.exe executable from your Python installation. Options is the rest of the command line. You may need to provide the full path to your web2py.py script. For example, the options field in the nssm dialog may be:

  1. c:\web2py\web2py.py -K app1

where app1 is the name of your application.

It is possible to invoke the scheduler with multiple applications. However, in this mode, web2py detaches each application’s scheduler into a subprocess. Therefore, the process started by the service will not die if one of the scheduler instances runs into problems; rather, that child process would die. We then can’t take advantage of Windows automatic service restart in case of failure. Using one app per service enables this feature.

nssm recipe: running web2py.py as a service

The example above shows how to use nssm. To run web2py in SSL mode on port 8041, and including some other options, you could give nssm a command line (in the options field of the nssm dialog) like this:

  1. c:\web2py.py -p 8041 -i "0.0.0.0" --password="112233" --folder="d:\web2py_internet" --socket-timeout=10 --timeout=120 -c "d:\web2py_internet\applications\example.com.au.crt" -k "d:\web2py_internet\applications\web2py.key

(note that this is not best-practice for storing passwords, since a task manager which shows command lines reveals the password. Investigate the web2py command line option -a ““)