Python Web Developer
Appliance Users Guide

James C. McDonald


Release DRAFT
June 6, 2006


The objective for the Python Web Developer Appliance project is to facilitate both learning how to develop and developing web applications using Python.

The Python Web Developer Appliance includes the leading Python web development frameworks and supporting libraries pre-installed and ready use, alongside a complete open-source software stack for building and deploying web applications. The appliance represents an attempt to take the "batteries included" philosophy ( to another level with respect to web application development and deployment.

The Python Web Developer Appliance is packaged as a VMware virtual machine. A ready-to-run virtual machine saves the time and the headache of selecting, assembling, building, and installing a coherent set of leading edge python oriented web application development and deployment tools.

Copyright © 2006 James C. McDonald. All rights reserved.

Note: This document was prepared using the standard Python documentation LaTeX toolchain.


1 Overview

The objective for the Python Web Developer Appliance is to facilitate developing and learning how to develop web applications using Python.

The Python Web Developer Appliance includes the leading python web development frameworks and supporting libraries pre-installed and ready use, alongside a complete open-source software stack for building and deploying web applications. The appliance represents an attempt to take the "batteries included" philosophy ( to another level with respect to web application development and deployment.

The Python Web Developer Appliance is packaged as a VMware virtual machine. A ready-to-run virtual machine saves the time and the headache of selecting, assembling, building, and installing a coherent set of leading edge python oriented web application development and deployment tools.

The bundled software stack includes the Apache web server, and PostgreSQL, MySQL, SQLite database management sytems. The underlying operating system is OpenBSD .

The bundled software components are described in detail in the Appliance Software Components section. Please review this section of the document carefully. Over one hundred tool, libraries, and frameworks are included.

The included non-Python software components are installed and may be managed using the cross-platform pkgsrc package management system from the NetBSD project.

The included Python software components are installed either using either standard Python disutils binary distributions or as Python Eggs ( ) if the upstream developer specifically included support for Eggs in their package.

Warning: This User Guide is NOT a substitute for the documentation of the included software components. Please refer to the documentation and or web sites of the included components for information on how to accomplish specific tasks with those components.

2 Installation

2.1 VMware Virtual Machine Installation

A VMware virtual machine installation should be as simple as:

  1. Install VMware Workstation, or the free VMware Player software four your operating system.
  2. Download the zipped Python Web Developer Appliance virtual machine directory from the VMware web site.
  3. Unzip the virtual machine files into a directory.
  4. Add the virtual machine directory as a new virtual machine to your VMware Workstation or VMware player installation.

The virtual machine has been created as a "Legacy" virtual machine to have the broadest compatibility across different VMware software versions and releases.

Note: The zipped virtual machine directory is approximately 500MB in size. The unzipped size of the virtual machine directory is approximately 1.25GB.

2.2 Installation via Bootable ISO Image

The Python Web Developer Appliance has also been built as an i386 bootable ISO image. If there is enough interest from the community in a generic installable ISO image then I'll start the process to get a proper open source project established in order to make an ISO image available for download.

2.3 Default root Password

The default password for the operating system root user is "admin".

Please login as root and change the password using the passwd command.

2.4 Other Default Passwords

Other default usernames and passwords are show below:

Account Default Password
os "root" user admin
PostgreSQL superuser "pgsql" admin
PostgreSQL user "pywebuser" user
MySQL admin none set
Zope3 "zope3admin" admin
Supervisor admin "pywebsupervisor" admin

The pre-configured usernames/password combinations may also be found in the /usr/local/pyweb/pyweb/etc/pywebConfig.ini file.

3 Configuration

3.1 VMware Machine Configuration

The VMware Virtual Machine has been configured with the following options.

Setting Initial Value
Memory 256MB
Hard Disk IDE, max 8GB, split into 2GB files
Networking Bridged/NAT

The initial virtual machine settings should work well in most situations.

The OpenBSD guest OS networking, DNS, and default gateway are all set to use DHCP.

If the networking configuration of the virtual machine is modified the OpenBSD network configuration may also need to be changed via the ifconfig command to correspond to the new virtual machine settings.

Note: The filesystem in the virtual machine is configured as a single root (/) disk partition plus 256MB a swap partition.

3.2 Operating System Configuration

The operating system is configured in the same manner as a normal OpenBSD system. Please take advantage of the excellent OpenBSD man pages answer any questions about how to configure or use the operating system.

Note: Because the operating system is a stock OpenBSD v3.9 installation, snapshot and/or security updates from the v3.9 stable releases (CVS tag "OPENBSD_3_9") should install correctly.

3.2.1 Set root password

By default the password for root is "admin".

Please login as root and change the password using the passwd command.

3.2.2 Check date/time and timezone

By default the timezone is set to Eastern Standard Time (EST).

Please login as root and check the date and time zone.

For instructions on how to change the time zone look at afterboot(8) man page specifically the "System date" section.

3.2.3 Set hostname and domain

By default the hostname is set to "" .

For instructions on how to check/change the hostname look at afterboot(8) man page specifically the "Check hostname" section.

Please review the afterboot(8) man page for a complete description of how to perform a common set of operating system configuration tasks.

3.3 Directory Layout

The software installed on the appliance beyond the base OpenBSD operating system is installed under the /usr/local/pyweb directory and /var/pyweb directories.

As a consequence, if you add additional users to the appliance you'll likely want to add the following directories to your path.

Important directories on the appliance are shown below.

Directory Description
/usr/local/pyweb/bin user commands and binaries
/usr/local/pyweb/sbin system commands and binaries
/usr/local/pyweb/lib installed appliance libraries
/usr/local/pyweb/pgsql PostGreSQL commands and binaries
/usr/local/pyweb/mysql MySQL commands and binaries
/usr/local/pyweb/javascript javascript libraries
/usr/local/pyweb/supervisor Supervisor related
/usr/local/pyweb/etc appliance configuration
/usr/local/pyweb/pyweb/etc/pywebConfig.ini default appliance config
/usr/local/pyweb/etc/httpd/ Apache configuration directory
/usr/local/pyweb/share/httpd/htdocs/ default Apache document root directory
/usr/local/pyweb/lib/httpd/ Apache module library directory
/var/pyweb/ variable data directories
/var/pyweb/pgsql/data default PostgreSQL data directory
/var/pyweb/log default pyweb log directory

The directory layout corresponds to a standard pkgsrc installation with a PREFIX setting of "/usr/local/pyweb".

All non-OpenBSD software and settings are found in either /usr/local/pyweb/ or /var/pyweb/.

Note: /usr/local/pyweb is a symlink to /usr/local/lj and /var/pyweb is a symlink to /var/lj , this is due to a quirk in the build process that is likely to be change in a future release.

3.4 Package Management

pkgsrc has been used as the package management system for the appliance.

From the pkgsrc documentation...

The NetBSD Packages Collection (pkgsrc) is a framework for building third-party software on NetBSD and other UNIX-like systems, currently containing over 5500 packages. It is used to enable freely available software to be configured and built easily on supported platforms.

pkgsrc provides the following key features:

Complete documentation may be found at

3.4.1 Thirty Second Guide to Adding pkgsrc Packages

Note: Because the pkgsrc build toolchain uses (NetBSD) specific features of make, always use the bmake command vs. make (/usr/local/pyweb/bin/bmake) when executing build commands in pkgsrc.

4 Appliance Software Components

4.1 Appliance Software Component Overview

The included software components fall into the following categories.

The components were selected to try to include a complete web application development and deployment software stack.

In most categories there is overlapping/redundant functionality between the available packages in order to appeal to a broader audience and more diverse set of needs.

Only freely distributable software packages have been included.

If I've not included your favorite package, my apologies. Please see the section on Next Steps in this document.

4.2 Operating System and Development Environment

The Python Web Developer Appliance is based on an unmodified build from the OpenBSD v3.9 STABLE branch

OpenBSD is a free, multi-platform 4.4BSD-based UNIX-like operating system with emphasis on portability, standardization, correctness, proactive security and integrated cryptography.

The X.Org X-Window libraries have not been included in the appliance.

Some of the components provided by OpenBSD are:

More information on OpenBSD may be found at .

4.3 Additional Tools and Libraries

To supplement the functionality of the base operating system the following tools and libraries have been added .

4.4 Python Programming Language

The appliance includes the most recent production version of the Standard Python Software (release version 2.4.3 The release was built using the pkgsrc 2006Q1 port.

4.5 Python Web Frameworks

The appliance includes (most of?) the leading Python Web Frameworks and their requisite dependencies.

The included frameworks are:

4.6 Python Templating Frameworks/Libraries

The appliance includes the leading Python Templating Frameworks and Libraries.

The included templating frameworks are:

This list does not include python web frameworks that have their own embedded templating approach such as Django, Quixote, etc.

4.7 Python Libraries and Frameworks

4.8 Web/Application Servers and Middleware

Web/Application server related:

Python WSGI middleware related:

4.9 Database and API Interfaces


Python DB-API interfaces to the above databases:

4.10 Object Relational Mapping Tools

4.11 Testing Tools

4.12 AJAX libraries and frameworks

5 Using the Appliance

5.1 Appliance IP Address

By default the appliance receives it's IP address via DHCP. To view the assigned IP address login as root and the IP address will be displayed or use the /usr/local/pyweb/pyweb/sbin/ command to view the system IP address(es). Each time the root user logs in the system's IP address will be displayed.

If using DHCP is not satisfactory, one can change the virtual machine and operating system to use a static network configuration.

DHCP was selected as the default to be most compatible across all VMware host operating systems and environments.

5.2 Logging In

One may login into the appliance either on the system console or by SSH.

To login via SSH, connect as the root user to the IP address of the appliance.

Warning: If you remove the password on root you will no longer be able to remotely login via ssh. This is controlled by the sshd configuration in /etc/ssh/sshd_config.

If you're using a Win32 system and you need a free SSH client you may want to try Putty

5.3 Accessing the Appliance Web Site

To view the pre-configured appliance web site use the following URL http://w.x.y.z/ replacing w.x.y.z with the IP address of your appliance. If you don't know the IP address of your appliance use the /usr/local/pyweb/pyweb/sbin/ command or login to the system as the root user.

For example, on my VMware test machine the DHCP addresses I got assigned was so I accessed the system with an address of "".

6 Appliance Features

6.1 Pre-configured Daemons

The appliance is pre-configured to start the following daemons.

The sshd daemon is started by the OpenBSD rc script and the rest of t he daemons are started by the /etc/rc.local script.

6.2 Pre-configured PostgreSQL Database

A PosgreSQL database and user have been configured and are available at startup. The database name is pywebdb and the username/password is pywebuser/user.

All the standard PostgreSQL binaries and tools may be found under /usr/local/pyweb/pgsql.

6.3 Pre-configured Zope3 Instance

A Zope3 instance is created upon installation in the /var/pyweb/zope3 directory. The default zope admin username/password is zope3admin/admin.

6.4 MySQL Database

MySQL is installed at /usr/local/pyweb/mysql from a community edition release from No pre-configuration has been done for the MySQL database.

Please follow the documentation for MySQL (/usr/local/pyweb/mysql/INSTALL-BINARY to setup and configure the MySQL database.

6.5 Pre-configured Appliance Web Site

The appliance is pre-configured with a default web site with a bit of content that may be helpful.

Please substitute your appliance's IP address for in the following table.

URL Content appliance web site home appliance User Guide Python 2.4 Language Reference Python pydoc documentation server Dive Into Python Book Link to the Zope3 Instance Link to the Zope3 Instance Mgmt Apache Documentation

The pydoc server is also accessible on port 8888 ( and the Zope3 instance is also accessible on port 8080 (

6.6 Starting and managing other Daemons

The appliance includes the python based daemon manager Supervisor Supervisor makes it easy to manage additional daemons that may need to be running for your web applications. Please refer to the information at the Supervisor Project page for how to configure Supervisor.

6.7 Supporting Python Libraries

A collection of python libraries not specifically related to web application programming but often used in web application programming have been included. These libraries support such things as the generation of PDF documents (ReportLab), the creation and manipulation of images and graphics (PIL), object-relational mapping (SQLAlchemy/SQLObject), checking python source files (pychecker, pylint), the creation of powerful network servers (Twisted), and tools to accelerate Python on i386 systems (Psyco).

6.8 Supporting Python WSGI Libraries

A collection of WSGI middleware and scripts are included in the appliance including the Paste suite, Rhubarbtart, Colubrid, WSGI Utils, and flup.

6.9 Version Control and Project Management

Both CVS and Subversion are included on the appliance as well as the Trac project mangement tool.

7 Next Steps?

Please contact me via email at if you have an interest in seeing the Python Web Developer Appliance continue as an on-going open source project.

By using the combination of pkgsrc and working towards a comprehensive use of Python Eggs, for future releases it should be feasible to release a version of the appliance that is installable on any of the (twelve or so) *nix platforms that pkgsrc supports delivered as virtual machines and (normal) installable software.

Also, it may make sense to offer one or more targeted distributions such as a "Django Web Developers" release or a "TurboGears Web Developer" release that have a more focused/slimmer software stack aimed a developer using a specific framework.

Note: For the Python frameworks and libraries whose users (and authors) feel that I should have included but have not included, I sincerely apologize. Please do not interpret my oversight as a judgment on the usefulness and/or quality of your project. If there is interest in continuing the python web developer appliance project I look forward to including the projects that I missed in the first iteration of the appliance.

8 Errata and Known Issues

8.1 Errata

Please check for current status, patches, errata, and updated documentation.

Warning: This appliance has been assembled in May of 2006 in the weeks preceding the VMware Virtual Appliance contest submission date of May 26, 2006. In addition, several of the included Python Web frameworks are in a pre-version 1.0 release status with APIs that are subject to change. As a result, while the appliance is currently useful as a development and learning tool it is not likely to be a good choice for a production environment.

8.2 Known Issues

9 License

The shell and python scripts that I've written for this project are released under the GNU General Public License version 2 as published by the Free Software Foundation.

About this document ...

Python Web Developer
Appliance Users Guide
, June 6, 2006, Release DRAFT

This document was generated using the LaTeX2HTML translator.

LaTeX2HTML is Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The application of LaTeX2HTML to the Python documentation has been heavily tailored by Fred L. Drake, Jr. Original navigation icons were contributed by Christopher Petrilli.