[Savannah-cvs] [231] FrontEndDevelopmentSite: expand, update directory structure

[assafgordon]

Revision: 231
          
http://svn.sv.gnu.org/viewvc/?view=rev&root=administration&revision=231
Author:   agn
Date:     2016-09-25 01:25:16 +0000 (Sun, 25 Sep 2016)
Log Message:
-----------
FrontEndDevelopmentSite: expand, update directory structure

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

Modified: trunk/sviki/FrontEndDevelopmentSite.mdwn
===================================================================
--- trunk/sviki/FrontEndDevelopmentSite.mdwn    2016-09-24 04:53:26 UTC (rev 
230)
+++ trunk/sviki/FrontEndDevelopmentSite.mdwn    2016-09-25 01:25:16 UTC (rev 
231)
@@ -8,7 +8,7 @@
 Development websites will have URLs such as
 <https://jsmith.frontend0.sv.gnu.org>.
 The PHP code will be hosted in each developer's home directory,
-(e.g. `frontend0:/home/jsmith/projects/savane/`).
+(e.g. `frontend0:/home/jsmith/savannah/savane/`).
 
 See also: [[FrontEndSetup]], [[SavannahHosts]].
 
@@ -83,21 +83,44 @@
     ERROR 1044 (42000): Access denied for user 
'jsmith'@'frontend0.savannah.gnu.org' to database 'savane'
 
 
+Step 3: Setup direcotries
+-------------------------
 
+The development site use dedicated directories,
+to ease development and troubleshooting.
 
-Step 3: PHP frontend code
+    cd /home/jsmith
+    mkdir savannah
+
+    # dev-site savane's php configuration
+    mkdir savannah/etc
+
+    # apache's access+error+php logs
+    mkdir savannah/var/logs
+
+    # uploads (for project registration)
+    mkdir savannah/submissions_uploads
+
+Ensure the directories are writable by `www-data`
+(run as root):
+
+    # cd /home/jsmith/savannah/var
+    # chgrp www-data logs submissions_uploads
+    # chmod g+w logs submissions_uploads
+
+
+Step 4: PHP frontend code
 -------------------------
 
 Clone the savane repository
 
-    cd /home/jsmith
-    mkdir projects ; cd projects
+    cd /home/jsmith/savannah
     git clone git://git.sv.gnu.org/administration/savane.git
 
 The current PHP code (the same code running on the existing/old 'frontend')
 is few old PHP constructs. Few patches are required to make it run on modern
 PHP installations. The updated repository is available in
-`frontend0:/home/agn/projects/savane`, or can be downloaded here:
+`frontend0:/home/agn/savannah/savane`, or can be downloaded here:
 `wget -O sv-local-run.patch.xz 
'https://savannah.gnu.org/support/download.php?file_id=32220'`
 
 FIXME: push these to `savane.git` repository (if not in 'master', then at least
@@ -107,7 +130,7 @@
 copy for local installation (be sure to read below for warnings and
 notes about this 'installation'):
 
-    cd savane
+    cd /home/jsmith/savannah/savane
     ./bootstrap
     ./configure --prefix=$HOME/savane-usr
     make
@@ -173,15 +196,83 @@
    to know which content files are installed/needed.
 
 
+Step 5: Savannah's dev-site configuration files,content
+-------------------------------------------------------
 
-Step 4: Apache configuraion
+The PHP code reads the configuration from a `.savane.conf.php` file,
+in a directory defined by `SAVANE_CONF` in the apache configuration
+file (see below).
+
+For the development site, the files will be stored in
+`/home/jsmith/savannah/etc/savane`.
+
+The configuration for the production site are in
+`/etc/savane`.
+
+Copy the configuration files from the production website,
+and update ownership and permissions (as root):
+
+    cd /home/jsmith/savannah/
+    cp -r /etc/savane ./etc/
+    chown -R jsmith:jsmith ./etc
+    chgrp www-data ./etc/.savane.conf.php ./etc/savane.pass
+
+*NOTE*: At this point, the files contain the MySQL user/password
+for the production website - DO NOT FORGET TO CHANGE THEM.
+The following settings must be updated:
+
+    $ cd /home/jsmith/savannah/etc/savane
+    $ grep '_db' .savane.conf.php
+    $sys_dbhost="208.118.235.78";
+    $sys_dbname="savane_jsmith";
+    $sys_dbuser="jsmith";
+    $sys_dbpasswd=rtrim(file_get_contents(dirname(__FILE__).'/savane.pass'));
+
+    $ cat savane.pass
+    XXXXXX
+
+    $ cat savane.ini
+    [database]
+    HOST=208.118.235.78
+    USER=jsmith
+    PASSWORD=XXXXXXXX
+    NAME=savane_jsmith
+
+The following settings should also be updated in `.savane.conf.php`:
+
+    $sys_default_domain="jsmith.frontend0.savannah.gnu.org";
+    $sys_brother_domain="jsmith.frontend0.savannah.nongnu.org";
+    $sys_incdir="/home/jsmith/savannah/etc/savane/content/gnu-content";
+    $sys_name="Savannah-jsmith-DEV";
+    $sys_upload_dir="/home/jsmith/savannah/var/submissions_uploads/";
+
+
+The outcome should look like:
+
+    $ cd /home/jsmith/savannah/etc/savane
+    $ ls -la
+    total 168
+    drwxr-xr-x 5 jsmith jsmith        4096 Sep  5 22:00 .
+    drwxrwxr-x 5 jsmith jsmith        4096 Jul 27 23:30 ..
+    -rwxr-x--- 1 jsmith www-data      1616 Sep  5 21:58 .savane.conf.php
+    -rw-r--r-- 1 jsmith jsmith      123540 Jul 27 23:30 cgitrepos
+    drwxr-xr-x 5 jsmith jsmith        4096 Jul 27 23:30 content
+    drwxr-xr-x 2 jsmith jsmith        4096 Jul 27 23:30 nongnu-conf
+    -rwxr-x--- 1 jsmith jsmith        8533 Sep  5 22:00 savane.conf.pl
+    -rw-r----- 1 jsmith jsmith          90 Sep  5 21:59 savane.ini
+    -rw-r----- 1 jsmith www-data        25 Sep  5 21:58 savane.pass
+    drwxr-xr-x 2 jsmith jsmith        4096 Jul 27 23:30 test-conf
+
+
+
+Step 6: Apache configuraion
 ---------------------------
 
 Create a separate apache configuration file:
 `frontend0:/etc/apache2/sites-available/sv-jsmith-dev.conf`
 A symlink should exist in:
 `frontend0:/etc/apache2/sites-enabled/sv-jsmith-dev.conf`
-(See example in `/etc/apache2/sites-available/sv-agn-dev.conf`.)
+(A good starting point is  `/etc/apache2/sites-available/sv-agn-dev.conf`.)
 
 ### Hostnames
 
@@ -194,7 +285,6 @@
     ServerAlias jsmith.frontend0.sv.nongnu.org
 
 
-
 ### SSL Certificates
 
 The apache configuration file includes an `alias` to certbot's
@@ -235,20 +325,35 @@
 
 The PHP code is served from the savane git repository directory:
 
-    DocumentRoot /home/jsmith/projects/savane/frontend/php
+    DocumentRoot /home/jsmith/savanne/savane/frontend/php
 
 
-
 ### Savane's PHP configuration
 
 In this apache config file, an environment variable `SAVANE_CONF` should
 point to the development site's configuration directory
-(e.g. `frontend0:/home/jsmith/projects/savane-etc`).
+(e.g. `frontend0:/home/jsmith/savannah/etc/savane`).
 
-    SetEnv SAVANE_CONF /home/jsmith/projects/savane-etc/
+    SetEnv SAVANE_CONF /home/jsmith/savannah/etc/savane/
 
+*Sanity checks when visiting <https://jsmith.frontend0.savannah.gnu.org>*
 
+1. Take note of the <TITLE> of the page (usually appears in the title
+   of the web-browser or the open tab).
+   It should say "Welcome [Savannah-jsmith-DEV]" which corresponds
+   to the `$sys_name` variable in
+   `/home/jsmith/savannah/etc/savane/.savane.conf.php`.
+   If it says anything else, the PHP code for this development site
+   is not reading the correct configuration file - check your
+   apache configuration.
+   If it says "Welcome [Savane]", it is likely reading the default
+   configuration file from `/etc/savane/.savane.conf.php`.
+2. If you see a red "error" box at the top of the page saying:
+   'Warning: Savane was not able to read "" site-specific
+   information, please contact administrators' it likely means
+   the `$sys_incdir` variable points to an invalid directory.
 
+
 ### Password-protection
 
 This is a development website, not meant for public consumption.
@@ -263,64 +368,22 @@
         Require valid-user
     </Location>
 
+### Upload directory
 
+Update the upload directory alias with:
 
-PHP db/user/pw configuration
-----------------------------
+    Alias /submissions_uploads /home/jsmith/savannah/var/submissions_uploads/
+    <Directory "/home/jsmith/savannah/var/submissions_uploads/">
+      [...]
+    </Directory>
 
-The PHP code reads the configuration from a `.savane.conf.php` file,
-in a directory defined by `SAVANE_CONF` in the apache configuration
-file (see above). Example: `frontend0:/home/jsmith/projects/savane-etc`.
 
-The files are based on the production configuration directory in
-`frontend0:/etc/savane`.
+### Apache logs
 
-The files contain the db/user/pw for the development website:
+Update the location of the log files to write them
+to the developer's directory:
 
-    $ cd /home/jsmith/projects/savane-etc
-    $ grep '_db' .savane.conf.php
-    $sys_dbhost="208.118.235.78";
-    $sys_dbname="savane_jsmith";
-    $sys_dbuser="jsmith";
-    $sys_dbpasswd=rtrim(file_get_contents(dirname(__FILE__).'/savane.pass'));
-
-    $ cat savane.pass
-    XXXXXX
-
-    $ cat savane.ini
-    [database]
-    HOST=208.118.235.78
-    USER=jsmith
-    PASSWORD=XXXXXXXX
-    NAME=savane_jsmith
-
-Other relevant settings for the development site:
-
-    $ cd /home/jsmith/projects/savane-etc
-    $ cat .savane.conf.php
-    $sys_brother_domain="jsmith.frontend0.savannah.nongnu.org";
-    $sys_incdir="/home/jsmith/projects/savane-etc/content/gnu-content";
-    $sys_name="Savannah-jsmith-DEV";
-
-The PHP code runs from apache as user `www-data`.
-The configuration directory must allow `www-data` to read the files.
-
-    $ cd /home/jsmith/projects/savane-etc
-    $ chgrp www-data .savane.conf.php savane.pass
-
-The outcome should look like:
-
-    $ cd /home/jsmith/projects/savane-etc
-    $ ls -la
-    total 168
-    drwxr-xr-x 5 jsmith jsmith        4096 Sep  5 22:00 .
-    drwxrwxr-x 5 jsmith jsmith        4096 Jul 27 23:30 ..
-    -rwxr-x--- 1 jsmith www-data      1616 Sep  5 21:58 .savane.conf.php
-    -rw-r--r-- 1 jsmith jsmith      123540 Jul 27 23:30 cgitrepos
-    drwxr-xr-x 5 jsmith jsmith        4096 Jul 27 23:30 content
-    drwxr-xr-x 2 jsmith jsmith        4096 Jul 27 23:30 nongnu-conf
-    -rwxr-x--- 1 jsmith jsmith        8533 Sep  5 22:00 savane.conf.pl
-    -rw-r----- 1 jsmith jsmith          90 Sep  5 21:59 savane.ini
-    -rw-r----- 1 jsmith www-data        25 Sep  5 21:58 savane.pass
-    drwxr-xr-x 2 jsmith jsmith        4096 Jul 27 23:30 test-conf
-
+    # Apache Logs for development site
+    CustomLog /home/jsmith/savannah/var/logs/agn.access.log combined
+    ErrorLog /home/jsmith/savannah/var/logs/agn.error.log
+    php_admin_value error_log /home/jsmith/savannah/var/logs/agn.php-error.log