[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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Savannah-cvs] [744] Update instructions for current systems,
bob <=