This document details how to configure a user-managed webserver at CSLab. Please see the overview for information on user-managed webserver in general.
Setting up a user-managed webserver is done by running a program on colony.cs, the main webserver:
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 started automatically when colony.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 colony)./cs/htdata/user-webserver/makesite
The important paths for this user-managed webserver are:
Your user-managed webserver has been pre-configured with almost all of the Apache modules that are available on colony.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.
Once you've created your user-managed webserver, you can set up a MySQL database for it by running:
$HOME/site/bin/mysql-initThe MySQL database files will be put into $HOME/site/db, and things will be arranged so that your MySQL server is started when colony.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.
Once you've set up your user-managed webserver with your application, contact your Point of Contact 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, and 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.
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.
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:
$HOME/site/bin/apache2ctl stop
$HOME/site/bin/mysqladmin shutdown
If you need help with any parts of this process, you should talk to your Point of Contact.
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 colony.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 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.