[Savannah-cvs] [312] RunningSavannahLocally: major rewrite

[assafgordon]

Revision: 312
          
http://svn.sv.gnu.org/viewvc/?view=rev&root=administration&revision=312
Author:   agn
Date:     2017-02-12 00:49:12 -0500 (Sun, 12 Feb 2017)
Log Message:
-----------
RunningSavannahLocally: major rewrite

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

Modified: trunk/sviki/RunningSavaneLocally.mdwn
===================================================================
--- trunk/sviki/RunningSavaneLocally.mdwn       2017-02-06 23:21:49 UTC (rev 
311)
+++ trunk/sviki/RunningSavaneLocally.mdwn       2017-02-12 05:49:12 UTC (rev 
312)
@@ -13,179 +13,150 @@
 (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 <address@hidden> .
+The following instructions have been tested on **Debian 8 (Jessie)** and
+**Ubuntu 14.04 LTS** running as **non-root** user. Other
+configurations might not work (See below for know issues).  If you
+encounter errors, please write to <address@hidden> .
 
-For a pre-configured virtual machine with Savane, see [[SavaneInABox]].
+Use the instructions below to run the PHP code locally on your
+computer. The PHP code needs a MySQL with a pre-configured database.
+Either use our demo server, or create a local MySQL server (instructions
+for both, below).
 
-## The recipe:
-
     # Install required packages
-    sudo apt-get install apache2 libapache2-mod-php5 \
-                         mysql-server mysql-client \
-                         php5-mysql
+    sudo apt-get install -y git php5-cli php5-mysql mysql-client \
+                            imagemagick autoconf automake gettext make
 
     # 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
+    # Run required initialization
     ./bootstrap
     ./configure
+    make
 
-    # setup local demo with a stub database (one project)
-    cd local
-    make local-apache2-start
-    make local-db-setup-tiny
+    # Start local server
+    ./run-local-dev.sh
 
-Now visit <http://localhost:50080>.  
-Login with user `admin` password `admin` or `localuser` password `12345`.
+Once the PHP server is started, you'll see this message:
 
-More details follow ...
+    $ ./run-local-dev.sh
+    PHP 5.6.30-0+deb8u1 Development Server started at Sun Feb 12 00:17:54 2017
+    Listening on http://127.0.0.1:7890
+    Document root is /home/gordon/savane/frontend/php
+    Press Ctrl-C to quit.
 
-## Requirements
+Open a web browser and visit <http://127.0.0.1:7890>.
 
-The PHP frontend requires `apache2` with `php5` and `MySQL 5`.
+When you run the server for the first time, you'll see this message:
 
-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).
+    Hello Savannah Developer!
 
-On a `DEB`-based system, install the following packages:
+    It seems this is the first time you run the savane PHP code.
 
-    sudo apt-get install apache2 libapache2-mod-php5 \
-                         mysql-server mysql-client \
-                         php5-mysql
+    The code need to access a savane mock-up database.
 
-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:
+    To request access to such database, please write to
+      address@hidden
+    and ask for username/password.
 
-    sudo service apache2 stop
-    sudo service mysql stop
-    sudo update-rc.d apache2 remove
-    sudo update-rc.d mysql remove
+    Once you receive them, please edit the following file
+    (locally on your computer):
 
+       /home/gordon/savane/local2/etc-savane/savane-dev-db.php
 
-## Local Savane Components
+    Set the hostname, database, username and password,
+    then reload the website.
 
-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
+Send us an email to <address@hidden>,
+introduce yourself and ask for access to our demo MySQL server.
+We'll send you (privately) the following information:
 
-The `Makefile` in `./local/` offers the following commands:
+    $sys_dbhost="demo.database.foobar.org";
+    $sys_dbname="savane_XXXXXX";
+    $sys_dbuser="XXXXXXX";
+    $sys_dbpasswd="XXXXXXXXXX";
 
