BIRCH on a multiuser system - Getting the Documentation onto the Web
 update July 20, 2026
This section is mainly relevant if your BIRCH installation is for multiple user accounts, for example, in a server-based environment, as opposed to a single user on a personal desktop computer or laptop.

Purpose:

The BIRCH web site has a large number of pages that link to each other, as well as linking program documentation and datafiles. As well, some documentation files opened by BioLegato applications are HTML files that need to be viewed in a web browser.

Special case: A standalone computer (eg. in a lab) that does not run a web server, but does have multiple user accounts.

Until recently, if you installed a copy of BIRCH on a single account, the BIRCH documentation was easiily readable by all other accounts, since BIRCH is installed with world-readable permissions.
In that (default) case, BIRCH documentation files had a URL beginning with something like "file:///home/birch/public_html...". However, recent web browsers such as Firefox no longer allow access to files outside of one's own home directory. This is a security measure, albeit a clumsly and crude one.

To get around this problem, you will need root privileges to configure a local web server that should be accessible by others on your local network (eg. a VLAN).

1. Install the apache web server - On Ubuntu or related distros, "apt install apache2". On RedHat (Fedora) and related distros, see https://linuxcapable.com/how-to-install-apache-httpd-on-fedora-linux/. On MacOS, see https://discussions.apple.com/docs/DOC-250009910

2. Allow users to have personal web sites.
(From https://stackoverflow.com/questions/526742/how-can-i-make-a-public-html-folder-in-ubuntu)

Assuming you've already installed apache2, do the following:

sudo a2enmod userdir
sudo systemctl restart apache2

The first command enables the userdir apache mod, which allows each user to have a web site in their $HOME/public_html directory. The second reloads apache configurations so that it starts using the new configuration.

To make your BIRCH site available on the local network, you also need to make a symbolic link from birch's home directory to the BIRCH web directory:

As birch, go to your $HOME directory (eg. /home/birch) and type

ln -s BIRCH/public_html

If you type ls -l, the link should look something like

lrwxrwxrwx  1 birch birch      17 Jul 18 17:19 public_html -> BIRCH/public_html

Finally, you need to change links in the BIRCH documentation so that all links read the documentation through your local web server. This is done in the birchadmin tool, as shown below.


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.


From the BIRCH Launcher, choose File --> birchadmin to launch the BIRCH Administration Tool. In birchadmin, choose Preferences --> Properties to launch the BIRCH Properties Tool (birchprops).

Alternatively, you can launch birchprops from the command line as follows:

cd to the install-scripts directory and type

./birchprops.sh



Click on  "Set Web Location for Documentation" Currently, all documentation contains links like those seen in the lower panel (Documentation is accessible only by local login). Click on "Make Documentation Web Accessible.  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. For example, if you were installing BIRCH in /home/birch/BIRCH on a local machine,



NOTE: If you look closely, you'll see that the "dots" are built into the interface. This is a bit of a kludge, so in the example, the IP address 10.0.0.37 is split up among "prefix", 2° Level Domain and 1° Level Domain.

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://brassica.plants.umanitoba.ca/~birch,  the URL for the file $BIRCH/doc/xylem/shuffle.txt would be http://brassica.plants.umanitoba.ca.ca/~birch/birchhomedir/doc/xylem/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/~birch. 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:



In another example, the URL for the BIRCH home directory is input like this:



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 birchprops.  You can probably ignore this section.

Running customdoc.py and htmldoc.py

To implement the changes in the BIRCH web site, birchprops writes changes to the file $BIRCH/local/admin/BIRCH.properties, and also to $BIRCH/local/admin/newstr.param.

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 birchprops wizard would have created an $BIRCH/local/admin/newstr.param file that looked something like this:

~
file:///home/birch/BIRCH/public_html/index.html
file:///home/birch/BIRCH
brian.fristensky@umanitoba.ca
/home/birch/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-scripts/oldURL.param by copying these 2 lines. For example:

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

Now create another file called  install-scripts/newURL.param, for example:
 
http://flamingo.plants.umanitoba.ca/~birch
http://flamingo.plants.umanitoba.ca/~birch/birchhomedir

To make the changes, run customdoc.py:

python3 customdoc.py oldURL.param newURL.param htmldir.param

Alternatively, in birchadmin, choose Documentation --> customdoc.py.

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\://flamingo.plants.umanitoba.ca/~birch/birchhomedir
http\://flamingo.plants.umanitoba.ca/~birch
brian.fristensky@umanitoba.ca
/home/birch/BIRCH
birch

Finally, edit your $birch/local/admin/BIRCH.properties to change BirchProps.birchURL and BIRCHProps.birchHomeURL so that the file looks like this:

#Birch Properties
#Fri Jul 08 17:00:56 CDT 2016
BirchProps.BirchMasterCopy=
BirchProps.adminUserid=birch
BirchProps.minibirch=false
BirchProps.homedir=/home/birch/BIRCH
BirchProps.platform=linux-x86_64
BirchProps.adminEmail=brian.fristensky@umanitoba.ca
BirchProps.birchURL=http\://flamingo.plants.umanitoba.ca/~birch
BirchProps.birchHomeURL=http\://flamingo.plants.umanitoba.ca/~birch/birchhomedir
IMPORTANT: Note that the ':' characters in the URLs MUST be escaped with backslash characters! If you do not do that, sql2htmldoc.py will not create valid URLs.


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

Finally, we need to run htmldoc.py to change the links on the web documentation pages for each package and program in BIRCH.

cd $birch/install-scripts
./sql2htmldoc.py

Alternatively, in birchadmin, choose Documentation --> htmldoc.py.

Reload the home page in your web browser, and all links should work.


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