Running Savane Locally

"Savane" is the name of the the server software that runs GNU Savannah.

There are several forks of Savane. The currently running version that is described here is this one.

"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 Trisquel 11 Aramo and Ubuntu 22.04.3 LTS. The system package installation requires superuser access but subsequent development and running the development server is done as a non-root user. As long as you have PHP and MariaDB then savane should work. If you don't have autoconf/automake/gettext/perl/etc, you can skip the bootstrap / configure / make steps -- the main PHP should still work, but many of the images and icons will be missing.

As of 2024, Savannah has been tested with PHP versions 5.4, 5.5, 5.6, 7.0, 7.2, 7.4, 8.0, 8.1. Newer versions have not been tested but problem reports on any issues found are appreciated. If you encounter errors, please write to savannah-hackers-public@gnu.org and tell us about it.

Note that MariaDB is the current version fork of the previous MySQL project. Most names now use the new MariaDB project naming but some files and commands continue to use the "mysql" name for compatibility. This results in the likely confusing mix of mysql and mariadb names which cannot be avoided.

Install MariaDB and other required packages on the system.

sudo apt-get install -y git autoconf automake gettext make imagemagick \
    php-cli php-mysqli mariadb-client mariadb-server

Savane makes heavy use of the SQL database to hold much of the operating parts of the web site. Everything from navigation controls to the content text displayed. Nothing can work without some type of database. The first step is to load the initial database.

In order to facilitate this a demo database has been created by trimming down a snapshot of the production database. This intrinsically has undesirable risks of exposing real data. It is desired to create a demo database from scratch using only randomly generated data. Also this trimmed down data is still a very large amount of data. It is desired that this demo data be as small as practical. Perhaps you can help with this task item? Until then we can only make this work using the current supplied demo database to seed the new system.

## Setup database account "gordon" and "savane_gordon" database.

$ sudo mysql
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 2
Server version: 10.6.12-MariaDB-0ubuntu0.22.04.1 Ubuntu 22.04

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

## Create the database.
MariaDB [(none)]> CREATE DATABASE savane_gordon CHARACTER SET utf8mb4;
Query OK, 1 row affected (0.001 sec)

## Create user and grant access privileges.  Use a different random password.
MariaDB [(none)]> GRANT ALL ON savane_gordon.* TO 'gordon'@'localhost' IDENTIFIED BY 'eXbVedcYWHydp9b5';
Query OK, 0 rows affected (0.016 sec)

MariaDB [(none)]> FLUSH PRIVILEGES;
Query OK, 0 rows affected (0.001 sec)

MariaDB [(none)]> exit;
Bye

Create a MariaDB option file in your home directory. This will set the defaults for your interactive access to the database. This contains the password and therefore should have permissions only for yourself removing group and other access permissions. Instead of "gordon" use your actual account name.

gordon:~/src/savane$ cat >~/.my.cnf <<EOF
[mysql]
database = savane_gordon
user = gordon
password = eXbVedcYWHydp9b5
EOF
chmod go-rw ~/.my.cnf

Download the initial seed database. Load the demo tables. This "mysql" command will read the ~/.my.cnf file above to use the indicated user and password and database.

$ wget https://download.savannah.nongnu.org/releases/administration/savane_demo-2022-05.sql.gz
$ zcat savane_demo-2022-05.sql.gz | mysql

For this local sandbox working copy we are going to be working in our home directory in a "$HOME/src/savane" directory.

Get Savane code. Configure. Make. Install. Run local PHP server.

mkdir -p ~/src
cd ~/src
git clone https://git.savannah.nongnu.org/git/administration/savane.git
cd savane
./bootstrap
./configure --prefix=$HOME/src/mysavannah-www --sysconfdir=$HOME/src/mysavannah-etc
make && make install

This will install files into $HOME/src/mysavannah-www and $HOME/src/mysavannah-etc directories. Those will be used to run the local working copy sandbox server.

Update the configuration file with the user name and password that were used above creating the database user. Our example used "gordan" and a random password example. In the source directory edit the ~/src/savane/local2/etc-savane/savane-dev-db.php file updating these value.

<?php
$sys_dbhost="localhost";
$sys_dbname="savane_gordon";
$sys_dbuser="gordon";
$sys_dbpasswd="eXbVedcYWHydp9b5";
?>

This breaks the paradigm of running from the install directory somewhat. All of the rest of the site is run from the $HOME/src/mysavannah-www and $HOME/src/mysavannah-etc directories but the local development "php -S" server uses the local2/local.php and associated savane-dev-db.php configuration out of the source directory. This is done so that the local.php file can be customized for local development leaving the installed files set for larger deployment as Savannah is deployed.

Start a local "php -S" server on port 127.0.0.1:7890 running in the terminal. Tracing output from local server is emitted. This terminal remains in use running the local development server. This script is a thin wrapper to act as a helper script to check for errors and to invoke the test server.

./run-local-dev.sh

By default this will listen on the localhost loopback device and not be accessible from the network. If you are developing on a different system such as a virtual machine then you might need to make this available to your web browser by binding the port to the global IP address. For development you probably do not want to make this available to the hostile Internet but if it is on a local software bridge such as with a KVM virtual machine then set the SVHOST variable to the IP address. Here is an example.

