[Savannah-cvs] [770] update documentation on Savane setup

[ineiev]

Revision: 770
          
http://svn.savannah.gnu.org/viewvc/?view=rev&root=administration&revision=770
Author:   ineiev
Date:     2024-02-24 12:16:36 -0500 (Sat, 24 Feb 2024)
Log Message:
-----------
update documentation on Savane setup

Modified Paths:
--------------
    trunk/sviki/FrontEnd.mdwn
    trunk/sviki/FrontEndSetup.mdwn
    trunk/sviki/SavaneReleases.mdwn
    trunk/sviki/back-page.mdwn

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

Modified: trunk/sviki/FrontEnd.mdwn
===================================================================
--- trunk/sviki/FrontEnd.mdwn   2024-02-24 15:29:50 UTC (rev 769)
+++ trunk/sviki/FrontEnd.mdwn   2024-02-24 17:16:36 UTC (rev 770)
@@ -1,7 +1,7 @@
 # Savannah frontend
 
 The Savane frontend is installed on the 'frontend' virtual machine, in
-`/opt/savannah/savane/`, which pulls from the `administration/savane.git`
+`/opt/savane/`, which pulls from the `administration/savane.git`
 repository.
 
 See also: [[Savannah Frontend Setup|FrontEndSetup]]

Modified: trunk/sviki/FrontEndSetup.mdwn
===================================================================
--- trunk/sviki/FrontEndSetup.mdwn      2024-02-24 15:29:50 UTC (rev 769)
+++ trunk/sviki/FrontEndSetup.mdwn      2024-02-24 17:16:36 UTC (rev 770)
@@ -1,4 +1,4 @@
-# Savannah Frontend Setup
+# Savannah frontend setup
 
 This page describes the configuration needed for Savannah
 new frontend web server and PHP code.
