Afterwards, the folder /Users/<username>/Sites/blast should exist (or the equivalent on other operating systems). Technically there is no reason it cannot be in any directory in the DocumentRoot e.g. /Users/ben/Sites/myblasts/blast, but the simplest directory is assumed in this howto. For the rest of the tutorial the directory /User/ben/Sites/blast is assumed to be base directory of the blast installation, and 'ben' is assumed to be the user logged into the computer.

After saving the file, restart the apache webserver. The simplest way is to restart the computer. If restarting the computer is not possible you can restart the server using apache2ctl, with administrator privileges:

$ sudo apache2ctl graceful

After restarting, you should be able to run a blast against the default test databases at http://localhost/blast/blast.html. You can use the sequence TACTGTTATCGATCCGGTCGAAAAACTGCTGGCAGTGGGGCATTACCTCGAATCTACCGTCGATATTGCT to test, against test_na_db using blastn. You should get a hit, not a half-blank page.

Getting the BLAST overview image to work

If there is no image showing how the blast sequence worked, and instead in its place was the an error message similar to below though with the numbers being different:

fail to open file TmpGifs/1804289383790.gif

This can be fixed by giving every user on the computer write access to the TmpGifs folder. In a terminal (on Linux, need administrator privileges):

$ chmod o+w /Users/ben/Sites/blast/TmpGifs/

There should be no output from this command. If the permissions have been changed correctly, the overview image should work.

Creating custom databases

By default, wwwblast only comes with a few databases that are generally not useful. Instead the researcher wants to BLAST against sequences generated in their own lab, for instance. To make a custom sequence database from a FASTA file, 3 steps are required: converting the fasta file into a binary blast database, changing the blast.html so that the database can be selected from the drop-down menu, and modifying blast.rc.

Converting a fasta file into a binary BLAST database

A binary BLAST database is a collection of multiple files (.nhr, .nin and .nsq files for nucleotide databases). They must be created from a fasta file in a terminal, using the BLAST+ toolkit, available from NCBI (PubMed citation). The legacy BLAST toolkit can be used to achieve the same goal, though the command line syntax differs.

After copying the fasta file (called for example 'my_nucleotide_sequences.fasta') to the db directory of the wwwblast installation (e.g. /Users/ben/Sites/blast/db), enter the following in a terminal:

Adding the custom database to the drop-down box

To search against a custom database, it must be able to be selected from the drop-down box in blast.html. To add a database to the drop-down box, modify blast.html in a text editor, such as TextWrangler on OSX, notepad on windows, or gedit on linux. An example:

After the HTML has been modified correctly, the custom database should be able to be found when viewing the blast page with an internet browser, for example at http://localhost/blast/blast.html.

Modifying blast.rc

Without modifying the blast.rc file correctly for a given database, the following error will appear when a blast is run:

Error 9 in submitting BLAST query
Short error description:
The combination of database and program, that you provided in your
message is invalid or not acceptable by BLAST search system.
Please look at current possible combinations in BLAST help.

To fix it, change the blast.rc file, which is in the blast folder to something akin to below:

As many databases can be added space separated as required after each program.

After completing this step, you should be able to run your blast from http://localhost/blast/blast.html. It is a good idea to run a positive control. Take a section of sequence from the fasta file of the database you are blasting against, and query the database with it. A positive control is a good idea because wwwblast reporting "no hits found" can be misleading - see the troublshooting section.

Troubleshooting

A false "no hits found", where there actually the binary blast database is not in the correct place.

A true "no hits found", where the binary database is correctly configured.

No hits found

Somewhat misleadingly, if the binary databases are not in the correct place, but blast.rc is specified correctly, then wwwblast will not warn of this directly. Instead, it will display "***** no hits found *****" but not complete the web page by adding database statistics. If there really are no hits found, the statistics about the database will be displayed below. See the two contrasting pictures to the right of this text.

Missing Features of WWW-BLAST

Even when properly setup, the default installation of wwwblast has some missing features;

No access to the entire hit sequence. When the query sequence has a hit against the database, there is no way to retrieve the entire hit sequence for further analysis. This may be fixed by installing the blast_link add-on.

No security. By the methods shown above, the sequences in the database are accessible to everyone on the internet. A username and password system may be added by configuring apache basic authentication.

No dead-easy installer. If you've followed the above tutorial, you'll realise that installation of www-blast is more complicated than installing the average program. Sorry about this one folks, but there's no known fix.