BIRCH
BIRCH - Getting the Documentation onto the Web

Purpose:

The BIRCH web site has a large number of pages that link to each other, as well as linking program documentation and datafilees. While most of the URLs in these links are "relative URLs", it is necessary that some of them be fully qualified URLs, particularly for documentation and datafiles. When you initially install BIRCH, the documentation and datafiles may not all be web-accessible. In this tutorial, we use the BIRCH  URL Builder to find out the URL that will reach your copy of the BIRCH home page. This may require a bit of experimentation to get it exactly right. (You may wish to check with your web administrator to find out how to determine the URL for your BIRCH web site.) Once you have the correct URLs, birchconfig will change URLs in the BIRCH documentation so that they are all accessible through your BIRCH web site.

We need to be able to find a URLs that will point to

If you already know a lot about web servers and URLs, you may wish to look at the EXAMPLES page now.

cd to the install-birch directory and start birchconfig:

./birchconfig.sh



Choose "Set Web Location for Documentation"



Currently, all documentation contains links like those seen in the lower panel (Documentation is accessible only by local login). This menu will help you find the URLs that are needed for the BIRCH documentation.

Read the next section before proceeding further!

First: Is there a web server (eg. Apache) running on the host where BIRCH is installed?

In the simplest case, there is a web server such as Apache running on the same host as BIRCH. In the figure, BIRCH has been installed on a host called intron.mylab.ca, in /home/birch. In a typical Apache installation, the user's web site is found in $HOME/public_html, or in this case, /home/birch/public_html. By default, the home page is called 'index.html', and this name need not be included in the URL. Again, typically there is a web server running on the same host whose name starts with 'www' or maybe 'home'. URLs therefore have the general structure:

http://www.hostname.domain/~userid

or

http://home.hostname.domain/~userid
Figure 1.

which tells the web server to automatically look at the $HOME/public_html directory for the user whose name is userid. In this case, the URL for the BIRCH home page should be http://www.mylab.ca/~birch. (At some sites, the tilda (~) is not used).


Figure 2.

The second possibility is that the web server is running on a different host from BIRCH. If that is the case, the only way to get the BIRCH web site to be accessible to the world is if the BIRCH home directory is remotely mounted (eg. via NFS) on the web host. In this scenario, all users are assumed to have a web directory on the web server, www.mylab.ca, within the /data/home  directory.  You would need to ask your web administrator to remotely mount your BIRCH web directory (/home/birch/public_html) a this point on the web server. (If security is an issue, your directory could be mounted read-only). Again, the URL for your web site would be  something like http://www.mylab.ca/~birch.

EXAMPLES of URLs

Make your webmeister happy!  Tell him/her/it that the BIRCH web site does NOT use CGI, PHP or Javascript. It is nothing more than read-only documentation.

Once you have determined the correct URL for your BIRCH site,  find the text frame labeled "URL for BIRCH Web site" and click on the URL Builder button.



The URL Builder is a tool for constructing and testing URLs to make sure that they work. Pull-down menus contain possible choices for different parts of a URL, and you can type in any text box to change these values. When you think you have a working URL, press the "Test" button. If your URL is correct, you will see a target web page in the HTML viewer:



If you see this window, you can click on "OK" and then Return to the "Change URLs" window. If you got an error message such as "Can't open connection to...." try again. You may need to consult with your system administrator to find the correct URL.

Next: we need to be able to link to files outside of $BIRCH/public_html

Typically, the web server assumes that all your web pages are in your public_html directory. For a lot of good organizational reasons, this is not practical to do in BIRCH. For example, we might want link to any of the documentation files in $BIRCH/doc or the data files in $BIRCH/dat, or the local web pages in $BIRHC/local/public_html. The problem has already been solved for you because $BIRCH/public_html contains a symbolic link to the BIRCH home directory. If you go to $BIRCH /public_html and type 'ls -l' you'll see

lrwxrwxrwx   1 birch  birch        2 Apr 17  2003 birchhomedir -> ../

That way, you can create a URL for any file in any BIRCH directory. For example, for the BIRCH site at http://www.visualgenomics.ca/~birch,  the URL for the file $BIRCH/doc/xylem/shuffle.txt would be http://www.visualgenomics.ca/~birch/birchhomedir/doc/xylem/shuffle.txt.

