# Configuring and Using the Twisted.Web Server

## Installation

To install the Twisted.Web server, you'll need to have installed Twisted.

Twisted servers, like the web server, do not have configuration files. Instead, you instantiate the server and store it into a 'Pickle' file, `web.tap`. This file will then be loaded by the Twisted Daemon.

    % mktap web --path /path/to/web/content

If you just want to serve content from your own home directory, the following will do:

    % mktap web --path ~/public_html/

Some other configuration options are available as well:

- `--port`: Specify the port for the web server to listen on. This defaults to 8080.
- `--logfile`: Specify the path to the log file.

The full set of options that are available can be seen with:

    % mktap web --help

## Configuration

Once you've created a tap file, you can use COIL, a browser based interface, to configure it. Run this command:

    % coil web.tap

And then point your browser to http://localhost:9080 to see the config interface. If you're configuring this on a remote machine, then substitute the name of that machine for `localhost`.

Once you've finished configuring the server, hit Ctrl-C in the terminal where you run coil in order to shutdown the web server and save your changes.

You're now ready to start your Twisted.Web server!

## Using Twisted.Web

### Stopping and Starting the Server

Once you've created your `web.tap` file and done any configuration, you can start the server:

    % twistd -f web.tap

You can stop the server at any time by going back to the directory you started it in and running the command:

    % kill `cat twistd.pid`

### Serving Flat HTML

Twisted.Web serves flat HTML files just as it does any other flat file.

### Embedded Python Scripts

An Embedded Python script is a Python file ending with the extension `.epy`, which is executed by the Twisted Web server.

Embedded Python scripts have 2 special variables defined within their namespace:

- `__file__`: The name of the .epy file, including the full path.
- `request`: An instance of `twisted.web.server.Request`.

A very simple Embedded Python Script might look like:

    request.write("""

    <html>
        <head><title> Welcome To Twisted Python </title></head>

        <body>
        This is a demonstration of embedded python in a webserver.
        </body>
    </html>
    """)

### Resource Scripts

A Resource script is a Python file ending with the extension `.rpy`, which is required to create an instance of a (subclass of a) `twisted.web.resource.Resource`.

Resource scripts have 2 special variables:

- `__file__`: The name of the .rpy file, including the full path. This variable is automatically defined and present within the namespace.
- `resource`: The variable which must be defined by the script and set to the resource instance that will be used to render the page.

A very simple Resource Script might look like:

    from twisted.web import resource
    class MyGreatResource(resource.Resource):
        def render(self, request):
            return "<html>foo</html>"

    resource = MyGreatResource()

### DOM Templates

The DOM Templates system is a system for handling templated content. See its documentation for more details.

### Spreadable Web Servers

One of the most interesting applications of Twisted.Web is the distributed webserver; multiple servers can all answer requests on the same port, using the `twisted.spread` package for "spreadable" computing. In two different directories, run the commands:

    % mktap web --user
    % mktap web --personal [other options, if you desire]

Both of these create a `web.tap`; you need to run both at the same time. Once you have, go to http://localhost:8080/your_username.twistd/ -- you will see the front page from the server you created with the `--personal` option. What's happening here is that the request you've sent is being relayed from the central (User) server to your own (Personal) server, over a PB connection. This technique can be highly useful for small "community" sites; using the code that makes this demo work, you can connect one HTTP port to multiple resources running with different permissions on the same machine, on different local machines, or even over the internet to a remote site.