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:

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.

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:

---  
no_automated_merges: 1

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:

apt-get apache2

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:

/etc/apache2/sites-available

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:

   Include /etc/apache2/my.conf

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

   NameVirtualHost *:80  
   <VirtualHost *:80>  
   </VirtualHost>

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:

   NameVirtualHost *:80  
   <VirtualHost *:80>  
      <Directory /var/www/tests>  
         Options +FollowSymLinks Indexes MultiViews  
         AllowOverride All  
         order allow,deny  
         allow from all  
      </Directory>  
      Alias /tests /var/www/tests/  
   </VirtualHost>

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:

   apache2ctl restart

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:

   useradd monotone -b /home/monotone

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

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:

   pattern "*"  
      allow "*"

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:

   ~/neurospaces_project/MTN

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




developer.mtnmodel-container.mtnstudio.mtn



gshell.mtn ns-sli.mtn userdocs.mtn



heccer.mtn ssp.mtn



You can then either issue the command:

   nohup neurospaces_serve &

as your monotone user or you can issue the command:

   sudo -H -u monotone nohup neurospaces_serve &

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

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:

   /etc/init.d/exim4 restart

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.

OUTPUTDIR: /var/www/tests  
URL: http://repo-genesis3.cbi.utsa.edu/tests  
DOXYGENOUTPUT: /var/www/doxygen  
DOXYGENURL: http://repo-genesis3.cbi.utsa.edu/doxygen  
REGTESTOUTPUT: /var/www/regtests  
REGTESTURL: http://repo-genesis3.cbi.utsa.edu/regtests

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:

For Level 6 documentation you need to install:

For building regression test output you need:

The following CPAN modules for Perl must also be installed:

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:

apt-get install dh-make dpkg-dev dpkg

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

apt-get install rpm

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

apt-get install fakeroot

Server Configurations

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

apt-get install ntpdate

Then execute the command:

/etc/network/if-up.d/ntpdate

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:

/usr/share/texmf/tex4ht/base/unix/tex4ht.env

On Debian systems it is located at:

/usr/share/texmf/tex4ht/tex4ht.env

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:

Gconvert -crop 0x0 -density 500x500 -geometry 25% -transparency  ’#FFFFFF’ tex4ht.ps %%3