But what if your web server doesn't allow the use of symbolic links on personal home pages?

For security reasons, some systems that allow web sites for individual users do not allow the use of symbolic links within public_html, especially if they point to directories outside of public_html. One way around this is to have your web master create a symbolic link from some directory on the web server to the remotely-mounted BIRCH home directory. For example, the main BIRCH web site is at http:/home.cc.umanitoba.ca/~psgendb. Since symbolic links are not allowed for users at out site, there is a link from the web server at www.umanitoba.ca. This link is called 'birch', and is found in the '/www/data/faculties/afs/plant_science/' directory. The URL that points to the BIRCH home directory is therefore http://www.umanitoba.ca/faculties/afs/plant_science/birch.  If you click on this link, what you'll see is not an HTML web page, but rather a directory listing of the BIRCH home directory. To link to the file $BIRCH/doc/xylem/shuffle.txt, we would use the URL
http://www.umanitoba.ca/faculties/afs/plant_science/birch/doc/xylem/shuffle.txt

Find the URL for the BIRCH Home directory

The BIRCH Home directory can be reached in either of two ways. $BIRCH/public_html/birchhomedir is a symbolic link to $BIRCH. If you web server allows symbolic links, the URL might look something like http://intron.mylab.ca/~birch/birchhomedir. If $BIRCH is remotely mounted to a web server (eg. www.mylab.ca), you could link directly to that directory eg. http://www.mylab.ca/birch.

Click on the "URL Builder" button with the label "URL for BIRCH Home Directory".
Again, enter the URL that you think is correct and Press the "Test" button. If your BIRCH Home Directory was successfully found, you will see a window something like:



When you  are successful, press "Apply", and then Return to the "Change URLs..." window. The window now should have both of the new URLs:



You are now ready to change the URLs in the BIRCH documentation. Press the Apply button to begin, or Return to Main Menu if you don't want to change the URLs at this time.



The remainder of this document tells how to change URLs in documentation manually, without using birchconfig.  You can probably ignore this seciton.

Running customdoc.py

By now you should know
  1. URL for your BIRCH web site
  2. URL for your BIRCH home directory
The python script customdoc.py will substitute your values for the current ones. When you do a new BIRCH installation, these two URLs are set to refer to local files. For example, if  the BIRCH home directory is /home/birch, the birchconfig wizard would have created an install-birch/newstr.param file that looked something like this:

~
file:///home/birch/public_html/index.html
file:///home/birch
birch@mylab.ca
/home/birch
birch

These are the values that were substituted into BIRCH web documentation when you did the new install. The "file:///" strings need to be replaced by the correct URLs. Create a file called install-birch/oldURL.param by copying these 2 lines. For example:

file:///home/birch/public_html/index.html
file:///home/birch

Now create another file called  install-birch/newURL.param, for example:
 
http://www.mylab.ca/~birch
http://www.mylab.ca/~birch/birchhomedir

To make the changes, run customdoc.py:

python customdoc.py oldURL.param newURL.param htmldir.param

The script will echo the names of directories visited, and lines changed to the terminal window.
You can also use customdoc.py  for future automated changes to web pages by creating your own .param files.

At this point, the documentation for your local copy of BIRCH should have custom filepaths, directory names, email addresses etc.

... wait, we're not done yet

When you're sure that the URLs have been correctly changed in the BIRCH documentation, we need to make the changes permanent. The file newstr.param, is read when updating to a new version of BIRCH, and also when when you add new documentation to the $BIRCH/local directory. This file still contains the URLs that you copied to oldURL.param. You need to replace those with the URLs from newURL.param. Thus, your final newstr.param file might look something like:

~
http://www.mylab.ca/~birch
http://www.mylab.ca/~birch/birchhomedir
birch@mylab.ca
/home/birch
birch

The good news: Once newstr.param is correct, you should never have to think about it again. Every time you update to a new version of BIRCH, the values in newstr.param will be used.

Please send suggestions of comments regarding this page to frist@cc.umanitoba.ca