Running Savane Locally
"Savane" is the name of the the server software that runs GNU Savannah.
- Project page: http://savannah.gnu.org/projects/administration
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
- FrontEndDebuggingTips for log files and PHP debugging tips.
- FrontEndSetup - how the same PHP code is configured on Savannah servers.