Running Savane Locally - howto

"Savane" is the code name for the server software that runs GNU Savannah, among other things.

"Savane" has many parts. This page describes a method to run a locally copy of Savane frontend PHP part on your computer.

"Savane" is an old, delicate beast and is quick to anger. Tread lightly and send questions to savannah-hackers-public@gnu.org (archive: http://lists.gnu.org/archive/html/savannah-hackers-public/).

The following instructions have been tested on Debian 7, running as non-root user. Other configurations might not work. If you encounter errors, please write to savannah-hackers-public@gnu.org .

For a pre-configured virtual machine with Savane, see SavaneInABox.

The recipe:

# Install required packages
sudo apt-get install apache2 libapache2-mod-php5 \
                     mysql-server mysql-client \
                     php5-mysql

# Get Savane code
git clone git://git.sv.gnu.org/administration/savane.git
cd savane
# Use known working revision
# (newer revisions have not been tested, but might work)
git checkout 7d4703de

# Get and apply patches to run locally
wget -O sv-local-run.patch.xz 'https://savannah.gnu.org/support/download.php?file_id=32220'
xzcat sv-local-run.patch.xz | git am

# Prepare Savane
./bootstrap
./configure

# setup local demo with a stub database (one project)
cd local
make local-apache2-start
make local-db-setup-tiny

Now visit http://localhost:50080.
Login with user admin password admin or localuser password 12345.

More details follow ...

Requirements

The PHP frontend requires apache2 with php5 and MySQL 5.

This demo will run as non-root user, there is no need to setup anything globally (in /etc/). The apache and mysql servers do not need to be otherwise running on your server (this demo will configure and run them as a normal user).

On a DEB-based system, install the following packages:

sudo apt-get install apache2 libapache2-mod-php5 \
                     mysql-server mysql-client \
                     php5-mysql

NOTE: installing the above package will setup Apache2/MySQL servers to run by default on your computer. If you do not to run them by default, use the following command:

sudo service apache2 stop
sudo service mysql stop
sudo update-rc.d apache2 remove
sudo update-rc.d mysql remove

Local Savane Components

  1. Apache2:
    1. configuration: ./local/apache2/conf/apache2.conf
    2. Listens on 127.0.0.1:50080 .
    3. logs: ./local/apache2/logs/{access,error}.log
    4. pid file ./local/apache2/pid
    5. quick start: cd local ; make local-apache2-start
    6. quick stop: cd local ; make local-apache2-stop
  2. MySQL:
    1. database directory ./local/db/
    2. Listens on Unix socket: ./local/db/sock
    3. database name: savane
    4. Database content: based on chosen setup:
      1. tiny - one stub project (siteadmin)
  3. PHP:
    1. Code is in ./frontend/php/*
    2. Apache Setup in ./local/apache2/conf/apache2.conf points to ./frontend/php.
    3. Hidden config file in ./local/savane/.savane.conf.php contains local demo configuration values.
    4. Apache Setup in ./local/apache2/conf/apache2.conf points to ./local/savane/.savane.conf.php.

Make commands

The Makefile in ./local/ offers the following commands:

  1. local-apache2-start - Creates apache2 configuration (based on template file ./local/apache2/conf/apache2.conf.template), and starts the apache2 process as the current user.
  2. local-apache2-stop - Stops the running apache2 process (based on PID file ./local/apache2/pid).
  3. local-db-start - Starts the MySQL server process as the current user. Initializes database directory ./local/db if it doesn't already exist - in which case the database will be empty.
  4. local-db-stop - Stops the MySQL server process.
  5. local-db-delete - Stops the MySQL server (if it was running), then deletes the database directory (./local/db/). Use this command before setting-up a new database (see below).
  6. local-db-setup-tiny - Creates a new database, and populates it with a stup project called siteadmin (from ./db/mysql/*.sql). When this command completes, the MySQL server is running.
  7. local-db-cli - runs the command-line interface (mysql) to the database. Allows running SQL commands directly.

local-apache2-start, local-apache2-stop, local-db-start and local-db-stop are safe to run repeatedly. They start/stop the servers as the current (non-root) user.

local-db-setup-* should be run once, to populate the database.

local-db-delete should be used before re-running local-db-setup-* to reset the database (or try a different snapshot).

Troubleshooting

Possible errors when configuring the system:

  1. Error: MySQL-Server failed to start. after make local-db-start
    Check the file ./local/db/debian76.err for possible hints. One reason might be running as root - this setup was tested as non-root user.

  2. apache2: Configuration error: No MPM loaded after make local-apache2-start2
    The current settings work well with the apache version on Debian 7 (Apache2 version 2.2.22). Other versions (especially 2.4.X) might require slightly different settings. Please write to savannah-hackers-public@gnu.org and we'll try to help you troubleshoot this error (likely involves adding a LoadModule statement in the apache configuration file).

Possible errors when visiting http://localhost:50080:

  1. Connection Rejected or Page not found - The apache2 server is not running.
    Try cd local ; make local-apache2-start.
    Try netstat -ntlp | grep 50080.
    Check ./local/apache2/logs/error_log.

  2. Failed to connect to Database: Can't connect to local MySQL server through socket... - The mysql server is not running.
    Try cd local ; make local-db-start .
    Try cd local ; make local-db-cli .

  3. Failed to connect to Database: Unknown database "savane" - The mysql server is running, but the database has not been created.
    Try cd local ; make local-db-setup-tiny

  4. db_query: SQL query error Table 'savane.groups' doesn't exist in [SELECT group_id FROM groups ...] - The mysql server is running, but database "savane" is empty (or some critical tables don't exist).
    This can happen if a database setup process failed half-way through.
    Try cd local ; make local-db-delete && make local-db-setup-tiny .

  5. Savannah Loads, but a red error is shown: Your $sys_unix_group_name configuration variables refers to a non-existing project.
    The file ./local/savane/.savane.conf.php has a variable named $sys_unix_group_name, which must contain the name of a existing, valid project in the database.
    When using the tiny database setup, this name is siteadmin.
    If something went wrong during automatic setup, this field might be invalid - Fix it manually.

  6. Internal Server Error, and the log file ./local/apache2/logs/error_log contains errors such as ./savane/frontend/php/.htaccess: ErrorDocument not allowed here:
    This error is likely due to differences in apache versions (the tested version is Apache 2.2.20). Please write to savannah-hackers-public@gnu.org and we'll try to help you troubleshoot this error.

See FrontEndDebuggingTips for log files and PHP debugging tips.