GENESIS: Documentation

Related Documentation:
GENESIS System

Installation on a Debian Server

This is a guide for setting up an independent version of the GENESIS software platform on a new Debain 5.0.3 installation, with the tester, code repository, and webserver running. The installation requires minimal system changes, however it is advisable to make backups of the following affected files before starting:

• /etc/apache2/apache2.conf or whatever configuration file apache uses.
• /etc/crontab which needs one line added for the cronjob.

The installation will also require some administrator access to create directories with certain user permissions.

Install the Developer Package

It is advised not to install the developer package as the root user, but instead install it as a regular user for instance with name g3tester.

Dependencies

This list is old and needs to be updated.

• Install gcc: Install gcc by executing the following command as root:

  apt-get install gcc

• Install autotools: By default, Debian usually doesn’t have development tools installed. You will need to use apt-get to install and make automake with the following commands:

  apt-get install automake         apt-get install make

• Additional Dependencies: The following additional dependencies must be installed via apt-get:
  • psmisc (for the killall command)
  • daemon (to run neurospaces_serve as a daemon process)
  • sudo
  • libncurses5-dev
  • flex
  • bison
  • swig
  • libperl-dev
  • libreadline5-dev
  • python-dev

Now perform an incomplete developer installation of GENESIS:

1. Create the correct directory layout:

   neurospaces_create_directories

2. Pull all the code from the remote repositories:

   neurospaces_pull

3. Create workspace with up to date source code:

   neurospaces_update

4. Generate make files:

   neurospaces_configure

5. Clean all workspaces: (Used when upgrading DeveloperPackage, or following a build to remove previously built files).

   neurospaces_clean

Configure the developer package

For a default installation the developer package assumes it is being used by a software developer, but for a server installation, this is not the case. Certain operations performed by the developer package sometimes require manual corrections, something not always possible on a server. The tools in the developer package need to know that these operations should not be performed.

Automated merges is one of these operations. To configure the developer package for non-automated merges, paste the following code to the configuration file with name /etc/neurospaces/developer/build.yml:

This setting prevents the server to get stuck on merge conflicts that can arise from the automated merges by the developer package. Because the server only pulls from the central repository, a merge on the server is unique to the server. The subsequents merges of the merge node or any of its descendants can give rise to merge conflicts unique to the repository on the server, and unresolvable without logging in on the server.

Setting up the Web Server

Test run output as well as generated html files from programs like Xrefactory and Doxygen need to be accessible over the internet. This is a guide to adding the Apache2 rules to set up a directory that will have its contents displayed via a http server.

Install Apache

First install Apache2 via the apt-get command as follows:

DocumentRoot

