/** INSTALL - a document to answer the question of "How do I install Anthill?" **/ /** Part of the Anthill Bug Manager distribution **/ Note: For those who are impatient and have a solid grasp on how to use MySQL and Perl on their system, grab CGI::SecureState, DBI, and DBD::mysql from CPAN and run 'configure.pl'. Report back here if you have problems. If you do not run 'configure.pl', Anthill will not run. Contents: This document answers the following questions: 1. What do I need before I begin to install? 2. How do I install Anthill? 3. What if that way doesn't work? 4. How do I uninstall Anthill? 1. What do I need before I begin to install? Since Anthill has several dependencies, you might want to install them before the install script complains loudly at you. It also simplifies the installation procedure if you know the questions that the install script will ask you before you actually run it. Part I: Software required. Software packages that are necessary: MySQL - a popular and speedy database server, available from www.mysql.com. Perl - a popular programming language, available from www.perl.com. Any web server with CGI or PERL capabilities - you may use any reasonable web server with Anthill, but the Apache web server is recommended due to its acceleration and caching of Perl scripts. It is available from www.apache.org and the mod_perl package is available from perl.apache.org. Standard Perl modules that are necessary: All Perl distributions should come with these, so you are most likely covered already: CGI: A module that greatly eases the pain of writing CGI scripts. Exporter: A module that greatly eases the pain of writing Perl modules that export symbols to other namespaces. File::Spec: A module that greatly eases the pain of writing scripts that portably use filenames. File::Copy: A module that copies and moves files around. (Only used in the installer script). Fcntl: Provides a portable way to specify the type of lock when locking files. There are also some additional Perl modules that are necessary. You may find these on CPAN if you use a UNIX or VMS-based system, with the Perl Package Manager if you use a MS Windows-based system, or CPAN+MPW if you are using a non-UNIX-based version of Mac OS. They are: Digest::SHA1: A module for calculating message digests (think MD5 but longer and more secure). Crypt::Blowfish: A module for encryption using the Blowfish cipher. CGI::SecureState: A module that maintains session information between CGI scripts. DBI: A module that allows easy and portable access to databases via Perl. DBD::mysql: A driver module for DBI that allows access to MySQL databases. Please note that for this module, it is a recent phenomenon that any/all of the test scripts seem to fail despite the fact that the module still works perfectly. If you suspect that it is the test scripts' fault (in this instance, this is normally the case), then you may force the install anyway (for users of CPAN, it is usually a simple "make install" in the source directory of the package). Apache::Registry: This is a strictly optional module that is only useful if you want the full speed of Anthill under the Apache web server. The recommended way to get this module is in a pre-built package for your operating system (usually called mod_perl or apache-mod_perl), but if you decide to compile it yourself, you should visit perl.apache.org to get it. perl.apache.org also has full details on how to set up a working mod_perl configuration. Part II: Information required. The configure.pl script will ask you several questions about your setup and will check to make sure that you have all the necessary Perl modules installed. If you are missing one, you may optionally download it within the script using CPAN. This is generally only a good idea if you are using a UNIX or VMS-based system, so if you aren't lucky enough to have one of those, make sure you read Part I thoroughly. Most of the questions that the script will ask will be self-explanatory. The script will ask you if: 1) You want to use Apache::Registry: (Default: no) Answer 'yes' if you know what this is and have it, or 'no' if you do not. 2) You want to allow anonymous submission and searching of bugs: (Default: no) If you want to let the commons submit bugs to your project and look through your list of bugs, then say 'yes' here. All the bugs that the public submits will have a priority of 'unconfirmed' and a status of 'unconfirmed' so that a developer must confirm them as real bugs before useful things happen. A developer login is required to do anything beyond submitting and searching bugs. 3) You want to use a different database than MySQL: (Default: no) This is a highly unsupported feature in Anthill. It may even be a bug. If you are crazy enough to want to use Oracle, for example, then we will not stop you, but we offer no guarantees that Anthill will even run. If you are foolish enough to answer 'yes' here, then you will have to specify the exact name of the DBD driver for your database at the next prompt. If you say 'yes' by accident, you may save yourself by entering 'mysql' at the next prompt. 4) Your database is on another machine: (Default: no) If your database server is separate from your web server, then you will get a prompt where you can specify the name or IP address of that server if you say 'yes' here. You will also have to specify the name/IP address of the web server, so that the correct access permissions may be granted. The script will then ask you for: 5) A name for the bugs database that does not conflict with other databases that you may have: (Default: bugs) If the 'bugs' database (you were running BugZilla, weren't you!) is already taken, or you have a more descriptive name, you should enter that here. 6) A user for the bugs database that does not conflict with other users that you currently have: (Default: bugs) If a 'bugs' user already has an account on your MySQL database, then, by all means, put a different name here. 7) A non-empty password for this user: (No default) You will have to rack your brains to think up a non-empty string of characters that you won't have to remember. How hard is that? Note that this password will be not be stored as plain text on your computer, and thus cannot be retrieved without human intervention. 8) A user (with an optional password) with restricted access to the databases: (Default depends on question 2) This user will be used by the Anthill authentication module to access the password information of the developers. In addition, if you allowed anonymous access to the databases, this will be the login that Anthill uses when it receives anonymous requests. 9) A response on whether you want the database administrator's e-mail address revealed when there is a database problem: (Default: yes) If you answer 'yes' to this question, then you will be asked to provide the database administrator's e-mail address, which will be used as contact information should a database command return a critical error. 10) A location to install the Anthill scripts (Default: /var/www/perl/Anthill if you have Apache::Registry, /var/www/cgi-bin/Anthill otherwise) You should put a reasonable location for the scripts here if you do not like the default. 11) The name of this path relative to the root directory of the webserver (Default depends on response to question 10) You should respond with the relative path to the program scripts. For example, if you used the default in the last question, and you do not have Apache::Registry, you can access Anthill at http://127.0.0.1/cgi-bin/Anthill. So, for this question, you should answer '/cgi-bin/Anthill', which is the default response. 12) A location to install the Anthill HTML files (Default depends on your response to question 10) You should respond with the directory where you want Anthill's static HTML and image files to go. The default is usually acceptable. 13) The name of this path relative to the root directory of the webserver (similar to question 11) This exactly parallels question 11. The default should be a reasonable answer, but if you know better, then say so to the install script. 14) A response on whether you want the "states" directory readable only by the web server: (Default: yes) If you have a filesystem that supports permissions (most notably not FAT16, FAT32, HFS, or HFS+), then you can restrict access to the session information files created every time a user logs in. These are encrypted by CGI::SecureState, but it is usually a good idea to protect them anyway. If you say 'yes' here, you will be asked for the username that the web server runs as (usually 'apache', 'nobody' or 'root') and the install script will make the session files only accessible by the web server (Note that this requires root privileges to do so). 15) A response on whether you want the configuration script to install the "AnthillDirectories.pm" file in a place where Perl can find it without external help: (Default: yes) Several web servers do not run scripts in their own directories so that when it comes time for Anthill to include some of its modules, the web server will return with an error page and a message in its logs about Perl not being able to find "AnthillConfig.pm", "AnthillDirectories.pm", "XMLTemplate.pm" or "AnthillAuth.pm". Saying "yes" here fixes this problem by installing "AnthillDirectories.pm" in a place that Perl knows about so that it can change the working directory of the script to the correct location. You should say "yes" here unless you know better. The script will then thank you for having answered all these questions. 2) How do I install Anthill? You should run the configuration script "configure.pl" from the command-line in the directory where you unpacked the Anthill source files. The configuration script will pester you with questions (See Part II of Question 1), and will then write the configuration file that Anthill requires to run. If you have gotten this far and make a mistake with the rest of the installation, you may skip the questions by running 'configure.pl --continue' and you will be asked to re-enter the password that you specified for the user with privileged database access. The script will proceed to install the Anthill files, creating directories as needed. The configuration script then needs to set up the MySQL database. If you didn't select an alternative database type, it can do this for you. You will need to have a user with administrative privileges whose username is not 'root'. If you do not have one of these, then you can enter in the commands that it prints out manually with the mysql client. If you do have such a user, then you will be asked for login information, and if all goes well, the script will automatically set up your databases for you. If you did select a different database type, then you will not only have to enter the commands manually, but you will have to translate them to work with your own non-MySQL database. If all goes well, you should have a working Anthill install! You may access the anonymous scripts directly from the Anthill installation directory (search.pl and new.pl), and you may access the rest of Anthill through the admin directory (admin/login.pl). For example, if you entered "/perl/Anthill" as the response to "Where will this be with respect to the root directory of your webserver?" after you responded to the question "Where should I install the Anthill program files?", then you can access the anonymous scripts at http://my.web.server/perl/Anthill/search.pl and http://my.web.server/perl/Anthill/new.pl and log in at http://my.web.server/perl/Anthill/login.pl 3) What if that way doesn't work? You should contact us immediately. While we are thinking about how to respond, you may do the installation manually. You absolutely MUST run the configure.pl script to get a working Anthill install, but you only need to answer the questions up to the point where it thanks you and says it has all the information it needs. Make sure that you say 'no' to the question about changing permissions. You should then copy all the files in the 'src' directory to the place where you specified that the program files should go and you should copy all the files in the 'html' directory to the place where you specified that the html files should go. Then, run the program in the 'docs' subdirectory called 'database_settings.pl' to get a listing of what you should do to set up the Anthill databases. Finally, if your webserver requires it, copy the file 'AnthillDirectories.pm' to a place in the default @INC array of Perl (which you may find by running perl -e 'print join(", ", @INC), "\n";' (Using appropriate quotes for your operating system)). With a little bit of luck, you may still get Anthill to run. 4) How do I uninstall Anthill? By running the 'uninstall.pl' script. Read the UNINSTALL file first, however. Note: Wherever the name "Anthill" is mentioned in this document, it refers to the Anthill Bug Manager. If other projects, things, people, or fuzzy green mittens coincidentally bear the name "Anthill", it is assumed that the reader can divine from the context of this document that only the Anthill Bug Manager is being referred to. If not, that is what this note is for.