µWeb

h1. Application

Provided with µWeb is a script named @uweb@ which when [[Installation|installed]] using @pip@ will be located on your path, i.e. globally executable. With this application you can create and manage µWeb projects and webservers for testing purposes.

h2. Creating new µWeb projects

New µWeb projects can be created (initialized) by running the @uweb init@ command. With this, you have to specify the name of your project, as follows:

<pre><code class="bash">

uweb init boondoggle

</code></pre>

This creates a µWeb project named @boondoggle@ in the current directory. All the necessary files are copied to this directory and a router configuration entry is made (more about that later). What's important now is picking the right name for your project (of course, you can change it, but a good name gets you going). The script will do its thing and tell you when it's done:

<pre>

elmer@Penrose:~$ uweb init boondoggle

+--------------------------------------------------------------+

| initializing new uWeb project 'boondoggle'                   |

+--------------------------------------------------------------+

* copying uWeb base project directory

* setting up router

* setting up apache config

+--------------------------------------------------------------+

| initialization complete - have fun with uWeb                 |

+--------------------------------------------------------------+

</pre>

h3. Error: Target already exists

Sometimes you end up using the same really good name twice. µWeb will warn you that there's already a directory with the given name, it won't readily use this directory and destroy its contents. You can use the @-f@ flag to force the initialization in that directory.

*N.B.*: This will delete any and all existing data in the target directory. It will not _merge_ the µWeb project.

h2. Controlling the development webserver

The uweb script can also be used to list all projects, control and configure development webserver. All the information used here is stored in the @sites.json@ file, stored in the @.uweb@ directory in your homedir.

h3. Listing µWeb projects

µWeb comes preloaded with a set of two example projects, and now our project is listed as well:

<pre>

elmer@Penrose:~$ uweb list

Overview of active sites:

 +------------+---------------------------------+-------------+

 | Name       | Router                          | Working dir |

 +------------+---------------------------------+-------------+

 | boondoggle | boondoggle.router.boondoggle    | /home/elmer |

 | logviewer  | uweb.logviewer.router.logging   | /           |

 | uweb_info  | uweb.uweb_info.router.uweb_info | /           |

 +------------+---------------------------------+-------------+

</pre>

We can see three projects here:

* Our newly initialized @boondoggle@ project, aspiring to be the new social media synergy machine.

* @logviewer@, which is a handy viewer for µWeb's SQLite logfiles

* @uweb_info@, a demonstration project for various µWeb functionalities and abstractions.

h3. Starting and stopping µWeb projects

µWeb projects by default run on port 8082 (and bind to all IP addresses on the machine, so they're also reachable by other people on the network). This can be configured by changing the configuration files for [[Standalone]], and in fact the two projects that come with µWeb run on different ports:

* The @logviewer@ runs on port 8001

* @uweb_info@ runs on port 8000

Starting a µWeb project using the @uweb@ application is simple enough:

<pre>

uweb start boondoggle

</pre>

You can then point your webbrowser to http://localhost:8082/ and you'll be greeted with a basic HTML page welcoming you to your new project.

The development server can be stopped or restarted using the @stop@ and @restart@ commands:

<pre>

uweb stop boondoggle

</pre>

h3. Removing routers

If you need to remove a project from the project list (because you no longer need to test it locally, or any other reason) you can remove it from the list using @uweb remove@:

<pre>

uweb remove boondoggle

</pre>

If this executes successfully, no feedback will be given, it will simply be removed from the internal list of sites, and no longer displayed upon new @uweb list@ commands. This will *not* remove the project's directory from disk, and if you feel the need, you can re-add the project to the list again, as explained in the next portion.

h3. Adding / updating routers

If you join in on an existing µWeb project, or you need to re-add a previously existing router to the project list, @uweb add@ does exactly that. In it's basic form it maps a router module to a name:

<pre>

uweb add boondoggle boondoggle.router.boondoggle

</pre>

The dots are important because the µWeb project is meant to work as a Python package. This means that the [[router]] in boondoggle can go 'up' in the package and find its [[pagemaker]]. This also means that the boondoggle directory must be on your PYTHONPATH.

If the project's main directory is not on your path, you can provide the directory where it does reside with the @--directory@ option:

<pre>

uweb add boondoggle boondoggle.router.boondoggle --directory /home/elmer

</pre>

This way, the router will first change the working directory to @/home/elmer@ and from there it will try to import the @boondoggle@ package. This means that you can have multiple packages with the same name and as long as you keep them in separate working directories, you can run them all in µWeb.

By default, @uweb add@ will not overwrite (or update) existing information. If we want our new boondoggle working directory to work, we need to provide the @--update@ flag, as follows:

<pre>

uweb add boondoggle boondoggle.router.boondoggle --directory /home/elmer --update

</pre>

h3. Creating Apache configurations