Starting the server, configuring

Requirements

You'll need at least Python 2.3 to run Snakelets.

Please consider installing the sendfile(2) system call extension module from Snakefarm.org (works on Linux) or the one from Ben Woolley (which works on Linux and BSD too). This module may improve performance and CPU utilization in some cases (experiment!). Snakelets will automatically use it if it is installed (doesn't matter which one of the two mentioned above).

Out-of-the-box startup

It is possible to start the Snakelets server out-of-the-box, without changing anything. If you don't enable the virtual host feature (see below), Snakelets will scan the "webapps" directory and will load all web applications it finds on the current host. If you have a web app named "ROOT" that one will be used as the web application for the root context '/'. You can just start the serv.py script without configuring anything and away you go. The default port number is 9080, so you can access the server with the following url: http://machinename.domain:9080/ .

Warning: the default config works but is very likely not the one that you want for your own server environment. One of the things you will have to change is removing the example plugins (if any) and webapps that come with Snakelets!

Apache?

...is not needed: Snakelets contains its own multithreaded web server. But if you still want to use Apache, you can use mod_proxy or mod_rewrite to let Apache forward certain requests to a running snakelets server behind it. Plans exist to develop a snakelets module for tighter integration in Apache, and for more performance. But for now, you'll have to use mod_proxy (or mod_rewrite).

Configuring Apache; bottom line: Set up apache to reverse-proxy everything after snake/ to Snakelets.

Warning: as the Apache manual also states, regarding the use of proxies: please secure your Apache configuration: do not let it become an open proxy server!

Edit your Apache config file. Make sure that mod_proxy is loaded in the LoadModule section.
Configure the forwarding to the Snakelets server:

ProxyRequests Off
ProxyPass /snake/ http://localhost:9080/snake/
ProxyPassReverse /snake/ http://localhost:9080/snake/

This example forwards all requests starting with '/snake/' to Snakelets. You can also configure a dedicated virtual host, for example:

<VirtualHost snakelets.host.domain>
  ServerName snakelets.host.domain
  ProxyRequests Off 
  ProxyPass / http://localhost:9080/
  ProxyPassReverse / http://localhost:9080/
</VirtualHost>

Now all requests to this hostname will be passed to Snakelets.

Then run Snakelets where you set (in serv.py) bindname='localhost', serverURLprefix='/snake/' and externalPort=80. If you use the virtualhost mapping, the serverURLprefix is empty.

Note: if you are using mod_cache, you must tell it to not cache the Snakelets urls! This can be done like this:

    <IfModule mod_cache.c>
      CacheDisable /your-snakelet-url-base
    </IfModule>

If you find that your URLs are not correct in Snakelets, you also have to enable virtual hosting in Snakelets (see below) and create a virtual host entry for the 'correct' hostname (i.e. the hostname that is used in your URLs). (You can still use a different bindname such as "localhost").

Virtual Hosts

Snakelets supports virtual hosting (based on hostnames). To enable this feature you have to edit the Virtual Host configuration. It tells the server what web applications to load and to what host names they must be connected. If you have different hostnames that point to the same IP address you are able to serve different web sites this way (this only works with HTTP 1.1 browsers, but most browsers are). The configuration file is webapps/__init__.py (the webapp module init file). It contains four configuration items:

• ENABLED - set this to True to enable virtual hosts. Setting it to False disables this feature and reverts back to out-of-the-box startup (see above).
• virtualhosts - a mapping of host names to a sequence of web application names that will be connected to the specified hostname. If a web application is not mentioned for any virtual host, it won't be loaded. A web app may be connected to multiple vhosts.
• webroots - a mapping of host names to the name of the web app that will be mapped in the URL root ( '/' ) of the server on that virtual host. The web root hosts must be known virtualhosts specified in the virtualhosts.
• aliases - a mapping of vhost-alias name to real-vhost name (this avoids duplicate loading of webapps).
• defaultvhost - the name of the default virtual host that will be used when the browser doesn't send a 'Host' header.

Every vhost can have a different list of webapps that are deployed on it, but a webapp can also be deployed on multiple vhosts at the same time. However, all deployed instances will be separate, unrelated copies of the webapp: if you deploy a webapp on multiple vhosts, it will be created for each vhost, and the init function will be invoked once for every copy.

Starting the server

If the virtual host config is in place, the Snakelet server is best started using the provided serv.py script. Just execute this and you're ready to go! Notice that the web applications that you configured in the virtual host config are installed automatically, any other web applications in the webapps directory are ignored. The parameters to snakeserver.server.main are:

• HTTPD_PORT - the port the http server will be listening on (default=9080). Note: on most operating systems you have to be root (have admin rights) to be able to use ports below 1024. So for instance, if you want to run Snakelets on port 80 (default HTTP), you will have to start the server with root privileges (for instance with "sudo python serv.py"). You also have to configure the runas-user that the server will change back to after allocating the privileged objects (see below)
• externalPort - the port the server is visible on from the outside world (default=same as HTTPD_PORT). If you're running behind a forwarding proxy you may need to set this. 'External' hostnames are handled by the virtual host configuration.
• bindname - the hostname the server will bind on, None (default) means only the current host
• serverURLprefix - URL prefix for all urls that this server uses (for instance, "/snakelets). Default is '' (empty). Internally it will be molded into the form "/prefix"; slashes will be added/stripped automatically if required.
• debugRequests - should the incoming requests and headers be printed? Default is False (boolean).
• precompileYPages - should all Ypages be precompiled to find possible errors early? Default is True (boolean). You may want to set this to False to allow faster startup times, but then you won't find out if an Ypage can't compile until the page is actually requested. (This feature needs Python2.3+)
• writePageSource - should the generated Ypage source code be written to a file in the tmp directory? Default is False (boolean). You may want to set this to True for easier Ypage debugging.
• serverRootDir - the root directory for the Snakelet server (i.e. the directory that contains the logging config, the webapps and userlibs directories etc). Default is None. If not specified, the current directory is used.
• runAsUser - the username that you want the server process to run as (used if you need to start the server as root)
• runAsGroup - the groupname that you want the server process to run as (used if you need to start the server as root)

It is also possible to use the monitor.py script. This script is designed to run on Linux, and will check if the server is active. If it's not active (or hanging) the monitor script will restart the Snakelets server (as a daemon process in the background). After starting the server it does not check anymore if it's still running, so you will have to create your own mechanism to be sure that a stopped (crashed?) server is restarted.

Logging

The server uses the standard Python logging module to log messages (if you're not using Python 2.3 or newer, you'll have to install the logging package yourself first). Logfiles appear in the "logs" directory. Logging configuration is in the "logging.cfg" file. There are a few loggers:

• "Snakelets.logger" is the logger that is used for server messages. Default logfile is "logs/server.log". It is a rotating logfile, 10 times 100Kb.
• "Snakelets.logger.accesslog" is used for logging the web server requests (apache-style access log). Default logfile is "logs/access.log". It's a rotating logfile, 10 times 100Kb. The loglevel is set to 'NOTSET'. If you set it to 'CRITICAL', no access logging is performed (improves server speed; access logging slows it down).
• "Snakelets.logger.stdout" and "Snakelets.logger.stderr" are the logger adapters for the standard output and standard error messages. These messages are printed on the console but are also written to "logs/server_console.log"

You can use the logging facility in your own code by doing:

import logging
log=logging.getLogger("Snakelets.logger")
log.debug("my debug message")

User libraries / modules

If you want to use a library or module from within several webapps, you don't have to include it in every webapp directory. There is a special directory "userlibs" in which you can place your modules and packages that you want to install. Snakelets adds this directory to the module search path, so you can import anything in it in your webapps without using nasty prefixes.

You can also easily upgrade libraries this way, just put the new version in userlibs instead of the older version and all your webapps that import it will instantly use the new code the next time you start the server.