@@ -7,16 +7,15 @@
 kicking off the server migration efforts. The existing server
 (which hosts <http://savannah.gnu.org>) is called `frontend`
 (`frontend.savannah.gnu.org`). The new server is currently
-called `frontend0` (<https://frontend0.savannah.gnu.org>).
+called `frontend2` (<https://frontend2.savannah.gnu.org>).
 
 Further reading about Savannah server:
 
-* [[SavannahArchitecture]] - overview of the current ('old') setup
-  (i.e. vcs0, mgt0, frontend0, internal0, download0).
+* [[SavannahArchitecture]] - overview of the current setup
+  (i.e. vcs, mgt, frontend, internal, download).
 * [[SavannahServices]] - services/daemons available on Savannah hosts.
 * [[SavannahInternals]] - Savannah inner-workings.
-* [[SavannahHosts]] - Configuration of the new servers
-  (i.e. mgt0, vcs0, frontend0, internal0, download0).
+* [[SavannahHosts]] - Configuration of the new servers.
 
 Further reading about Savannah web frontend:
 
@@ -24,7 +23,6 @@
 * [[FrontEnd]] - Notes about the current frontend setup.
 * [[FrontEndDevelopmentSite]] - Setting up development sites for Savannah.
 
-
 ## General information
 
 Savannah web frontend (i.e. <https://savannah.gnu.org>)) is written in PHP.
@@ -36,43 +34,16 @@
 write-access: `git clone
 <USER>@git.sv.gnu.org:/srv/git/administration/savane.git`).
 
-As of September 2016, 'savane' is not 'installed' in a standard way
-(e.g. 'make install').  Instead, files and settings are copied
-from old servers (e.g. the old
-VM of 'frontend.sv.gnu.org' to the new VM 'frontend0').  The MySQL
-database is not created from scratch, but is copied from existing
-servers (e.g. DB on internal to internal0).  The configuration files
-(e.g `/etc/savane` or the local copy in `/home/foobar/projects/savane-etc`)
-are copied from existing servers, and tweaked until they 'just work'.
+The production machine run the head of the 'frontend'
+branch, see [[Releasing Savane|SavaneReleases]].
 
-The PHP code runs directly from the cloned and configured repository
-(i.e. if cloned into `$HOME/projects/savane`, Apache PHP configuration
-should point to `$HOME/projects/savane/frontend/php/`).
-`config.status --config` output may look like
-`'--prefix=/home/user/projects/' '--sysconfdir=/home/user/etc'`.
-The 'installation' above does not touch the PHP part.  When
-updating translations is needed, run 
+For details on how Savane is installed, see [[Savane setup|SavaneSetup]].
 
-   cd savane/po; make savane.pot-update update-po all install
-   git reset --hard
+## Apache/PHP configuration file location
 
-Generally, the production machines run the head of the master
-or i18n branch (see [[Releasing Savane|SavaneReleases]]).
-
-The current production website is <https://savannah.gnu.org>
-and is hosted on the 'old' VM (`frontend.sv.gnu.org`).
-
-The new production website is <https://frontend0.savannah.gnu.org>,
-and is hosted on the 'new' VM (`frontend0.sv.gnu.org`).
-The PHP code is in `frontend0:/usr/srv/savane`.
-The configuration is in `frontend0:/etc/savane`.
-
-
-## Apache/PHP Configuration File Location
-
 The environment variable `SAVANE_CONF` determines the location of the main
 PHP configuration file for savane. It could be set in Apache configurations
-file (`frontend0:/etc/apache2/sites-available/sv.inc`) or in an `.htaccess`
+file (`frontend2:/etc/apache2/sites-available/sv.inc`) or in an `.htaccess`
 file (`/usr/src/savane/frontend/php/.htaccess`) with
 `SetEnv SAVANE_CONF /etc/savane`
 

Modified: trunk/sviki/SavaneReleases.mdwn
===================================================================
--- trunk/sviki/SavaneReleases.mdwn     2024-02-24 15:29:50 UTC (rev 769)
+++ trunk/sviki/SavaneReleases.mdwn     2024-02-24 17:16:36 UTC (rev 770)
@@ -1,48 +1,46 @@
 # Releasing Savane
 
+## Releases for the Translation Project
+
+We do release tarballs in the [download area of the `administration`
+group](//download.savannah.nongnu.org/releases/administration/).
+These releases serve as references for the Translation Project
+where our UI is localized.  Nonetheless, we do make efforts to ensure
+that the tarballs look like real releases and e.g. can successfully
+pass distcheck.
+
+In the same area, we may also release auxiliary files like dumps of sample
+Savane database.
+
 ## Working branches
 
 [Our Savane
 repository](//git.savannah.gnu.org/cgit/administration/savane.git)
-has two permanent branches:
+has three permanent branches:
 <dl>
 <dt>master</dt>
-<dd>This is the "stable" branch: it doesn't accept non-fast-forward commits,
-it is the base for all other branches.</dd>
+<dd>The "stable" branch: it doesn't accept non-fast-forward commits,
+it is used as the base for all other branches.</dd>
 <dt>i18n</dt>
-<dd>This is where next development commits occur.  The commits may
-be amended in this branch until they are absorbed in the master
-branch.</dd>
+<dd>The branch where the development is done.  The commits are amended
+in this branch until they are absorbed in the master branch.</dd>
+<dt>frontend</dt><dd>The branch the frontend runs.</dd>
 </dl>
 
-When no development is going on, our production machines run
-in sync with head of the master branch.  When working on new
-features, the relevant machines may run the head of i18n
-(that is, where the head were at some specific moment).
-Since the AGPL requires that we provide
-the corresponding source code for frontend code, Savane links
-to the respective commit at our git server (the "Corresponding source code"
-link at the bottom of the page).  This implies that no uncommitted
-changes should be made in the running code on `frontend`&mdash;any
-modifications should come through Git.
+## Corresponding source code for specific machines
 
-Other machines where the users interact with Savane are the VCS servers
-and the download server.  For them, the source code of Savane is provided
-through RSYNC, which is one of the protocols offered for downloading
-the hosted data.
+The requirement of the AGPL to offer the corresponding source code
+is triggered in these cases:
 
-## Releases for the Translation Project
+- The PHP code of Savannah Web UI.  Savane links to the respective commit
+  at our Cgit instance (the "Corresponding source code" link at the bottom
+  of the page).  Keeping the frontend branch at the specific commit makes sure
+  that it is accessible and git gc doesn't remove it.
+- The sv_membersh script for SSH access, namely, VCS servers
+  and the download server.  The source code of Savane is provided
+  through RSYNC, which is one of the protocols offered for downloading
+  the hosted data.
 
-We do release tarballs in the [download area of the `administration`
-group](//download.savannah.nongnu.org/releases/administration/).
-These releases serve as references for the Translation Project
-where our UI is localized.  Nonetheless, we do make efforts to ensure
-that the tarballs look like real releases and e.g. can successfully
-pass distcheck.
-
-In the same area, we may also release auxiliary files like dumps of sample
-Savane database.
-
 ---
 
 Copyright &copy; 2024 Ineiev

Added: trunk/sviki/SavaneSetup.mdwn
===================================================================
--- trunk/sviki/SavaneSetup.mdwn                                (rev 0)
+++ trunk/sviki/SavaneSetup.mdwn        2024-02-24 17:16:36 UTC (rev 770)
@@ -0,0 +1,71 @@
+# Savane setup
+
+As of 2024-02, Savane is installed and runs on mgt1, download0,
+vcs0, vcs1, vcs2, frontend2.  The installation procedure
+is quite uniform.
+
+The bootstrapped Git repository is located at /opt/src/savane;
+the package is built in /root/build-savane/build.
+/root/build-savane has a link savane-bootstrapped pointing at
+/opt/src/savane.
+
+The configuration is maintained in /etc/savane: either Savane is
+configured with `--sysconfdir=/etc`, or /opt/savane/etc/savane
+contain links to the files from /etc/savane.
+
+Basic steps to update Savane after logging in as root
+the machine in question are:
+
+  cd ~/build-savane/savane-bootstrapped; git fetch origin
+  git diff --color=always HEAD origin/frontend
+  git reset --hard origin/frontend; autoreconf -vf
+  cd ~/build-savane/build; make all install{,check}
+
+Additional steps the admin does in certain cases are:
+
+- Check the command line of configure,
+
+    ~/build-savane/build/config.status --config
+
+  and add new options.
+
+- Backup the previous installation,
+
+    rm -fr /opt/savane~
+    cp -a /opt/savane{,~}
+
+- Update configuration files in /etc/savane.  When Savane is installed,
+  the existing configuration files are kept unchanged.
+
+## Common settings
+
+The existing database from the 'internal' VM is used, so the
+--disable-database configure option should be used.
+
+## Machine specifics
+
+### frontend
+
+The only machine where --disable-frontend and --enable-changelog
+are *not* used.
+
+### vcs
+
+The offer from sv_membersh suggests an rsync option that omits the '.git'
+directory, so --enable-changelog is used as a way to list the changes made
+in original software.
+
+### download
+
+In addition to --enable-changelog discussed in the preivous section,
+the configure script runs with --mirror-enabled, that switches on
+mirror-redirect and other mirror-related scripts.
+
+---
+
+Copyright &copy; 2024 Ineiev
+
+Copying and distribution of this file, with or without modification,
+are permitted in any medium without royalty provided the copyright
+notice and this notice are preserved.  This file is offered as-is,
+without any warranty.

Modified: trunk/sviki/back-page.mdwn
===================================================================
--- trunk/sviki/back-page.mdwn  2024-02-24 15:29:50 UTC (rev 769)
+++ trunk/sviki/back-page.mdwn  2024-02-24 17:16:36 UTC (rev 770)
@@ -185,6 +185,7 @@
 - [[Tips on communications|CodeOfConduct]]
 - [[How Savannah data are archived|Backup]]
 - [[A few words about our database schema|SavannahDatabaseSchema]]
+- [[How Savane is updated|SavaneSetup]]
 
 ### Download