[Savannah-cvs] [99] Added RunningSavaneLocally page

[Assaf Gordon]

Revision: 99
          http://svn.sv.gnu.org/viewvc/?view=rev&root=administration&revision=99
Author:   agn
Date:     2014-10-04 00:33:28 +0000 (Sat, 04 Oct 2014)
Log Message:
-----------
Added RunningSavaneLocally page

Modified Paths:
--------------
    trunk/sviki/FrontPage.mdwn

Added Paths:
-----------
    trunk/sviki/RunningSavaneLocally.mdwn

Modified: trunk/sviki/FrontPage.mdwn
===================================================================
--- trunk/sviki/FrontPage.mdwn  2014-10-02 23:51:58 UTC (rev 98)
+++ trunk/sviki/FrontPage.mdwn  2014-10-04 00:33:28 UTC (rev 99)
@@ -179,6 +179,7 @@
         -   [[GeoIP]]
 
     -   [[Nagios]]
+    -   [[RunningSavaneLocally]]
 
 -   [[SavannahTeam]]
     -   [[RecruitingVolunteers]]

Added: trunk/sviki/RunningSavaneLocally.mdwn
===================================================================
--- trunk/sviki/RunningSavaneLocally.mdwn                               (rev 0)
+++ trunk/sviki/RunningSavaneLocally.mdwn       2014-10-04 00:33:28 UTC (rev 99)
@@ -0,0 +1,204 @@
+# GNU Savane - Local Demo
+
+"Savane" is the code name for the server project running
+[GNU Savannah](http://savannah.gnu.org).
+
+* Project's page: <http://savannah.gnu.org/projects/administration>
+
+"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 <address@hidden>
+(previous discussions at:
+<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 <address@hidden> .
+
+## TL;DR;
+
+    # 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`.
+
+## 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
+even need to be running on your server (this demo will configure
+and run them as 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 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 <address@hidden> 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
+    <address@hidden> and we'll try to help you
+    troubleshoot this error.
+
+## PHP Debugging
+
+1. In the `./local/savane/.savane.conf.php` file, set (or uncomment)
+    `$sys_debug_on=true`.  
+    This option will add to the bottom of every rendered HTML page the
+    list of all SQL commands with source code information,
+    and all POST/GET/COOKIES values.  
+
+    In the code you want to debug, call `util_debug("hello world");` to add
+    this message to the debug information at the bottom of the page.
+
+    To print a variable, call `util_debug(print_r($VAR,TRUE));`.
+
+2. The apache error log `./local/apache2/logs/error_log` will contain the
+    `STDERR` from PHP.
+
+    In the php code, call `error_log("hello world");` to send this message to 
STDERR.
+
+    To print a variable, call `error_log(print_r($VAR,TRUE));`.
+
+    Then monitor the error log with `tail -f ./loval/apache2/logs/error_log`.