Startup

web2py comes in binary packages for Windows and Mac OS X. They include the Python 2.7 interpreter so you do not need to have it pre-installed. There is also a source code version that runs on Windows, Mac, Linux, and other Unix systems. The source code package assumes that Python 2.7 or 3.5 (or even newer) is already installed on the computer.

web2py requires no installation. To get started, unzip the downloaded zip file for your specific operating system and execute the corresponding web2py file.

On Unix and Linux (source distribution), run:

python web2py.py

On OS X (binary distribution), run:

open web2py.app

On Windows (binary web2py distribution), run:

web2py.exe

On Windows (source web2py distribution), run:

c:\Python27\python.exe web2py.py

Attention, to run web2py on Windows from source you must install first Mark Hammond’s win32 extensions from http://sourceforge.net/projects/pywin32/.

The web2py program accepts various command line options which are discussed later.

By default, at startup, web2py displays a startup window and then displays a GUI widget that asks you to choose a one-time administrator password, the IP address of the network interface to be used for the web server, and a port number from which to serve requests. By default, web2py runs its web server on 127.0.0.1:8000 (port 8000 on localhost), but you can run it on any available IP address and port. You can query the IP address of your network interface by opening a command line and typing ipconfig on Windows or ifconfig on OS X and Linux. From now on we assume web2py is running on localhost (127.0.0.1:8000). Use 0.0.0.0:80 to run web2py publicly on any of your network interfaces.

If you do not provide an administrator password, the administration interface is disabled. This is a security measure to prevent publicly exposing the admin interface.

The administrative interface, admin, is only accessible from localhost unless you run web2py behind Apache with mod_proxy. If admin detects a proxy, the session cookie is set to secure and admin login does not work unless the communication between the client and the proxy goes over HTTPS; this is a security measure. All communications between the client and admin must always be local or encrypted; otherwise an attacker would be able to perform a man-in-the middle attack or a replay attack and execute arbitrary code on the server.

After the administration password has been set, web2py starts up the web browser at the page:

http://127.0.0.1:8000/

If the computer does not have a default browser, open a web browser and enter the URL.

Clicking on “administrative interface” takes you to the login page for the administration interface.

The administrator password is the password you chose at startup. Notice that there is only one administrator, and therefore only one administrator password. For security reasons, the developer is asked to choose a new password every time web2py starts unless the option is specified. This is distinct from the authentication mechanism in web2py applications.

After the administrator logs into web2py, the browser is redirected to the “site” page.

This page lists all installed web2py applications and allows the administrator to manage them. web2py comes with three applications:

• An admin application, the one you are using right now.
• An examples application, with the online interactive documentation and a replica of the web2py official website.
• A welcome application. This is the basic template for any other web2py application. It is referred to as the scaffolding application. This is also the application that welcomes a user at startup.

Ready-to-use web2py applications are referred to as web2py appliances. You can download many freely available appliances from [appliances] . web2py users are encouraged to submit new appliances, either in open-source or closed-source (compiled and packed) form.

From the admin application’s site page, you can perform the following operations:

• install an application by completing the form on the bottom right of the page. Give a name to the application, select the file containing a packaged application or the URL where the application is located, and click “submit”.
• uninstall an application by clicking the corresponding button. There is a confirmation page.
• create a new application by choosing a name and clicking “create”.
• package an application for distribution by clicking on the corresponding button. A downloaded application is a tar file containing everything, including the database. You should not untar this file; it is automatically unpackaged by web2py when installed with admin.
• clean up an application’s temporary files, such as sessions, errors and cache files.
• enable/disable each application. When an application is disabled it cannot be called remotely but it is not disabled from localhost. This means disabled applications can still be accessed behind a proxy. An application is disabled by creating a file called “DISABLED” in the application folder. Users who try to access a disabled application will receive a 503 HTTP error. You can use routes_onerror to customize the error page.
• EDIT an application.

When you create a new application using admin, it starts as a clone of the “welcome” scaffolding app with a “models/db.py” that creates a SQLite database, connects to it, instantiates Auth, Crud, and Service, and configures them. It also provides a “controller/default.py” which exposes actions “index”, “download”, “user” for user management, and “call” for services. In the following, we assume that these files have been removed; we will be creating apps from scratch.

web2py also comes with a wizard, described later in this chapter, that can write an alternate scaffolding code for you based on layouts and plugins available on the web and based on high level description of the models.