Setting up a user-managed webserver

Setting up a user-managed webserver is done by running a program on settlement.cs, the user-managed webserver host: 

/cs/htdata/user-webserver/makesite

This will create a directory hierarchy for your user-managed webserver in /u/user/site and tell you some important information about the webserver, especially the port that has been assigned to it. Your user-managed webserver will be restarted automatically when settlement.cs reboots, and its Apache logs will be automatically rotated periodically (for details of how this is done, see the output of 'crontab -l' on settlement).

The important paths for this user-managed webserver are:

  • $HOME/site/www

    The Apache document root. A basic index.html page has been created there for you.

    $HOME/site/cgi-bin

    A standard CGI-BIN directory; this is visible as /cgi-bin in your user-managed webserver.

    $HOME/site/conf

    Configuration files for Apache, PHP, and MySQL.

    $HOME/site/logs

    The Apache logs for your user-managed webserver.

    $HOME/site/bin

    Scripts to manage your Apache and MySQL instances; the most important is apache2ctl, which is used to start and stop your Apache webserver.

    $HOME/site/site-config

    A file with all of the important information about your user-managed webserver. You should not normally edit this file.

Your user-managed webserver has been pre-configured with almost all of the Apache modules that are available on settlement.cs; you can see the list of enabled modules by looking in /cs/htdata/user-webserver/conf/mods-enabled. If an Apache module that you need is not on the list, you should talk to your POC.

Setting up MySQL

Once you've created your user-managed webserver, you can set up a MySQL database for it by running: $HOME/site/bin/mysql-init The MySQL database files will be put into $HOME/site/db, and things will be arranged so that your MySQL server is restarted when settlement.cs reboots.

During this process, you will be asked to set the MySQL root password. Anyone who knows this password has complete control over your MySQL databases; they can stop the server, remove database tables, edit tables freely, and so on. You should keep this password secure.

/!\ IMPORTANT: You must arrange to make database backups of your MySQL database by properly configuring a program such as mysqldump (unfortunately this problem is sufficiently complicated that it cannot be automated by mysql-init). While CSLab takes system-level backups, they may not be sufficient to recover your MySQL database in the event that something happens to it.

Arranging reverse proxying

Once you've set up your user-managed webserver with your application, contact your PoC to get the appropriate reverse proxying set up. They will need to know:

  • What URL on the main server you want mapped to what URL on your user-managed webserver.
  • What port your user-managed webserver is running on.

The URL on the main server that you want mapped to your user-managed webserver will normally be under your CSLab home page, for example http://www.cs.toronto.edu/~user/wiki. The URL on your user-managed webserver that it maps to is up to you.

Issues with reverse proxying

As mentioned in the overview, web applications that you use on your user-managed webserver must be aware that they are running behind a reverse proxy. The most important issue here concerns URLs.

When you are behind a reverse proxy, there are effectively two sorts of URLs: 'inside' URLs, URLs on your user-managed webserver, which are what appear in HTTP requests that you process, and 'outside' URLs, which URLs before the reverse proxy remapping has happened and what you want to output in HTML pages, HTTP redirections, and so on, because people seeing your web pages from outside can only use outside URLs. Your applications need to know the difference between the two sorts of URLs, and accept inside URLs while generating outside URLs.

To some extent you can camouflage the difference between the two sorts of URLs by using the same URL on your user-managed webserver as on the main webserver. For example, instead of mapping http://www.cs.toronto.edu/~user/wiki on the main server to /wiki on your server, you would map it to /~user/wiki. This leaves the different ports as the only change between inside and outside URLs.

Removing a user-managed webserver

There's a number of steps that are necessary to turn off and remove a user-managed web server. The following list is for servers that haven't been particularly customized:

  1. If you have a reverse proxy set up, tell your POC that you want it removed.
  2. Stop your Apache server (and your MySQL daemon if it's enabled): 

$HOME/site/bin/apache2ctl stop
$HOME/site/bin/mysqladmin shutdown

  1. Use crontab -e to remove the entries that were added by makesite, and any additional ones that you've added.

  2. Release your port reservations. In the simple case (where you only have one user-managed webserver), just remove any files owned by you that are in the /cs/htdata/user-webserver/ports directory.

  3. Finally, if you are confidant that you don't want any data from your user-managed webserver, you can remove the $HOME/site directory hierarchy itself. You should make sure that you copy or back up any data from it that you want to keep.

If you need help with any parts of this process, you should talk to your Point of Contact.

Some words on customizing your Apache server

Your Apache server's configuration is split into two parts: the part specific to your user-managed webserver instance, and the parts generic across all normal user-managed webservers. The former is in $HOME/site/conf/httpd.conf and includes the latter, which lives in a system directory.

There are three sorts of customizations that you might want to make to your user-managed webserver: adding configuration directives, adding additional modules, and changing existing elements of the configuration. Adding configuration directives is the easy customization, as it can be done by editing your own httpd.conf.

To change existing elements of the configuration, you will need to make a private copy of the generic portions of the generic configuration, change your httpd.conf to include that copy instead of the system-wide one, and then edit your copy appropriately.

Your Apache server should already include almost all of the useful Apache modules that are available on settlement.cs. If you need additional modules, there are two options. First, if the module is available as a standard Ubuntu package, you can talk to your Point of Contact (PoC) to have it installed and made available for all user-managed webservers, yours included. If the module you want is not available that way (or is not suitable for inclusion in all user-managed webservers), you will need to build the module yourself, put it somewhere, and then change your httpd.conf to directly include the module.

Security Updates

When security updates are applied to the server hosting user-managed webservers, the machine may be restarted to ensure user-run services are not frozen by any changes the security updates make to programs they may use, like mysql. Users should also regularly check for security updates if they are using any local software packages for their website and update as needed.