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.
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.
This list is old and needs to be updated.
apt-get install gcc
apt-get install automake
apt-get install make
Now perform an incomplete developer installation of GENESIS:
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.
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.
First install Apache2 via the apt-get command as follows:
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.
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:
Options +FollowSymLinks Indexes MultiViews
allow from all
Alias /tests /var/www/tests/
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.
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, it is freely available from http://monotone.ca/. Simply download the static binary and place it in your path.
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”.
mtn genkey email@example.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:
return "my passphrase"
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.
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:
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.
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:
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.
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.
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:
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”.
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:
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
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:
This will sync the server to a NTP server.
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:
Gconvert -crop 0x0 -density 500x500 -geometry 25% -transparency ’#FFFFFF’ tex4ht.ps %%3