env SVHOST=93.184.216.34 ./run-local-dev.sh

Once the PHP server is started, you'll see this message, with "gordon" replaced with your home directory login name.

gordon:~/src/savane$ ./run-local-dev.sh
PHP 8.1.2-1ubuntu2.14 Development Server (http://127.0.0.1:7890) started
Listening on http://127.0.0.1:7890
Document root is /home/gordon/src/savane/frontend/php
Press Ctrl-C to quit.

Open a web browser and visit http://127.0.0.1:7890.

The Savannah website (with dummy values) should be displayed.

There is an admin user 'agn' in the demo database, with password '12345'. This is the same user as in the live Savannah and the one who originated these instructions several years ago and created the original seed database.

At this point this local server is suitable for web UI development. Don't try to use the "php -S" server for public use. For that you will need a "real" web server such as Nginx or Apache. The "php -S" server is designed for development.

Initially I strongly suggest to these changes to the Savane web UI.

  • Log in as the "agn" user password "12345".
  • Select "My Account Config".
  • Scroll down to the "Cosmetics Setup" section.
  • Set the theme to "Savannah".
  • Set the checkbox for "Use the Stone Age menu".
  • Submit the "Update" button to save these settings to the database.

The reason is that the database default settings use dropdown menus that are not generally liked by current browsers making navigation difficult. This is another excellent task item for contributors! An improved default CSS style and theme for the web site to avoid the problems is needed.

Feel free to play, to hack, to make changes, to try out things. If you produce a feature you would like to see implemented please write discussion and patches to savannah-hackers-public@gnu.org and tell us about it.

Happy Hacking!

Web Server Setup

Presently Apache has been well tested and is running the production web server on Savannah.

THESE INSTRUCTIONS HAVE NOT BEEN UPDATED FOR THE CURRENT SYSTEM YET.

Use Apache with a configuration like this:

Listen 127.0.0.1:7890 http

<VirtualHost 127.0.0.1:7890>
  ServerAdmin webmasters@test.org
  ServerName 127.0.0.1

  DocumentRoot /var/www/savane/frontend/php

  SetEnv SAVANE_CONF /var/www/etc/savane

  <Directory "/var/www/savane/frontend/php/">
    # PHP conf
    php_admin_flag register_globals off
    php_admin_flag magic_quotes_gpc off
    php_admin_flag file_uploads on

    php_admin_flag allow_url_fopen off
    # See https://lists.gnu.org/mailman/private/savannah-hackers-private/2016-September/003325.html
    # regarding 'disable_functions'.
    php_admin_value disable_functions exec,passthru,popen,shell_exec,system

    DirectoryIndex index.php index.html
  </Directory>

  <Files ~ "^(users|us|u|projects|pr|p|file)$">
    SetHandler application/x-httpd-php
  </Files>
  ErrorDocument 404 /404.php

  # Restrict access into include/
  <Directory "/var/www/savane/frontend/php/include/">
    Order Allow,Deny
    Deny from all
  </Directory>

  <Location "/register">
    php_admin_value post_max_size 52428800
    php_admin_value upload_max_filesize 52428800
  </Location>

  # Uploads for new group registrations and bug-report attachments.
  # This directory must be writable by 'www-data' user.
  # NOTE: Ensure this directory matches the '$sys_upload_dir' value
  #       in the custom savanne configuration file
  #       ($SAVANE_CONF/.savane.conf.php).
  Alias /submissions_uploads /var/www/var/www/submissions_uploads/
  <Directory "/var/www/var/www/submissions_uploads/">
    Options Indexes
    AllowOverride None

    # Disable script engines
    # Method 1:
    #ForceType application/octet-stream

    # Method 2:
    <IfModule mod_php5.c>
      # Tested with Apache2 + mod-php5
      php_admin_flag engine off
    </IfModule>
    <IfModule mod_php7.0.c>
      # Tested with Apache2 + mod-php7
      php_admin_flag engine off
    </IfModule>

    <IfModule sapi_apache2.c>
      # Not working with Apache1 + mod-php5
      php_admin_flag engine off
    </IfModule>
    <IfModule mod_perl.c>
      # Disable mod_perl
    </IfModule>
    # Disable mod_python...

    # Method 3:
    <FilesMatch ".">
      SetHandler default-handler
    </FilesMatch>
  </Directory>
  # PHP logs for development site.
  php_admin_flag log_errors on
  php_admin_flag display_errors off

  # Set error_reporting = all errors except:
  #   8192      E_DEPRECATED
  #   16384     E_USER_DEPRECATED
  # To include decperation warnings, set the value to E_ALL (32767).
  # see http://php.net/manual/en/errorfunc.constants.php .
  php_admin_value error_reporting 8191

  # NOTE: If no errors are generated at all, this file
  # will not be created (which could be confusing at first...).
  # Enable deprecation warnings (above) and the file will surely be creatred :)
  php_admin_value error_log /var/www/var/logs/i18n.php-error.log

</VirtualHost>

More Information