-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.
+Paste the above values in the indicated file
+(e.g. `/home/gordon/savane/local2/etc-savane/savane-dev-db.php` above).
 
-`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.
+Reloading the savannah web page on your local web browser should
+now 'just work' and display the savannah website (with dummy values).
 
-`local-db-setup-*` should be run once, to populate the database.
+There is just one project in the demo database: `site-administration`.
+There is one user in the database: `admin` (password `admin`).
 
-`local-db-delete` should be used before re-running `local-db-setup-*` to reset
-the database (or try a different snapshot).
+Each volunteer developer will get a dedicated copy of the demo
+database, so adding/removing/updating information and creating projects
+will not interfere with other developers.
 
+## Supported PHP versions
 
-## Troubleshooting
+Savannah currently requires **php version 5.4, 5.5 or 5.6**.
+Earlier versions will not work locally (the script requires `php
+-S`). Newer versions (**php 7.0**) fail to run some of savane's old
+code (fixes and patches are *very* welcomed).
 
-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.
+## Other environments/distributions
 
-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).
+As long as you have PHP 5.4/5.5/5.6 with MySQL, savane should mostly
+work.  If you don't have `autoconf/automake/gettext/perl/etc`, you can
+even skip the `bootstrap / configure / make` steps - the main PHP
+should still work, but many of the images and icons will be missing.
 
-Possible errors when visiting <http://localhost:50080>:
+On Fedora-25, these are the relevant packages:
 
-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`.
+    sudo dnf -y install git automake autoconf gettext make \
+                            ImageMagick php-cli php-mysqlnd \
+                            community-mysql perl-ExtUtils-MakeMaker
 
-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` .
+However Fedora25 moved to PHP-7.0, and so the code won't "just work".
+(If you want to help adjusting savannah's PHP code to PHP-7.0, this
+will be a good way to start).
 
-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` .
+## Running local MySQL demo database
 
-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.
+If you prefer to run a local MySQL server, the following guidelines
+should work (but YMMV):
 
-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.
 
+    # Download a snapshot of the demo database:
 
-See [[FrontEndDebuggingTips]] for log files and PHP debugging tips.
\ No newline at end of file
+    $ wget 
https://download-mirror.savannah.gnu.org/releases/administration/savane_demo-2017-02-12.sql.gz
+    $ sha256sum savane_demo-2017-02-12.sql.gz
+    78ddffc7eddcaace1e4539bf9f0753ad5489362824658c8e60ae8e9e8d214bf1
+
+    # Create a new MySQL database
+    $ echo "CREATE DATABASE savane_demo;" | mysql
+
+    # Load the demo tables
+    $ zcat savane_demo-2017-02-12.sql.gz | mysql savane_demo
+
+    # Create a demo user
+    $ echo "grant SELECT on savane_demo.* TO 'USER'@'%' IDENTIFIED by 
'PASSWORD';" | mysql savane_demo
+    $ echo "grant insert,update,select,delete on savane_demo.* to 'USER'@'%';" 
| mysql savane_demo
+
+Set `USER` and `PASSWORD` above to your desired values.
+
+Then update the configuration file with your local values
+(e.g. `/home/gordon/savane/local2/etc-savane/savane-dev-db.php` above):
+
+    $sys_dbhost="localhost";
+    $sys_dbname="savane_demo";
+    $sys_dbuser="USER";
+    $sys_dbpasswd="PASSWORD";
+
+
+## More Information
+
+* [[FrontEndDebuggingTips]] for log files and PHP debugging tips.
+* [This 
Message](https://lists.gnu.org/archive/html/savannah-hackers-public/2016-09/msg00009.html)
+  for a tour of the configurable 'site-specific-content'.
+  In your local savannah instance the files are in
+  `./savane/etc/site-specific-content`.
+* [[FrontEndSetup]] - how the same PHP code is configured on
+  savannah's servers.
\ No newline at end of file