Copyright (C) 1999, 2000 The SourceForge Crew
Copyright (C) 2000-2006 Mathieu Roy
Copyright (C) 2014, 2016, 2017 Assaf Gordon
Copyright (C) 2001-2011, 2013, 2017 Sylvain Beucler
Copyright (C) 2013, 2014, 2017-2026 Ineiev

This file is part of Savane.

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.

This document describes a sample Savane installation procedure using an initial
database.  It was tested on Trisquel 8 to 11.  For more details and options,
you may want to look into Savannah wiki (https://savannah.gnu.org/maintenance/).
The commands are run from an ordinary (non-root) account unless in the 'Advanced
and troubleshooting' section where it's specifically noted otherwise.

Preparing the system
--------------------

Install dependencies listed in README.  If you are going to use localizations,
make sure the languages are listed when running locale -a (in Trisquel,
look for language-pack-*; for more info, see doc/i18n).

Getting a release
------------------

Download the latest tarball and its signature:

  $ wget \
    https://download.savannah.nongnu.org/releases/administration/savane-latest.tar.gz{.sig,}
  ...

You can also get the tarballs of any release with their signatures from
https://download.savannah.nongnu.org/releases/administration/; the names
of the tarballs follow the convention savane-RELEASE.NUMBERS.tar.gz.

Download and import Savane release keyring:

  $ wget -O savane.asc \
    'https://savannah.nongnu.org/project/release-gpgkeys.php?group=administration&download=1'
  ...
  $ gpg --import savane.asc
  ...

As an alternative, you can get the public key from a keyserver:

  $ gpg --recv-key BD9D4DEE7B2FF1CBEF2EE0C4E0ACD3E0CBE7874A
  ...
  gpg: key E0ACD3E0CBE7874A: public key "Ineiev (fencepost) <ineiev@gnu.org>" imported
  gpg: Total number processed: 1
  gpg:               imported: 1

Verify and unpack the tarball:

  $ gpg --verify savane-latest.tar.gz{.sig,} && tar xzf savane-latest.tar.gz
  gpg: Signature made Thu 29 Feb 2024 03:37:07 PM UTC
  gpg:                using RSA key BD9D4DEE7B2FF1CBEF2EE0C4E0ACD3E0CBE7874A
  gpg: Good signature from "Ineiev (fencepost) <ineiev@gnu.org>" [unknown]
  gpg:                 aka "Павел Харитонов <ineiev@gnu.org>" [unknown]
  gpg: WARNING: This key is not certified with a trusted signature!
  gpg:          There is no indication that the signature belongs to the owner.
  Primary key fingerprint: BD9D 4DEE 7B2F F1CB EF2E  E0C4 E0AC D3E0 CBE7 874A

Bootstrapping Git sources
-------------------------

If you want something more recent than a released tarball, you are to use
our Git repository.

Clone Savane to $HOME/sv:

  $ mkdir ~/sv && cd ~/sv \
    && git clone https://git.savannah.nongnu.org/git/administration/savane.git
  git clone https://git.savannah.nongnu.org/git/administration/savane.git
  Cloning into 'savane'...
  remote: Counting objects: 14454, done.
  remote: Compressing objects: 100% (3394/3394), done.
  remote: Total 14454 (delta 10514), reused 14454 (delta 10514)
  Receiving objects: 100% (14454/14454), 20.82 MiB | 1.57 MiB/s, done.
  Resolving deltas: 100% (10514/10514), done.

If you have a Savannah account, you an authenticated access may work better
for you (replace <account> with your user name),

  git clone <account>@git.savannah.nongnu.org:/srv/git/administration/savane.git

Checkout the commit you need, e.g.

  $ git checkout -b i18n origin/i18n

Regenerate the configure script and other parts of the build system:

  $ cd savane; autoreconf -vi
  autoreconf: Entering directory `.'
  ...
  autoreconf: Leaving directory `.'

Basic installation
------------------

In this case, a full database directory tree will be created in user's home
directory.  This works starting with Trisquel 10 (it comes with MariaDB 10.3.39
and MySQL 8.0.41); for older releases, see the 'Advanced and troubleshooting'
section.

Make a build directory and change the current working directory to it:

  $ mkdir build && cd build

Configure the package (replace SAVANE_SRC with the path to the top directory
of the tree containing Savane sources):

  $ SAVANE_SRC/configure --prefix=$HOME/sv/install
  checking for a BSD-compatible install... /usr/bin/install -c
  ...
  Now you can run
    make all install installcheck
  to install and check the package.

Build, install and check:

  $ make all install installcheck
  Making all in etc
  make[1]: Entering directory '/home/dti/sv/savane/etc'
  ...
  make[2]: Nothing to be done for 'install-data-am'.
  make[2]: Leaving directory '/home/dti/sv/savane'
  make[1]: Leaving directory '/home/dti/sv/savane'
  ...

Launch database daemon:

  $ $HOME/sv/install/sbin/sv_launch_db.pl

Start web server:

  $ $HOME/sv/install/sbin/sv_frontendctl -k start

Visit <http://127.0.0.85:4913/testconfig.php>, look for errors.

At this point, it should work: visit <http://127.0.0.85:4913>,
login as '-' using password '-'; that user is the initial administrator.

In order to shut down the servers, run

  $ $HOME/sv/install/sbin/sv_frontendctl -k stop
  $ $HOME/sv/install/sbin/sv_kill_db

Files attached in the trackers will be served from <http://127.0.0.86:4913>.

Adding sample database
----------------------

When configured with --enable-sample-db, non-administrator users
'alice', 'bob', 'carol', 'dave', 'eve' are added, with the same
password '-'.

Database: advanced and troubleshooting
--------------------------------------

The procedure above installs a complete instance of database server
data in user's home directory.  That avoids the need for running
any commands with root privileges, but the amount of server data
may exceed 100 MB, and typically that would duplicate already
initialized system-wide data.  Moreover, Savane database server
initialization is known to fail with older MySQL versions like 5.7.

The database can be installed in the system area, but that means invoking
the database client from the root account or at least using the root database
account.  Also, the database daemon is likely to start when the OS boots,
so you needn't run sv_launch_db.pl.

First, add --disable-database and --enable-db-networking to Savane
configure options; also, you may want to customize the database
name, user and password:

Write a file with database password in form 'password=*PASSWORD*'.

  $ ../savane/configure --prefix=$HOME/sv/install \
    --disable-database --enable-db-networking --with-db-user=sv \
    --with-db-credentials=PASSWD_FILE --with-db-name=sv_demo

where PASSWD_FILE is path to the file you've filled.

Build and install as usual:

$ make all install

Create database user account from the root account or use database root
account:

  $ sudo mysql < db/mk-db.sql

or

  $ mysql --user=root --password < db/mk-db.sql

Initialize database:

  $ mysql --user=sv --password sv_demo < ../savane/db/initial.sql

Optionally install sample entries:

  $ mysql --user=sv --password sv_demo < ../savane/db/sample.sql

Configuring GnuPG-signed tracker notifications
----------------------------------------------

See doc/signed-notifications.

Configuring follow-up comments via email
----------------------------------------

See doc/comments-via-email.

Configuring internationalization
--------------------------------

See doc/i18n.

Running *.gnu.org with *.nongnu.org at the same server
------------------------------------------------------

See doc/twin.