The DocumentRoot is the publicly available directory displayed when a user visits the bare URL for your server with a web browser (example: http://myserver.edu). If you want data to be available over the web, you can simply place it in the document root. If you place a file named mydata in the DocumentRoot, it will be available at the URL http://myserver.edu/mydata.

The default DocumentRoot on a debian server installation is usually “/var/www/html”. You can change the default template by editing the file:

If you want directories in another location on the machine to be displayed via the URL with a suffix see the next section.

Configuration File /etc/apache2/apache2.conf

The default http configuration file for the Apache Web Server in Debian is in the file /etc/apache2/apache2.conf. Important before starting be sure to create a backup of your configuration file. The cleanest method for declaring your Apache rules is to put all of your rules in a separate file, then add an Include statement to the default configuration file to include your file. For example:

To start your configuration file you’ll need a VirtualHost block. So the initial configuration file should look like this.

In your configuration file you will explicitly declare which directories you want served within the VirtualHost block. If you want to serve the directory /var/www/tests for test output you simply declare a block in the your configuration file for the directory and an Alias directive so that the directory can be accesible via a suffix to the URL (such as http://myserver.edu/tests). Your configuration file should end up looking like this:

For each directory you’d like to serve you must add a block and an alias. After you have updated your configuration restart Apache with this command:

The apache2ctl script comes standard with Apache 2. However if it is not present in your installation, you can restart Apache via the init script /etc/init.d/apache2 with a “restart” argument. You should now be able to view the contents of the directory /var/www/tests from your URL suffixed with your alias.

Set up the Monotone Repository Server

The GENESIS project uses monotone for its source code versioning system. The DeveloperPackage contains scripts for starting up the monotone repositories, but first some things must be set up for it to run correctly.

Install Monotone

Install monotone, it is freely available from http://monotone.ca/. Simply download the static binary and place it in your path.

Create a monotone user

It is bad practice to run a monotone repository as root so the first thing you should do is create a non-privileged user for monotone to run as. On the root shell prompt enter:

Note: If the user directory is not created, you must create it in /home via the mkdir command “mkdir /home/monotone”. You must then perform a chown to set the permissions “chown -R monotone:monotone /home/monotone”.

Setting up permissions

• Set up a server key: As the monotone user execute the command:

  mtn genkey email@address.com

  with an email address that the server can be identified with. Enter in a passphrase for it.

  The key will then be stored in the directory ~/.monotone/ and will be automatically used when the monotone user invokes any monotone command. To prevent monotone from asking for this passphrase every time it performs an action, create a file within ~/.monotone/ with the name monotonerc and put the following monotone lua function into the file:

  function get_passphrase(keypair_id)         return "my passphrase"      end

  This will give your passphrase to monotone automatically and prevent the process from stopping to ask for user input. It is advisable to protect access to the file and to use a unique password for the monotone user to prevent unauthorized users from reading this file.

Read permissions

To set who can read from the monotone repositories you serve, create the file in ~/.monotone/read_permissions. Inside this file you can set patterns to allow everyone to read all repositories, for example:

Write permissions

To set who can write to a repository create the file ~/.monotone/write_permissions. Here you simply type each email address and the identifier used when setting up your key, one line at a time.

In addition to this you must read in a public key on each monotone repository. For instructions on how to do this see the Repository Access section of the Developer Repository document.

Starting the montone repository servers

First you must have the compliant directory setup for the developer packages scripts to find the repositories to serve:

Inside the MTN directory you have repositories for each of the projects you will be serving over the web:

You can then either issue the command:

as your monotone user or you can issue the command:

as root to start the repository servers. They can now be connected too over the internet for pulls, pushes, and syncs.

Setting up the Tester

The neurospaces tester (neurospaces_cron) is a script which performs a routine check of the GENESIS repository, source code, and documentation. It is meant to be set up as a cronjob on a server with email capabilities, so that notification of a test run can be emailed to designated recipients.

When the script is set up, it ensures that errors within the system are reported in a timely fashion. This is just an overview of what needs to be done to set up the environment for the tester script to run. For more information on neurospaces_cron, such as configuration options, see the neurospaces-cron document.

Dependencies

• mailutils (for checking emails)
• exim4 (for sending emails)

Sending mail

By default Debian is configured for local mail only. To send email over the internet you will need to set the dc_eximconfig_configtype option in the file /etc/exim4/update-exim4.conf.conf from local to internet.

Then perform a restart of exim via the command:

Setting up directories

The tester script will need write access to some directories that you will be configuring via the YAML configuration file. Here are some examples of what is currently being used on the official GENESIS tester machine.

The directories /var/www/tests, /var/www/doxygen , and /var/www/regtests are all writable by the tester, and are viewable over the internet via the respective URL link. Instructions to make directories world readable via the Apache web server were previously shown in the section above titled ”Setting up the Web Server”.

Building userdocs

Dependencies

To build the user documentation you need to install LATEX and the following dependencies via the Debian installer apt-get:

• mailutils (for checking emails)
• exim4 (for sending emails)
• tetex-base
• tetex-bin
• tetex-doc (Might not need to install this as it may be included with tetex-base)
• tetex-extra
• tex4ht
• dvipng (image conversion when building the website)
• webcheck (For link checking)
• texlive-humanities is required on ubuntu based systems, it installs lineno.sty that is needed to compile some of the documents correctly.
• rst2pdf (and dependencies) is required on ubuntu based systems, it installs utilities to convert restructured text.
• unrtf (and dependencies) is required on fedora based systems, it installs utilities to convert rich text format.

For Level 6 documentation you need to install:

• Doxygen (Obtainable via ”apt-get install doxygen”)
• graphviz (If you want graphs in your Doxygen output, obtainable via ”apt-get install graphviz”).

For building regression test output you need:

• Source-highlight (obtainable via ”apt-get install source-highlight”)

The following CPAN modules for Perl must also be installed:

• HTML::Table
• HTML::Template

Package Building Dependencies

If you want to use the server to build Debian packages install the dependencies listed in the document. To make things easier, you can just copy this command:

To build RPM packages install the appropriate tools via the command:

To build either type of package you will need to install fakeroot. It can be installed with apt-get:

Server Configurations

To set the clock for the server from the command line install ntpdate via apt-get as follows:

Then execute the command:

This will sync the server to a NTP server.

Configuration

The generated image size in the html pages can be set in the tex4ht.env configuration found. On Red Hat/CentOS it is located at:

On Debian systems it is located at:

To change the image resolution you can add options to the Gconvert line in the configuration file. The flag density can have the it’s dimensions altered to produce larger images during the conversion. Here’s an example line: