savannah-cvs
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

[Savannah-cvs] [744] Update instructions for current systems


From: bob
Subject: [Savannah-cvs] [744] Update instructions for current systems
Date: Wed, 10 Jan 2024 05:43:15 -0500 (EST)

Revision: 744
          
http://svn.savannah.gnu.org/viewvc/?view=rev&root=administration&revision=744
Author:   rwp
Date:     2024-01-10 05:43:14 -0500 (Wed, 10 Jan 2024)
Log Message:
-----------
Update instructions for current systems

These instructions were tested on Trisquel 11 Aramo running PHP 8.1
and MariaDB 10.6.

Reworked to improve the clarity and simplify the instructions.

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

Modified: trunk/sviki/RunningSavaneLocally.mdwn
===================================================================
--- trunk/sviki/RunningSavaneLocally.mdwn       2024-01-08 09:18:53 UTC (rev 
743)
+++ trunk/sviki/RunningSavaneLocally.mdwn       2024-01-10 10:43:14 UTC (rev 
744)
@@ -1,10 +1,15 @@
 # Running Savane Locally
 
-"Savane" is the code name for the server software that runs
-[GNU Savannah](//savannah.gnu.org), among other things.
+"Savane" is the name of the the server software that runs
+[GNU Savannah](//savannah.gnu.org).
 
 * 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.
+
+* <https://git.savannah.nongnu.org/cgit/administration/savane.git/>
+
 "Savane" has many parts. This page describes a method to run
 a locally copy of Savane **frontend PHP part** on your computer.
 
@@ -13,137 +18,207 @@
 (archive:
 <http://lists.gnu.org/archive/html/savannah-hackers-public/>).
 
-The following instructions have been tested on **Debian 8 (Jessie)** and
-**Ubuntu 22.04.3 LTS** running as **non-root** user. Other
-configurations might not work (see below for know issues).  If you
-encounter errors, please write to <savannah-hackers-public@gnu.org> .
+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.
 
-Use the instructions below to run the PHP code locally on your
-computer. The PHP code needs a MySQL with a pre-configured database.
-Create a local MySQL server:
+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.
 
-    # Install required packages.
-    sudo apt-get install -y git php-cli php-mysqli mysql-client mysql-server \
-      imagemagick autoconf automake gettext make
+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.
 
-    # Get Savane code.
-    git clone https://git.savannah.nongnu.org/git/administration/savane.git
-    cd savane
+Install MariaDB and other required packages on the system.
 
-    # Run required initialization.
-    ./bootstrap
-    ./configure --prefix=`pwd`/../savane-prefix --sysconfdir=`pwd`/../etc
-    make && make install
+    sudo apt-get install -y git autoconf automake gettext make imagemagick \
+        php-cli php-mysqli mariadb-client mariadb-server
 
-    # Start local server.
-    ./run-local-dev.sh
+On Fedora-25 these are the package names.
 
-Once the PHP server is started, you'll see this message:
+    sudo dnf -y install git automake autoconf gettext make ImageMagick \
+        php-cli php-mysqlnd community-mysql perl-ExtUtils-MakeMaker
 
-    $ ./run-local-dev.sh
-    PHP 7.2.24-0ubuntu0.18.04.15 Development Server started at Mon Jan  2 
09:36:24 2023
-    Listening on http://127.0.0.1:7890
-    Document root is /home/gordon/savane/frontend/php
-    Press Ctrl-C to quit.
+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.
 
-Open a web browser and visit <http://127.0.0.1:7890>.
+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.
 
-When you run the server for the first time, you'll see this message:
+    ## Setup database account "gordon" and "savane_demo" database.
 
-    Hello Savannah Developer!
+    $ 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
 
-    It seems this is the first time you run the savane PHP code.
+    Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.
 
-    Savane need to access a savane mock-up database.
+    Type 'help;' or '\h' for help. Type '\c' to clear the current input 
statement.
 
-    Once you receive it, please edit the following file
-    (locally on your computer):
+    ## Create the database.
+    MariaDB [(none)]> CREATE DATABASE savane_demo CHARACTER SET utf8mb4;
+    Query OK, 1 row affected (0.001 sec)
 
-       /home/gordon/savane/local2/etc-savane/savane-dev-db.php
+    ## Create user and grant access privileges.  Use a different random 
password.
+    MariaDB [(none)]> GRANT ALL ON savane_demo.* TO 'gordon'@'localhost' 
IDENTIFIED BY 'eXbVedcYWHydp9b5';
+    Query OK, 0 rows affected (0.016 sec)
 
-    Set the hostname, database, username and password,
-    then reload the website.
+    MariaDB [(none)]> FLUSH PRIVILEGES;
+    Query OK, 0 rows affected (0.001 sec)
 
-Download and import savane_demo dump:
+    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.
+
+    gordon:~/src/savane$ cat >~/.my.cnf <<EOF
+    [mysql]
+    database = savane_demo
+    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.
+
     $ wget 
https://download.savannah.nongnu.org/releases/administration/savane_demo-2022-05.sql.gz
+    $ zcat savane_demo-2022-05.sql.gz | mysql savane_demo
 
-    ## Setup database account USERNAME and savane_demo database:
+For this local sandbox working copy we are going to be working in our
+home directory in a "$HOME/src/savane" directory.
 
-    $ sudo mysql -p
-    Enter password:
-    Welcome to the MySQL monitor.  Commands end with ; or \g.
-    Your MySQL connection id is 2
-    Server version: 5.7.40-0ubuntu0.18.04.1 (Ubuntu)
+Get Savane code.  Configure.  Make.  Install.  Run local PHP server.
 
-    Copyright (c) 2000, 2022, Oracle and/or its affiliates.
+    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
 
-    Oracle is a registered trademark of Oracle Corporation and/or its
-    affiliates. Other names may be trademarks of their respective
-    owners.
+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.
 
-    Type 'help;' or '\h' for help. Type '\c' to clear the current input 
statement.
+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.
 
-    ## Create a database user.
-    ## Set `USERNAME` and `PASSWORD` to your desired values.
+    $sys_dbhost="localhost";
+    $sys_dbname="savane_demo";
+    $sys_dbuser="gordon";
+    $sys_dbpasswd="eXbVedcYWHydp9b5";
 
-    mysql> CREATE USER 'USERNAME'@'localhost' IDENTIFIED by 'PASSWORD';
-    Query OK, 0 rows affected (0.01 sec)
+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.
 
-    mysql> create database savane_demo;
-    Query OK, 1 row affected (0.00 sec)
+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.
 
-    mysql> GRANT ALL ON savane_demo.* TO 'USERNAME'@'localhost';
-    Query OK, 0 rows affected (0.01 sec)
+    ./run-local-dev.sh
 
-    mysql> quit;
-    Bye
+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.
 
-    ## Load the demo tables
-    $ zcat savane_demo-2022-05.sql.gz | mysql --user USERNAME savane_demo -p
-    Enter password:
+    env SVHOST=93.184.216.34 ./run-local-dev.sh
 
-Then update the configuration file with your local values
-(e.g. `/home/gordon/savane/local2/etc-savane/savane-dev-db.php` above):
+Once the PHP server is started, you'll see this message, with "gordon"
+replaced with your home directory login name.
 
-    $sys_dbhost="localhost";
-    $sys_dbname="savane_demo";
-    $sys_dbuser="USERNAME";
-    $sys_dbpasswd="PASSWORD";
+    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.
 
-Reloading the Savannah web page on your local web browser should
-now 'just work' and display the Savannah website (with dummy values).
+Open a web browser and visit <http://127.0.0.1:7890>.
 
-There is an admin user 'agn' in the demo database, with password '12345'.
+The Savannah website (with dummy values) should be displayed.
 
-With MySQL 5.7 and later, be sure to exclude ONLY_FULL_GROUP_BY
-from sql_mode e.g. in my.cnf.
+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.
 
-Please ensure to disable SQL strict mode if you encounter an error such as 
"Field doesn't have a default value." This adjustment is essential for smooth 
operation.
+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.
 
-## Supported PHP versions
+Initially I strongly suggest to these changes to the Savane web UI.
 
-As of 2023, Savannah requires **PHP version 5.4, 5.5, 5.6, 7.0, 7.2, 7.4, 8.0
-8.1**.  Newer versions aren't tested.
+* 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.
 
-## Other environments
+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.
 
-As long as you have PHP 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.
+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.
 
-On Fedora-25, these are the relevant packages:
+Happy Hacking!
 
-    sudo dnf -y install git automake autoconf gettext make \
-                            ImageMagick php-cli php-mysqlnd \
-                            community-mysql perl-ExtUtils-MakeMaker
+## Web Server Setup
 
-However Fedora25 moved to PHP-7.0, and so the code didn't "just work".
+Presently Apache has been well tested and is running the production
+web server on Savannah.
 
-Some features still may not work.  Use Apache with a configuration
-like this:
+**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
 
@@ -180,13 +255,11 @@
     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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]